% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/inferences.R
\name{inferences}
\alias{inferences}
\title{(EXPERIMENTAL) Bootstrap, Conformal, and Simulation-Based Inference}
\usage{
inferences(
  x,
  method,
  R = 1000,
  conf_type = "perc",
  data_train = NULL,
  data_test = NULL,
  data_calib = NULL,
  conformal_score = "residual_abs",
  estimator = NULL,
  ...
)
}
\arguments{
\item{x}{Object produced by one of the core \code{marginaleffects} functions, or a data frame suitable for the function supplied to the \code{estimator} argument.}

\item{method}{String
\itemize{
\item "delta": delta method standard errors
\item "boot" package
\item "fwb": fractional weighted bootstrap
\item "rsample" package
\item "simulation" from a multivariate normal distribution (Krinsky & Robb, 1986)
\item "conformal_split": prediction intervals using split conformal prediction (see Angelopoulos & Bates, 2022)
\item "conformal_cv+": prediction intervals using cross-validation+ conformal prediction (see Barber et al., 2020)
\item "conformal_full": prediction intervals using full conformal prediction (see Lei et al., 2018). \strong{Warning}: This method is computationally expensive and typically much slower than split or CV+ methods.
\item "conformal_quantile": prediction intervals using full conformal prediction (see Romano et al., 2020).
}}

\item{R}{Number of resamples, simulations, or cross-validation folds.}

\item{conf_type}{String: type of bootstrap interval to construct.
\itemize{
\item \code{boot}: "perc", "norm", "basic", or "bca"
\item \code{fwb}: "perc", "norm", "wald", "basic", "bc", or "bca"
\item \code{rsample}: "perc" or "bca"
\item \code{simulation}: "perc" or "wald"
}}

\item{data_train}{Data frame used to train/fit the model. If \code{NULL}, \code{marginaleffects} tries to extract the data from the original model object. Test data are inferred directly from the \code{newdata} supplied to the originating \code{marginaleffects} call (e.g., \code{predictions()}).}

\item{data_test}{Data frame make out of sample prediction. Only used for conformal inference. If \code{NULL}, the data frame supplied to \code{newdata} in the original \code{marginaleffects} call is used.}

\item{data_calib}{Data frame used for calibration in split conformal prediction.}

\item{conformal_score}{String. Warning: The \code{type} argument in \code{predictions()} must generate predictions which are on the same scale as the outcome variable. Typically, this means that \code{type} must be "response" or "probs".
\itemize{
\item "residual_abs" or "residual_sq" for regression tasks (numeric outcome)
\item "softmax" for classification tasks (when \code{predictions()} returns a \code{group} columns, such as multinomial or ordinal logit models.
}}

\item{estimator}{Function that accepts a data frame, fits a model, applies a \code{marginaleffects} function, and returns the object. Only supported with \code{method = "rsample"} or \code{method = "boot"}. When \code{method = "rsample"}, the output must include a "term" column. This is not always the case for \code{predictions()}, in which case users may have to create the column manually.}

\item{...}{\itemize{
\item If \code{method = "boot"}, additional arguments are passed to \code{boot::boot()}.
\item If \code{method = "fwb"}, additional arguments are passed to \code{fwb::fwb()}.
\item If \code{method = "rsample"}, additional arguments are passed to \code{rsample::bootstraps()}, unless the user supplies a \code{group} argument, in which case all arguments are passed to \code{rsample::group_bootstraps()}.
\item If \code{method = "conformal_full"}, additional arguments control the optimization process:
\itemize{
\item \code{var_multiplier}: multiplier for initial search bounds (default: 10)
\item \code{max_iter}: maximum iterations for root finding (default: 100)
\item \code{tolerance}: tolerance for root finding convergence (default: \code{.Machine$double.eps^0.25})
}
\item If \code{method = "conformal_quantile"}, additional arguments are passed to \code{quantregForest::quantregForest()} for fitting the quantile regression forest (e.g., \code{ntree}, \code{mtry}, \code{nodesize}, \code{nthreads}).
\item Additional arguments are ignored for other conformal methods (\code{conformal_split}, \verb{conformal_cv+}).
}}
}
\value{
A \code{marginaleffects} object with simulation or bootstrap resamples and objects attached.
}
\description{
Warning: This function is experimental. It may be renamed, the user interface may change, or the functionality may migrate to arguments in other \code{marginaleffects} functions.

Apply this function to a \code{marginaleffects} object to change the inferential method used to compute uncertainty estimates.
}
\details{
When \code{method = "simulation"}, we conduct simulation-based inference following the method discussed in Krinsky & Robb (1986):
\enumerate{
\item Draw \code{R} sets of simulated coefficients from a multivariate normal distribution with mean equal to the original model's estimated coefficients and variance equal to the model's variance-covariance matrix (classical, "HC3", or other).
\item Use the \code{R} sets of coefficients to compute \code{R} sets of estimands: predictions, comparisons, slopes, or hypotheses.
\item Take quantiles of the resulting distribution of estimands to obtain a confidence interval (when \code{conf_type = "perc"}) and the standard deviation of simulated estimates to estimate the standard error (which is used for a Z-test and Wald confidence intervals when \code{conf_type = "wald"}).
}

When \code{method = "fwb"}, drawn weights are supplied to the model fitting function's \code{weights} argument; if the model doesn't accept non-integer weights, this method should not be used. If weights were included in the original model fit, they are extracted by \code{\link[=weights]{weights()}} and multiplied by the drawn weights. These weights are supplied to the \code{wts} argument of the estimation function (e.g., \code{comparisons()}).

Warning: custom model classes are not supported by \code{inferences()} because they are not guaranteed to come with an appropriate \code{update()} method.
}
\section{References}{


Krinsky, I., and A. L. Robb. 1986. "On Approximating the Statistical Properties of Elasticities." Review of Economics and Statistics 68 (4): 715–9.

King, Gary, Michael Tomz, and Jason Wittenberg. "Making the most of statistical analyses: Improving interpretation and presentation." American journal of political science (2000): 347-361

Dowd, Bryan E., William H. Greene, and Edward C. Norton. "Computation of standard errors." Health services research 49.2 (2014): 731-750.

Angelopoulos, Anastasios N., and Stephen Bates. 2022. "A Gentle Introduction to Conformal Prediction and Distribution-Free Uncertainty Quantification." arXiv. https://doi.org/10.48550/arXiv.2107.07511.

Barber, Rina Foygel, Emmanuel J. Candes, Aaditya Ramdas, and Ryan J. Tibshirani. 2020. "Predictive Inference with the Jackknife+." arXiv. http://arxiv.org/abs/1905.02928.

Lei, Jing, Max G'Sell, Alessandro Rinaldo, Ryan J. Tibshirani, and Larry Wasserman. 2018. "Distribution-Free Predictive Inference for Regression." Journal of the American Statistical Association 113 (523): 1094–1111.

Romano, Yaniv, Evan Patterson, and Emmanuel Candes. 2020. "Conformalized quantile regression." Advances in neural information processing systems 32.
}

\section{Parallel computation}{


The \code{slopes()} and \code{comparisons()} functions can use parallelism to
speed up computation. Operations are parallelized for the computation of
standard errors, at the model coefficient level. There is always
considerable overhead when using parallel computation, mainly involved
in passing the whole dataset to the different processes. Thus, parallel
computation is most likely to be useful when the model includes many parameters
and the dataset is relatively small.

Warning: In many cases, parallel processing will not be useful at all.

To activate parallel computation, users must load the \code{future.apply} package,
call \code{plan()} function, and set a global option.

\code{options(marginaleffects_parallel = TRUE)}: parallelize delta method computation of standard errors.
\code{options(marginaleffects_parallel_inferences = TRUE)}: parallelize \code{"rsample"} or \code{"fwb"} bootstrap computation in \code{inferences()}.
\code{options(marginaleffects_parallel_packages = TRUE)}: vector of strings with the names of modeling packages used to fit the model, ex: c("survival", "splines")

For example:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(future.apply)
plan("multisession", workers = 4)
options(marginaleffects_parallel = FALSE)
options(marginaleffects_parallel_inferences = TRUE)
options(marginaleffects_parallel_packages = c("survival", "splines"))

slopes(model)
}\if{html}{\out{</div>}}

To disable parallelism in \code{marginaleffects} altogether, you can set a global option:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{options(marginaleffects_parallel = FALSE)
}\if{html}{\out{</div>}}
}

