Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
vincentarelbundock committed Sep 11, 2023
1 parent 75e7999 commit 713a370
Showing 18 changed files with 41 additions and 57 deletions.
5 changes: 1 addition & 4 deletions R/marginal_means.R
Original file line number Diff line number Diff line change
@@ -21,10 +21,7 @@
#' type, but will typically be a string such as: "response", "link", "probs",
#' or "zero". When an unsupported string is entered, the model-specific list of
#' acceptable values is returned in an error message. When `type` is `NULL`, the
#' default value is used. This default is the first model-related row in
#' the `marginaleffects:::type_dictionary` dataframe. If `type` is `NULL` and
#' the default value is "response", the function tries to compute marginal means
#' on the link scale before backtransforming them using the inverse link function.
#' first entry in the error message is used by default.
#' @param wts character value. Weights to use in the averaging.
#' + "equal": each combination of variables in `newdata` gets equal weight.
#' + "cells": each combination of values for the variables in the `newdata` gets a weight proportional to its frequency in the original data.
6 changes: 1 addition & 5 deletions R/predictions.R
Original file line number Diff line number Diff line change
@@ -14,9 +14,6 @@
#' * <https://marginaleffects.com/>
#'
#' @rdname predictions
#' @details
#' For `glm()`, `MASS::glm.nb`, `gam::gam()`, and `feols::feglm` models with `type`, `transform` and `hypothesis` all equal to `NULL` (the default), `predictions()` first predicts on the link scale, and then backtransforms the estimates and confidence intervals. This implies that the `estimate` produced by `avg_predictions()` will not be exactly equal to the average of the `estimate` column produced by `predictions()`. Users can circumvent this behavior and average predictions directly on the response scale by setting `type="response"` explicitly. With `type="response"`, the intervals are symmetric and may have undesirable properties (e.g., stretching beyond the `[0,1]` bounds for a binary outcome regression).
#'
#' @param model Model object
#' @param variables Counterfactual variables.
#' * Output:
@@ -59,8 +56,7 @@
#' type, but will typically be a string such as: "response", "link", "probs",
#' or "zero". When an unsupported string is entered, the model-specific list of
#' acceptable values is returned in an error message. When `type` is `NULL`, the
#' default value is used. This default is the first model-related row in
#' the `marginaleffects:::type_dictionary` dataframe. See the details section for a note on backtransformation.
#' first entry in the error message is used by default.
#' @param transform A function applied to unit-level adjusted predictions and confidence intervals just before the function returns results. For bayesian models, this function is applied to individual draws from the posterior distribution, before computing summaries.
#'
#' @template deltamethod
3 changes: 1 addition & 2 deletions R/slopes.R
Original file line number Diff line number Diff line change
@@ -53,8 +53,7 @@
#' type, but will typically be a string such as: "response", "link", "probs",
#' or "zero". When an unsupported string is entered, the model-specific list of
#' acceptable values is returned in an error message. When `type` is `NULL`, the
#' default value is used. This default is the first model-related row in
#' the `marginaleffects:::type_dictionary` dataframe.
#' first entry in the error message is used by default.
#' @param slope string indicates the type of slope or (semi-)elasticity to compute:
#' - "dydx": dY/dX
#' - "eyex": dY/dX * Y / X
4 changes: 2 additions & 2 deletions book/articles/predictions.qmd
Original file line number Diff line number Diff line change
@@ -178,7 +178,7 @@ pred <- predictions(modlin)
mean(pred$estimate)
```

Note that in GLM models with a non-linear link function, the predictions are first made on the link scale, averaged, and then back transformed. Thus, the average prediction may not be exactly identical to the average of predictions:
Note that in GLM models with a non-linear link function, the default `type` is `linkinv(link)`. This means that predictions are first made on the link scale, averaged, and then back transformed. Thus, the average prediction may not be exactly identical to the average of predictions:

```{r}
mod <- glm(vs ~ hp + am, data = mtcars, family = binomial)
@@ -224,7 +224,7 @@ predictions(
summarize(AAP = mean(estimate))
```

Note that the two results are exactly identical when we specify `type="response"` explicitly. However, they will differ slightly when we leave `type` unspecified, because `marginaleffects` will then automatically make predictions and average on the link scale, before backtransforming:
Note that the two results are exactly identical when we specify `type="response"` explicitly. However, they will differ slightly when we leave `type` unspecified, because `marginaleffects` will then automatically make predictions and average on the link scale, before backtransforming (`"linkinv(link)"`):

```{r}
predictions(
4 changes: 3 additions & 1 deletion man-roxygen/type.R
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
#' @section Prediction types:
#'
#' The `type` argument determines the scale of the predictions used to compute quantities of interest with functions from the `marginaleffects` package. Admissible values for `type` depend on the model object. When users specify an incorrect value for `type`, `marginaleffects` will raise an informative error with a list of valid `type` values for the specific model object.
#' The `type` argument determines the scale of the predictions used to compute quantities of interest with functions from the `marginaleffects` package. Admissible values for `type` depend on the model object. When users specify an incorrect value for `type`, `marginaleffects` will raise an informative error with a list of valid `type` values for the specific model object. The first entry in the list in that error message is the default type.
#'
#' The `linkinv(link)` is a special type defined by `marginaleffects`. It is available for some (but not all) models and functions. With this link type, we first compute predictions on the link scale, then we use the inverse link function to backtransform the predictions to the response scale. This is useful for models with non-linear link functions as it can ensure that confidence intervals stay within desirable bounds, ex: [0,1] for a logit model. Note that an average of estimates with `type="linkinv(link)"` will not always be equivalent to the average of estimates with `type="response"`.
#'
#' Some of the most common `type` values are:
#'
9 changes: 5 additions & 4 deletions man/comparisons.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/get_group_names.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/get_predict.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 5 additions & 6 deletions man/marginal_means.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 5 additions & 6 deletions man/marginalmeans.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/plot_cap.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/plot_cco.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/plot_cme.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/plot_comparisons.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions man/plot_predictions.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 713a370

Please sign in to comment.