% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/WVIM.R
\name{WVIM}
\alias{WVIM}
\title{Williamson's Variable Importance Measure (WVIM)}
\description{
Base class generalizing refit-based variable importance measures.
Default corresponds to leaving out each feature \code{n_repeats = 1} times, which
corresponds to LOCO (Leave One Covariate Out).
}
\examples{
\dontshow{if (requireNamespace("ranger", quietly = TRUE) && requireNamespace("mlr3learners", quietly = TRUE)) withAutoprint(\{ # examplesIf}
library(mlr3)
library(mlr3learners)

task <- sim_dgp_correlated(n = 500)

# Group correlated features together, independent features separately
groups <- list(
  correlated = c("x1", "x2"),
  independent = c("x3", "x4")
)

wvim <- WVIM$new(
  task = task,
  learner = lrn("regr.ranger", num.trees = 10),
  groups = groups
)
wvim$compute()
wvim$importance()
\dontshow{\}) # examplesIf}
}
\references{
Lei J, G'Sell M, Rinaldo A, Tibshirani R, Wasserman L (2018).
\dQuote{Distribution-Free Predictive Inference for Regression.}
\emph{Journal of the American Statistical Association}, \bold{113}(523), 1094--1111.
\doi{10.1080/01621459.2017.1307116}.
}
\keyword{internal}
\section{Super class}{
\code{\link[xplainfi:FeatureImportanceMethod]{FeatureImportanceMethod}} -> \code{WVIM}
}
\section{Public fields}{
  \if{html}{\out{<div class="r6-fields">}}
  \describe{
    \item{\code{direction}}{(\code{character(1)}) Either "leave-out" or "leave-in".}

    \item{\code{design}}{(\code{logical()}) Feature selection design matrix where \code{TRUE} equals "left in" and \code{FALSE} "left out".
Columns correspond to \code{task$feature_names} and the number of rows corresponds to \code{length(features) * n_repeats}.
The base matrix is created by \link{wvim_design_matrix} and then replicated \code{n_repeats} times before.}

    \item{\code{instance}}{(\code{FSelectInstanceBatchSingleCrit}) The \code{mlr3fselect} feature selection instance containing
also the archive of all evaluations, possible useful for future use. Only stored if \code{store_instance} is \code{TRUE}.}
  }
  \if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
  \itemize{
    \item \href{#method-WVIM-initialize}{\code{WVIM$new()}}
    \item \href{#method-WVIM-importance}{\code{WVIM$importance()}}
    \item \href{#method-WVIM-compute}{\code{WVIM$compute()}}
    \item \href{#method-WVIM-clone}{\code{WVIM$clone()}}
  }
}
\if{html}{\out{<details open><summary>Inherited methods</summary>
<ul>
  <li><span class="pkg-link" data-pkg="xplainfi" data-topic="FeatureImportanceMethod" data-id="obs_loss"><a href='../../xplainfi/html/FeatureImportanceMethod.html#method-FeatureImportanceMethod-obs_loss'><code>FeatureImportanceMethod$obs_loss()</code></a></span></li>
  <li><span class="pkg-link" data-pkg="xplainfi" data-topic="FeatureImportanceMethod" data-id="print"><a href='../../xplainfi/html/FeatureImportanceMethod.html#method-FeatureImportanceMethod-print'><code>FeatureImportanceMethod$print()</code></a></span></li>
  <li><span class="pkg-link" data-pkg="xplainfi" data-topic="FeatureImportanceMethod" data-id="reset"><a href='../../xplainfi/html/FeatureImportanceMethod.html#method-FeatureImportanceMethod-reset'><code>FeatureImportanceMethod$reset()</code></a></span></li>
  <li><span class="pkg-link" data-pkg="xplainfi" data-topic="FeatureImportanceMethod" data-id="scores"><a href='../../xplainfi/html/FeatureImportanceMethod.html#method-FeatureImportanceMethod-scores'><code>FeatureImportanceMethod$scores()</code></a></span></li>
</ul>
</details>}}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-WVIM-initialize"></a>}}
\if{latex}{\out{\hypertarget{method-WVIM-initialize}{}}}
\subsection{\code{WVIM$new()}}{
  Creates a new instance of this \link[R6:R6Class]{R6} class.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{WVIM$new(
  task,
  learner,
  measure = NULL,
  resampling = NULL,
  features = NULL,
  groups = NULL,
  direction = c("leave-out", "leave-in"),
  label = "Williamson's Variable Importance Measure (WVIM)",
  n_repeats = 1L,
  batch_size = NULL
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{task, learner, measure, resampling, features, groups}}{Passed to \code{FeatureImportanceMethod} for construction.}
      \item{\code{direction}}{(\code{character(1)}) Either "leave-out" or "leave-in".}
      \item{\code{label}}{(\code{character(1)}) Method label.}
      \item{\code{n_repeats}}{(\code{integer(1)}: \code{1L}) Number of refit iterations per resampling iteration.
This may be useful for some stochastic learners, but in general it is advisable to increase resampling iterations instead of
repeatedly refitting on the same data.}
      \item{\code{batch_size}}{(\code{integer(1)}: \code{NULL}) Number of design points (refits) dispatched per internal
\code{mlr3::benchmark()} call by the \code{mlr3fselect::fs("design_points")} fselector. \code{NULL} (default) keeps
the bbotk default of one design point per call, i.e. sequential single-refit evaluation. Set to a
positive integer to batch refits so mlr3's \code{future}/\code{mirai} parallelization can spread them across
workers; a sensible value is the number of available workers/daemons.}
    }
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-WVIM-importance"></a>}}
\if{latex}{\out{\hypertarget{method-WVIM-importance}{}}}
\subsection{\code{WVIM$importance()}}{
  Get aggregated importance scores.
Extends the base \verb{$importance()} method to support \code{ci_method = "lei"}.

This implements distribution-free inference based on Lei et al. (2018),
testing observation-wise loss differences using the Wilcoxon signed-rank test by default.

Lei et al. (2018) proposed this method specifically for LOCO with L1 (absolute) loss,
median aggregation, and a single train/test split (holdout). The inference is
conditional on the training data, requiring i.i.d. test observations from a single
split. While the aggregation function, statistical test, and resampling strategy are
parameterizable, deviating from these defaults may invalidate the theoretical guarantees.

For a comprehensive overview of inference methods, see
\code{vignette("inference", package = "xplainfi")}.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{WVIM$importance(
  relation = NULL,
  standardize = FALSE,
  ci_method = c("none", "raw", "nadeau_bengio", "quantile", "lei"),
  conf_level = 0.95,
  alternative = c("two.sided", "greater"),
  test = c("wilcoxon", "t", "fisher", "binomial"),
  B = 1999,
  aggregator = NULL,
  p_adjust = "none",
  ...
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{relation}}{(\code{character(1)}) How to relate perturbed scores to originals ("difference" or "ratio"). If \code{NULL}, uses stored parameter value.}
      \item{\code{standardize}}{(\code{logical(1)}: \code{FALSE}) If \code{TRUE}, importances are standardized by the highest score so all scores fall in \verb{[-1, 1]}.}
      \item{\code{ci_method}}{(\code{character(1)}: \code{"none"}) Variance estimation method. In addition to base methods (\code{"none"}, \code{"raw"}, \code{"nadeau_bengio"}, \code{"quantile"}),
WVIM methods support \code{"lei"} for distribution-free inference (Lei et al., 2018).}
      \item{\code{conf_level}}{(\code{numeric(1)}: \code{0.95}) Confidence level to use for confidence interval construction when \code{ci_method != "none"}.}
      \item{\code{alternative}}{(\code{character(1)}: \code{"two.sided"}) Type of alternative hypothesis for statistical tests.
\code{"greater"} tests H0: importance <= 0 vs H1: importance > 0 (one-sided).
\code{"two.sided"} tests H0: importance = 0 vs H1: importance != 0.}
      \item{\code{test}}{(\code{character(1)}: \code{"wilcoxon"}) Test to use for Lei et al. inference. One of \code{"wilcoxon"}, \code{"t"}, \code{"fisher"}, or \code{"binomial"}.
Only used when \code{ci_method = "lei"}.}
      \item{\code{B}}{(\code{integer(1)}: \code{1999}) Number of replications for Fisher test. Only used when \code{ci_method = "lei"} and \code{test = "fisher"}.}
      \item{\code{aggregator}}{(\code{function}: \code{stats::median}) Aggregation function for computing the point estimate from observation-wise
importance values. Defaults to \code{stats::median} as proposed by Lei et al. (2018). Only used when \code{ci_method = "lei"}.}
      \item{\code{p_adjust}}{(\code{character(1)}: \code{"none"}) Method for p-value adjustment for multiple comparisons.
Accepts any method supported by \link[stats:p.adjust.methods]{stats::p.adjust.methods}, e.g. \code{"holm"}, \code{"bonferroni"}, \code{"BH"}, \code{"none"}.
When \code{"bonferroni"}, confidence intervals are also adjusted (alpha/k).
For other correction methods (e.g. \code{"holm"}, \code{"BH"}), only p-values are adjusted;
confidence intervals remain at the nominal \code{conf_level} because these sequential/adaptive
procedures do not have a clean per-comparison alpha for CI construction.}
      \item{\code{...}}{Additional arguments passed to the base method.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Returns}{
    (\link[data.table:data.table]{data.table}) Aggregated importance scores.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-WVIM-compute"></a>}}
\if{latex}{\out{\hypertarget{method-WVIM-compute}{}}}
\subsection{\code{WVIM$compute()}}{
  Computes leave-out or leave-in feature importance.
\code{wvim_design_matrix(task$feature_names, "leave-out")} corresponds to LOCO.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{WVIM$compute(
  store_models = TRUE,
  store_backends = TRUE,
  store_instance = FALSE
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{store_models, store_backends}}{(\code{logical(1)}: \code{TRUE}) Whether to store fitted models / data backends, passed to \link[mlr3:resample]{mlr3::resample} internally
backends in resample result.
Required for some measures, but may increase memory footprint.}
      \item{\code{store_instance}}{(\code{logical(1)}: \code{FALSE}) Whether to store the \link[mlr3fselect:mlr3fselect]{mlr3fselect} instance in \verb{$instance}.}
    }
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-WVIM-clone"></a>}}
\if{latex}{\out{\hypertarget{method-WVIM-clone}{}}}
\subsection{\code{WVIM$clone()}}{
  The objects of this class are cloneable with this method.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{WVIM$clone(deep = FALSE)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{deep}}{Whether to make a deep clone.}
    }
    \if{html}{\out{</div>}}
  }
}

}
