From bc08095c58ed52e82e5275d00203ec860eda0e5a Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 11 Sep 2023 10:25:48 -0400 Subject: [PATCH] docs --- R/marginal_means.R | 4 ++-- R/predictions.R | 4 ++-- R/print.R | 4 ++++ R/sanitize_type.R | 6 +++--- R/type_dictionary.R | 8 ++++---- book/articles/predictions.qmd | 4 ++-- man-roxygen/type.R | 2 +- man/comparisons.Rd | 4 ++-- man/marginal_means.Rd | 4 ++-- man/marginalmeans.Rd | 4 ++-- man/predictions.Rd | 4 ++-- man/slopes.Rd | 4 ++-- 12 files changed, 28 insertions(+), 24 deletions(-) diff --git a/R/marginal_means.R b/R/marginal_means.R index 28a440423..75c043466 100644 --- a/R/marginal_means.R +++ b/R/marginal_means.R @@ -192,7 +192,7 @@ marginal_means <- function(model, # if type is NULL, we backtransform if relevant type_string <- sanitize_type(model = model, type = type, calling_function = "predictions") - if (type_string == "linkinv(link)") { + if (type_string == "invlink(link)") { type_call <- "link" } else { type_call <- type_string @@ -387,7 +387,7 @@ marginal_means <- function(model, out <- equivalence(out, equivalence = equivalence, df = df, ...) # after assign draws - if (identical(type_string, "linkinv(link)")) { + if (identical(type_string, "invlink(link)")) { linv <- tryCatch(insight::link_inverse(model), error = function(e) identity) out <- backtransform(out, transform = linv) } diff --git a/R/predictions.R b/R/predictions.R index 931574503..9a3c3ca6a 100644 --- a/R/predictions.R +++ b/R/predictions.R @@ -274,7 +274,7 @@ predictions <- function(model, # if type is NULL, we backtransform if relevant type_string <- sanitize_type(model = model, type = type, calling_function = "predictions") - if (type_string == "linkinv(link)") { + if (type_string == "invlink(link)") { type_call <- "link" } else { type_call <- type_string @@ -526,7 +526,7 @@ predictions <- function(model, out <- equivalence(out, equivalence = equivalence, df = df, ...) # after rename to estimate / after assign draws - if (identical(type_string, "linkinv(link)")) { + if (identical(type_string, "invlink(link)")) { linv <- tryCatch(insight::link_inverse(model), error = function(e) identity) out <- backtransform(out, transform = linv) } diff --git a/R/print.R b/R/print.R index c8bcab9ce..d156ee063 100644 --- a/R/print.R +++ b/R/print.R @@ -35,6 +35,7 @@ print.marginaleffects <- function(x, nrows = getOption("marginaleffects_print_nrows", default = 30), ncols = getOption("marginaleffects_print_ncols", default = 30), style = getOption("marginaleffects_print_style", default = "summary"), + type = getOption("marginaleffects_print_type", default = TRUE), ...) { @@ -243,6 +244,9 @@ print.marginaleffects <- function(x, if (ncol(x) <= ncols) { cat("Columns:", paste(colnames(x), collapse = ", "), "\n") } + if (isTRUE(type) && !is.null(attr(x, "type"))) { + cat("Type: ", attr(x, "type"), "\n") + } cat("\n") print_tail <- attr(x, "print_tail") diff --git a/R/sanitize_type.R b/R/sanitize_type.R index 4eff7ebde..bb39bf745 100644 --- a/R/sanitize_type.R +++ b/R/sanitize_type.R @@ -11,13 +11,13 @@ sanitize_type <- function(model, type, calling_function = NULL) { } dict <- type_dictionary if (calling_function %in% c("slopes", "comparisons")) { - dict <- dict[dict$type != "linkinv(link)", , drop = FALSE] + dict <- dict[dict$type != "invlink(link)", , drop = FALSE] } - # fixest: linkinv(link) only supported for glm model + # fixest: invlink(link) only supported for glm model if (inherits(model, "fixest")) { if (!isTRUE(hush(model[["method_type"]]) %in% c("feglm"))) { - dict <- dict[dict$type != "linkinv(link)", , drop = FALSE] + dict <- dict[dict$type != "invlink(link)", , drop = FALSE] } } diff --git a/R/type_dictionary.R b/R/type_dictionary.R index e03b524e8..28543c6cb 100644 --- a/R/type_dictionary.R +++ b/R/type_dictionary.R @@ -49,7 +49,7 @@ hxlr,scale hxlr,density ivpml,pr ivpml,xb -fixest,linkinv(link) +fixest,invlink(link) fixest,response fixest,link hurdle,response @@ -60,14 +60,14 @@ iv_robust,response lm,response gam,response gam,link -Gam,linkinv(link) +Gam,invlink(link) Gam,response Gam,link geeglm,response geeglm,link glimML,response glimML,link -glm,linkinv(link) +glm,invlink(link) glm,response glm,link glmerMod,response @@ -104,7 +104,7 @@ mhurdle,E mhurdle,Ep mhurdle,p mlogit,response -negbin,linkinv(link) +negbin,invlink(link) negbin,response negbin,link ols,lp diff --git a/book/articles/predictions.qmd b/book/articles/predictions.qmd index cc97bbdc3..f285973a5 100644 --- a/book/articles/predictions.qmd +++ b/book/articles/predictions.qmd @@ -178,7 +178,7 @@ pred <- predictions(modlin) mean(pred$estimate) ``` -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: +Note that in GLM models with a non-linear link function, the default `type` is `invlink(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 (`"linkinv(link)"`): +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 (`"invlink(link)"`): ```{r} predictions( diff --git a/man-roxygen/type.R b/man-roxygen/type.R index 63d29cd48..6acd1113f 100644 --- a/man-roxygen/type.R +++ b/man-roxygen/type.R @@ -2,7 +2,7 @@ #' #' 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"`. +#' The `invlink(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="invlink(link)"` will not always be equivalent to the average of estimates with `type="response"`. #' #' Some of the most common `type` values are: #' diff --git a/man/comparisons.Rd b/man/comparisons.Rd index 93c1fb917..1869eb217 100644 --- a/man/comparisons.Rd +++ b/man/comparisons.Rd @@ -409,11 +409,11 @@ Thanks to Russell V. Lenth for the excellent \code{emmeans} package and document The \code{type} argument determines the scale of the predictions used to compute quantities of interest with functions from the \code{marginaleffects} package. Admissible values for \code{type} depend on the model object. When users specify an incorrect value for \code{type}, \code{marginaleffects} will raise an informative error with a list of valid \code{type} values for the specific model object. The first entry in the list in that error message is the default type. -The \code{linkinv(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="linkinv(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. +The \code{invlink(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="invlink(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. Some of the most common \code{type} values are: -response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, linkinv(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob +response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, invlink(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob } \examples{ diff --git a/man/marginal_means.Rd b/man/marginal_means.Rd index c47f3e98c..549280034 100644 --- a/man/marginal_means.Rd +++ b/man/marginal_means.Rd @@ -269,11 +269,11 @@ Thanks to Russell V. Lenth for the excellent \code{emmeans} package and document The \code{type} argument determines the scale of the predictions used to compute quantities of interest with functions from the \code{marginaleffects} package. Admissible values for \code{type} depend on the model object. When users specify an incorrect value for \code{type}, \code{marginaleffects} will raise an informative error with a list of valid \code{type} values for the specific model object. The first entry in the list in that error message is the default type. -The \code{linkinv(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="linkinv(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. +The \code{invlink(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="invlink(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. Some of the most common \code{type} values are: -response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, linkinv(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob +response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, invlink(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob } \examples{ diff --git a/man/marginalmeans.Rd b/man/marginalmeans.Rd index 0045f18e2..b6bd31701 100644 --- a/man/marginalmeans.Rd +++ b/man/marginalmeans.Rd @@ -263,11 +263,11 @@ Thanks to Russell V. Lenth for the excellent \code{emmeans} package and document The \code{type} argument determines the scale of the predictions used to compute quantities of interest with functions from the \code{marginaleffects} package. Admissible values for \code{type} depend on the model object. When users specify an incorrect value for \code{type}, \code{marginaleffects} will raise an informative error with a list of valid \code{type} values for the specific model object. The first entry in the list in that error message is the default type. -The \code{linkinv(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="linkinv(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. +The \code{invlink(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="invlink(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. Some of the most common \code{type} values are: -response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, linkinv(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob +response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, invlink(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob } \examples{ diff --git a/man/predictions.Rd b/man/predictions.Rd index d59287841..59ad38518 100644 --- a/man/predictions.Rd +++ b/man/predictions.Rd @@ -332,11 +332,11 @@ Thanks to Russell V. Lenth for the excellent \code{emmeans} package and document The \code{type} argument determines the scale of the predictions used to compute quantities of interest with functions from the \code{marginaleffects} package. Admissible values for \code{type} depend on the model object. When users specify an incorrect value for \code{type}, \code{marginaleffects} will raise an informative error with a list of valid \code{type} values for the specific model object. The first entry in the list in that error message is the default type. -The \code{linkinv(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="linkinv(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. +The \code{invlink(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="invlink(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. Some of the most common \code{type} values are: -response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, linkinv(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob +response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, invlink(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob } \examples{ diff --git a/man/slopes.Rd b/man/slopes.Rd index cdc2c0347..ac6ed062a 100644 --- a/man/slopes.Rd +++ b/man/slopes.Rd @@ -331,11 +331,11 @@ Thanks to Russell V. Lenth for the excellent \code{emmeans} package and document The \code{type} argument determines the scale of the predictions used to compute quantities of interest with functions from the \code{marginaleffects} package. Admissible values for \code{type} depend on the model object. When users specify an incorrect value for \code{type}, \code{marginaleffects} will raise an informative error with a list of valid \code{type} values for the specific model object. The first entry in the list in that error message is the default type. -The \code{linkinv(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="linkinv(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. +The \code{invlink(link)} is a special type defined by \code{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: \link{0,1} for a logit model. Note that an average of estimates with \code{type="invlink(link)"} will not always be equivalent to the average of estimates with \code{type="response"}. Some of the most common \code{type} values are: -response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, linkinv(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob +response, link, E, Ep, average, class, conditional, count, cum.prob, cumprob, density, disp, expected, expvalue, fitted, latent, linear.predictor, invlink(link), linpred, location, lp, mean, p, pr, precision, prediction, prob, probability, probs, quantile, risk, scale, survival, unconditional, utility, variance, xb, zero, zlink, zprob } \examples{