\examples{
\dontrun{
library(magrittr)
set.seed(1024)
mod <- lm(Sepal.Length ~ Sepal.Width * Species, data = iris)

# bootstrap
avg_predictions(mod, by = "Species") \%>\%
    inferences(method = "boot")

avg_predictions(mod, by = "Species") \%>\%
    inferences(method = "rsample")

# Fractional (bayesian) bootstrap
avg_slopes(mod, by = "Species") \%>\%
    inferences(method = "fwb") \%>\%
    get_draws("rvar") \%>\%
    data.frame()

# Simulation-based inference
slopes(mod) \%>\%
    inferences(method = "simulation") \%>\%
    head()

# Two-step estimation procedure: Propensity score + G-Computation
lalonde <- get_dataset("lalonde")
estimator <- function(data) {
    # Step 1: Estimate propensity scores
    fit1 <- glm(treat ~ age + educ + race, family = binomial, data = data)
    ps <- predict(fit1, type = "response")
    # Step 2: Fit weighted outcome model
    m <- lm(re78 ~ treat * (re75 + age + educ + race),
        data = data, weight = ps
    )
    # Step 3: Compute average treatment effect by G-computation
    avg_comparisons(m, variables = "treat", wts = ps, vcov = FALSE)
}
inferences(lalonde, method = "rsample", estimator = estimator)
}
}
