% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/domir.r
\name{domir}
\alias{domir}
\alias{domir.formula}
\alias{domir.formula_list}
\title{Dominance analysis methods}
\usage{
domir(.obj, ...)

\method{domir}{formula}(
  .obj,
  .fct,
  .set = NULL,
  .wst = NULL,
  .all = NULL,
  .adj = FALSE,
  .cdl = NULL,
  .cpt = NULL,
  .rev = FALSE,
  .cst = NULL,
  .prg = FALSE,
  ...
)

\method{domir}{formula_list}(
  .obj,
  .fct,
  .set = NULL,
  .wst = NULL,
  .all = NULL,
  .adj = FALSE,
  .cdl = NULL,
  .cpt = NULL,
  .rev = FALSE,
  .cst = NULL,
  .prg = FALSE,
  ...
)
}
\arguments{
\item{.obj}{A \code{formula} or \code{formula_list}.
Parsed to produce a list of names. All valid combinations names from
the list are \code{\link{sapply}}-ed to \code{.fct}.

The combinations of names submitted to \code{.fct} are formatted to be of
the same \code{\link{class}} as \code{.obj} and must be submitted to
\code{.fct} as its first, unnamed argument.}

\item{...}{Passes arguments to other methods during method dispatch;
passes arguments to the function in \code{.fct} during function execution.}

\item{.fct}{A \code{\link{function}} or string function name.
Applied to all valid combinations of names parsed from \code{.obj}.
Must return a length 1/scalar, numeric, atomic vector.}

\item{.set}{A \code{list}.
Each element of the list must be the same class as \code{.obj}.
Elements of the list can be named.
Names parsed from the elements of the list must also be in \code{.obj}.}

\item{.wst}{A \code{list}.
Each element of the list must be the same class as \code{.obj}.
Names parsed from the elements of the list must also be in \code{.obj}.}

\item{.all}{A \code{formula} or \code{formula_list}.
Must be the same class as \code{.obj}.
Parsed names must also be in \code{.obj}.}

\item{.adj}{Logical.
If \code{TRUE} then a model including only an intercept is submitted to \code{.fct}
and the value returned is subtracted from the values returned from all
subsets in the dominance analysis.}

\item{.cdl}{\code{NULL}.
Depreciated. Use \code{.cdl = FALSE} in \code{domir}'s \code{print} method to suppress
display of conditional dominance values.}

\item{.cpt}{\code{NULL}.
Depreciated. Use \code{.cpt = FALSE} in \code{domir}'s \code{print} method to suppress
display of complete dominance values.}

\item{.rev}{Logical.
If \code{TRUE} then standardized vector, ranks, and complete dominance
designations are reversed in their interpretation.}

\item{.cst}{Object of class c("SOCKcluster", "cluster") from
\code{\link{parallel-package}}.

When non-\code{NULL}, will alter the method for collecting values from all
combinations of names from using \code{\link{sapply}} to \code{\link[parallel:clusterApply]{parallel::parSapply}}.}

\item{.prg}{Logical.
If \code{TRUE} then a progress bar is displayed during collection of values
to indicate progress.}
}
\value{
Returns an object of \code{\link{class}} "domir" composed of:
\describe{
\item{\code{General_Dominance}}{Vector of general dominance values.}
\item{\code{Standardized}}{Vector of general dominance values standardized
to sum to 1.}
\item{\code{Ranks}}{Vector of ranks applied to the general dominance values.}
\item{\code{Conditional_Dominance}}{Matrix of conditional dominance values.
Each row represents a name in \code{.obj};
each column represents a number of names included in \code{.fct}.}
\item{\code{Complete_Dominance}}{Matrix of proportions of subsets where the
name in the row has a larger value than the name in the column.
These proportions determine complete dominance when a value of
1 or 0.}
\item{\code{Value}}{Value returned by \code{.fct} with all names included.}
\item{\code{Value_All}}{Value of \code{.fct} associated with names included
in \code{.all};
when \code{.adj} is \code{TRUE}, this value will be adjusted for \code{Value_Adjust}.}
\item{\code{Value_Adjust}}{Value of \code{.fct} returned when no names are included.}
\item{\code{Call}}{The matched call.}
}
}
\description{
Parses input object to obtain a list of names, determines which
combinations of the names are valid, submits valid name
combinations to a function, and computes dominance
values based on the returned values from the function.
}
\details{
\subsection{Name Parsing}{

\code{.obj} is first parsed into a list of names.
How the name list is parsed depends on \code{.obj}'s class.
\subsection{\code{formula}}{

The \code{formula} method creates a name list using all terms in the formula.
The terms are obtained using \code{\link{terms.formula}}.
All processing that is normally applied to the right hand side of a
formula is implemented (see \code{\link{formula}}).

A response/left hand side is not required but, if present, is
included in all \code{formula}s passed to \code{.fct}.
}

\subsection{\code{formula_list}}{

The \code{\link{formula_list}} creates a name list out of response-term pairs.
The terms are obtained using \code{terms.formula} applied to each individual
formula in the list.

The \code{formula_list} methods make it possible to implement dominance analysis
for parameter estimates in multivariate predictive models
(e.g., Luchman, Xie, & Kaplan, 2020).
}

\subsection{Additional Details}{

\code{formula}s and \code{formula_list} elements are assumed to have an intercept
except if explicitly removed with a \code{- 1} in the \code{formula}(s) in \code{.obj}.
If removed, the intercept will be removed in all \code{formula}(s) in each
\code{sapply}-ed subset to \code{.fct}.
If \code{\link{offset}}s are included, they are passed, like intercepts, while
\code{sapply}-ing subsets to \code{.fct}.
}

}

\subsection{Changing Combination Generation}{

Parsed names are used independently for creating combinations of names
to submit to\code{.fct}.
When using \code{.set}, \code{.wst}, and \code{.all}, the way combinations are
created changes.
Names in \code{.set}, \code{.wst}, and \code{.all} must also be present in \code{.obj}.
\subsection{\code{.set}}{

\code{.set} binds together names such that they are considered to be one name
when creating combinations.
The names in each \code{.set} then pool their returned value together with the
other members of their set.

By default, sets are referred to by set names in all output.
Unnamed \code{.set} list elements are called 'set@' where '@' is an integer
indicating the set's position in the list.
The user can give each set in the \code{.set} list a name that will be used in
place of the default.
Names of \code{.set}s cannot contain the period character '.'.

\code{.set} implements the grouped dominance analysis method described by
Luchman (2026).
}

\subsection{\code{.wst}}{

\code{.wst} binds together names such that they are considered to be one name
when creating combinations with other names that are not in their \code{.wst}.
All combinations of names of the members of names within a \code{.wst}
are considered valid.
The names in each \code{.wst} then pool their returned value together with the
other members of their set when compared to names outside of the \code{.wst}
but do not pool their returned value when compared to names within their
\code{.wst}.

\code{.wst} list elements cannot be named.

\code{.wst} implements the within-group dominance analysis method described by
Luchman (2026).
\code{.wst} and \code{.set} can be used together.
}

\subsection{\code{.all}}{

\code{.all} binds together names such that they are considered to be one name
when creating combinations and are always included first, before all
other names.
The names in \code{.all} will then be included in 'all' valid combinations
of names.
The names in \code{.all} are included after the combination with no names but
before any other combinations.
The value associated with \code{.all} is also removed from the
dominance analysis and is reported along with the overall value
including all names.

The \code{formula} method for \code{.all} does not allow the formula in \code{.all} to have
a left hand side.
}

\subsection{\code{.adj}}{

By default, \code{domir} assumes that the combination of no names has a
value of 0.
\code{.adj} indicates that the there is an 'adjustment' needed such that the
no names combination has a non-0 value and an intercept-only model should
be supplied to \code{.fct}.

The \code{formula} method will submit an intercept-only formula to \code{.fct}.
The \code{formula_list} method creates a separate, intercept-only subset for each
of the \code{formula}s in the list.
Both the \code{formula} and \code{formula_list} methods will respect the user's
removal of an intercept and or inclusion of an \code{offset}.
}

\subsection{Additional Details}{

All methods submit combinations of names as an object of the same class as
\code{.obj}.
A \code{formula} in \code{.obj} will submit all combinations of names as
\code{formula}s to \code{.fct}.
A \code{formula_list} in \code{.obj} will submit all
combinations of subsets of names as \code{formula_list}s to \code{.fct}.
In the case that \code{.fct} requires a different \code{class} (e.g.,
a character vector of names, a \code{\link[Formula:Formula]{Formula::Formula}} see \code{\link{fmllst2Fml}}) the
subsets of names will have to be processed in \code{.fct} to obtain the correct
\code{class}.

The \code{formula} or \code{formula_list} of names will be submitted to \code{.fct} as the
first, unnamed argument.
}

}

\subsection{\code{.fct} as Analysis Pipeline}{

\code{.fct} is expected to be a complete analysis pipeline that receives a
subset of names of the same \code{class} as \code{.obj} and uses these names in the
\code{class} as submitted to generate a returned value of the appropriate
type to dominance analyze.
At current, only atomic (i.e., non-\code{list}), numeric scalars (i.e.,
vectors of length 1) are allowed as returned values.
\code{domir} is designed for use with predictive models and assumes the returned
value is a scalar-valued fit statistic/metric.

The \code{.fct} argument is strict about names submitted and returned value
requirements for functions used.
A series of checks to ensure the submitted names and returned value adhere
to these requirements.
The checks include whether the \code{.obj} can be submitted to \code{.fct} without
producing an error and whether the returned value from \code{.fct} is a length 1,
atomic, numeric vector.
In most circumstances, the user will have to make their own named or
anonymous function to supply as \code{.fct} to satisfy the checks.
}
}
\section{Notes}{
Prior to version 1.1.0, the \code{formula} method allowed a \code{formula}
to be submitted to \code{.adj}.
Submitting any argument other than a logical is now defunct.

The \code{formula} and \code{formula_list} methods can be used to pass responses,
intercepts, and \code{offset}s to all combinations of names.
If the user seeks to include other model components integral to
estimation (i.e., a random effect term in \code{\link[lme4:glmer]{lme4::glmer()}}) include them as
\code{\link[=update.formula]{update}} to the submitted \code{formula} or \code{formula_list}
embedded in \code{.fct}.

Second-order or higher terms (i.e., interactions like \code{~ a*b}) are parsed
by default but not used differently from first-order terms for generating
valid combinations.
The values ascribed to such names may not be valid unless the user ensures
that second-order and higher term names are used appropriately in \code{.fct}.
}

