docs: comparison function improvement

Author: vincentarelbundock

R/comparisons.R

@@ -68,11 +68,9 @@
 #' + [subset()] call with a single argument to select a subset of the dataset used to fit the model, ex: `newdata = subset(treatment == 1)`
 #' + [dplyr::filter()] call with a single argument to select a subset of the dataset used to fit the model, ex: `newdata = filter(treatment == 1)`
 #' @param comparison How should pairs of predictions be compared? Difference, ratio, odds ratio, or user-defined functions.
-#' * string: shortcuts to common contrast functions.
-#'   - Supported shortcuts strings: `r toString(names(marginaleffects:::comparison_function_dict))`
-#'   - See the Comparisons section below for definitions of each transformation.
+#' * string: shortcuts to common contrast functions. Supported shortcuts strings: `r toString(names(marginaleffects:::comparison_function_dict))`
 #' * function: accept two equal-length numeric vectors of adjusted predictions (`hi` and `lo`) and returns a vector of contrasts of the same length, or a unique numeric value.
-#'   - See the Transformations section below for examples of valid functions.
+#' * See the "Comparison functions" section below for a list of common transformations and the definitions of available shortcuts.
 #' @param transform string or function. Transformation applied to unit-level estimates and confidence intervals just before the function returns results. Functions must accept a vector and return a vector of the same length. Support string shortcuts: "exp", "ln"
 #' @param equivalence Numeric vector of length 2: bounds used for the two-one-sided test (TOST) of equivalence, and for the non-inferiority and non-superiority tests. For bayesian models, this report the proportion of posterior draws in the interval and the ROPE. See Details section below.
 #' @param by Aggregate unit-level estimates (aka, marginalize, average over). Valid inputs:

man-roxygen/comparison_functions.R

@@ -1,13 +1,25 @@
-#' @section comparison argument functions:
-#'
-#' The following transformations can be applied by supplying one of the shortcut strings to the
-#' `comparison` argument.
-
-#' `hi` is a vector of adjusted predictions for the "high" side of the
-#' contrast. `lo` is a vector of adjusted predictions for the "low" side of the
-#' contrast. `y` is a vector of adjusted predictions for the original data. `x`
-#' is the predictor in the original data. `eps` is the step size to use to
-#' compute derivatives and elasticities.
+#' @section Comparison functions:
+#'
+#' Each of the quantities computed by `comparisons()` can be defined as a function of these quantities:
+#'
+#' - `hi`: vector of predictions for the "high" side of the contrast. 
+#' - `lo`: vector of predictions for the "low" side of the contrast. 
+#' - `y`: predictions for the original data. 
+#' - `x`: focal predictor in the original data.
+#' - `w`: weights
+#'
+#' For example, the "lift" of a binary predictor is a popular quantity of
+#' interest, defined as the difference between predictions when the focal
+#' predictor \eqn{X = 1}, and predictions when the focal predictor is
+#' \eqn{X = 0}, normalized by the starting point. Or:
+#'
+#' \eqn{\frac{\hat{Y}_{X=1} - \hat{Y}_{X=0}}{\hat{Y}_{X=0}}}
+#'
+#' When, the argument is set to `comparison="lift"`, `marginaleffects` will compute the quantity using this function:
+#'
+#' `function(hi, lo) { (hi - lo) / lo }`
+#'
+#' Users can supply custom functions to the `comparison` argument, or use one of the many shortcuts available for common quantities of interest:
 #'
 #' ```{r, echo = FALSE, results = "asis"}
 #' k <- marginaleffects:::comparison_function_dict