domir (version 1.2.0)

domir: Dominance analysis methods

Description

Parses input object to obtain list of names, determines all required combinations of subsets of the name list, submits name list subsets to a function as the input type, and computes dominance decomposition statistics based on the returned values from the function.

Usage

domir(.obj, ...)
# S3 method for formula
domir(
  .obj,
  .fct,
  .set = NULL,
  .wst = NULL,
  .all = NULL,
  .adj = FALSE,
  .cdl = TRUE,
  .cpt = TRUE,
  .rev = FALSE,
  .cst = NULL,
  .prg = FALSE,
  ...
)
# S3 method for formula_list
domir(
  .obj,
  .fct,
  .set = NULL,
  .wst = NULL,
  .all = NULL,
  .adj = FALSE,
  .cdl = TRUE,
  .cpt = TRUE,
  .rev = FALSE,
  .cst = NULL,
  .prg = FALSE,
  ...
)

Value

Returns an object of class "domir" composed of:

General_Dominance

Vector of general dominance values.

Standardized

Vector of general dominance values normalized to sum to 1.

Ranks

Vector of ranks applied to the general dominance values.

Conditional_Dominance

Matrix of conditional dominance values. Each row represents an element in .obj; each column represents a number of elements from .obj in a subset.

Complete_Dominance

Matrix of proportions of subsets where the name in the row has a larger value than the name in the column. The se proportions determine complete dominance when a value of 1 or 0.

Value

Value returned by .fct with all elements (i.e., from .obj, .all, and .adj.

Value_All

Value of .fct associated with elements included in .all; when elements are in .adj, will be adjusted for Value_Adjust.

Value_Adjust

Value of .fct associated with elements in .adj.

Call

The matched call.

Arguments

.obj

A formula or formula_list.

Parsed to produce list of names. Combinations of subsets the name list are sapply-ed to .fct.

The name list subsets submitted to .fct are formatted to be of the same class as .obj and are submitted to .fct as the first, unnamed argument.

...

Passes arguments to other methods during method dispatch; passes arguments to the function in .fct during function execution.

.fct

A function or string function name.

Applied to all subsets of elements as received from .obj. Must return a length 1/scalar, numeric, atomic vector.

.set

A list.

Must be comprised of elements of the same class as .obj. Elements of the list can be named.

.wst

Not yet used.

.all

A formula or formula_list.

Must be the same class as .obj.

.adj

Logical.

If TRUE then a model including only an intercept is submitted to .fct and the value returned is subtracted from the values returned from all subsets in the dominance analysis.

.cdl

Logical.

If FALSE then conditional dominance matrix is not computed.

.cpt

Logical.

If FALSE then complete dominance matrix is not computed.

.rev

Logical.

If TRUE then standardized vector, ranks, and complete dominance designations are reversed in their interpretation.

.cst

Object of class c("SOCKcluster", "cluster") from parallel-package.

When non-NULL, will alter the method for collecting values from all combinations of names from using sapply to parallel::parSapply.

.prg

Logical.

If TRUE then a progress bar is displayed during collection of values to indicate progress.

Notes

formula method

Prior to version 1.1.0, the formula method allowed a formula to be submitted to .adj. Submitting an intercept-only formula as opposed to a logical has been depreciated and submitting a formula with more than an intercept is defunct.

The formula and formula_list methods can be used to pass responses, intercepts, and offsets to all combinations of names. If the user seeks to include other model components integral to estimation (i.e., a random effect term in lme4::glmer()) include them as update to the submitted formula or formula_list imbedded in .fct.

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

Details

Element Parsing

.objs is parsed into a name list that is used to determine the required number of combinations of subsets of the name list included the dominance analysis. How the name list is obtained depends on .obj's class.

formula

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

A response/left hand side is not required but, if present, is included in all formulas passed to .fct.

formula_list

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

Additional Details

By default, names obtained from .obj are all considered separate 'value-generating names' with the same priority. Each value-generating name will be a separate element when computing combination subsets and will be compared to all other value-generating names.

formulas and formula_list elements are assumed to have an intercept except if explicitly removed with a - 1 in the formula(s) in .obj. If removed, the intercept will be removed in all formula(s) in each sapply-ed subset to .fct.

If offsets are included, they are passed, like intercepts, while sapply-ing subsets to .fct.

Changing Element Parsing

All methods' default behavior that considers all value-generating names to be of equal priority can be overriden using .set and .all arguments.

Names in .set and .all must also be present in .obj.

.set

.set binds together value-generating names such that they are of equal priority and are never separated when submitted to .fct. Thus, the elements in .set bound together contribute jointly to the returned value and are considered, effectively, a single value-generating name.

If list elements in .set are named, this name will be used in all returned results as the name of the set of value-generating names bound together.

.set thus considers the value-generating names an 'inseparable set' in the dominance analysis and are always included or excluded together.

.all

.all gives immediate priority to value-generating names. The value-generating names in .all are bound together, are ascribed their full amount of the returned value from .fct, and are not adjusted for contribution of other value-generating names.

The value of .fct ascribed to the value-generating names bound together in .all is returned separately from, and not directly compared to, the other value-generating names.

The formula method for .all does not allowthe submitted formula to have a left hand side.

.all includes the value-generating names in 'all subsets' submitted to the dominance analysis which effectively removes the value associated with this set of names.

.adj

.adj indicates that an intercept-only model should be supplied to .fct. This intercept-only subset is given most immediate priority and the value of .fct ascribed to it is removed from all other value-generating names and sets including those in .all.

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

.adj then 'adjusts' the returned value for a non-0 value-returning null model when no value generating names are included. This is often useful when a predictive model's fit metric is not 0 when no predictive factors are included in the model.

Additional Details

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

The all subsets of names will be submitted to .fct as the first, unnamed argument.

.fct as Analysis Pipeline

.fct is expected to be a complete analysis pipeline that receives a subset of names of the same class as .obj and uses these names in the class as submitted to generate a returned value of the appropriate type to dominance analyze. Typically, the returned value is a scalar fit statistic/metric extracted from a predictive model.

At current, only atomic (i.e., non-list), numeric scalars (i.e., vectors of length 1) are allowed as returned values.

The .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 .obj can be submitted to .fct without producing an error and whether the returned value from .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 .fct to satisfy the checks.

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
mlm_rxy <-
  function(fml, data, dvnames) {
    mlm_res <- lm(fml, data = data)
    mlm_pred <- predict(mlm_res)
    cancor(mlm_pred, data[dvnames])$cor[[1]]^2
  }

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


## 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
  )
}