\examples{
## Linear model returning r-square
lm_r2 <-
  function(fml, data) {
    lm_res <- lm(fml, data = data)
    summary(lm_res)[["r.squared"]]
 }

domir(mpg ~ am + vs + cyl, lm_r2, data = mtcars)

## Linear model including set
domir(
  mpg ~ am + vs + cyl + carb + gear + disp + wt,
  lm_r2,
  .set = list(~ carb + gear, ~ disp + wt),
  data = mtcars
)

## Multivariate regression with multivariate r-square and
## all subsets variable
if (requireNamespace("performance", quietly = TRUE)) {
  mlm_rxy <-
    function(fml, data) {
      mlm_res <- lm(fml, data = data)
      performance::r2_mlm(mlm_res)[["Symmetric Rxy"]]
    }

  domir(
    cbind(wt, mpg) ~ vs + cyl + am + carb,
    mlm_rxy,
    .all = ~ carb,
    data = mtcars
  )
}

## Named sets
domir(
  mpg ~ am + gear + cyl + vs + qsec + drat,
  lm_r2,
  data = mtcars,
  .set =
    list(
      trns = ~ am + gear,
      eng = ~ cyl + vs,
      misc = ~ qsec + drat
    )
)

## Linear model returning AIC
lm_aic <-
  function(fml, data) {
    lm_res <- lm(fml, data = data)
    AIC(lm_res)
 }

domir(
  mpg ~ am + carb + cyl,
  lm_aic,
  .adj = TRUE,
  .rev = TRUE,
  data = mtcars
 )

## 'systemfit' with 'formula_list' method returning AIC
if (requireNamespace("systemfit", quietly = TRUE)) {
  domir(
    formula_list(mpg ~ am + cyl + carb, qsec ~ wt + cyl + carb),
    function(fml) {
      res <- systemfit::systemfit(fml, data = mtcars)
      AIC(res)
    },
    .adj = TRUE, .rev = TRUE
  )
}

## within-set or within-group dominance analysis
domir(
  mpg ~ am + gear + cyl + vs + qsec + drat,
  lm_r2,
  data = mtcars,
  .wst =
    list(
      ~ am + gear,
      ~ cyl + vs,
      ~ qsec + drat
    )
)
}
\references{
\itemize{
\item Luchman, J. N., Lei, X., & Kaplan, S. (2020). Relative Importance
Analysis with Multivariate Models: Shifting the Focus from Independent
Variables to Parameter Estimates. Journal of Applied Structural Equation
Modeling, 4(2), 1-20. doi:https://doi.org/10.47263/JASEM.4(2)02
\item Luchman, J. N. (2026). Determining Relative Importance with
Independent Variable Groups: An Alternative Dominance Analysis Method.
Journal of Behavioral Data Science, 6(1), 1-26.
doi:https://doi.org/10.35566/jbds/luchman
}
}
