domir {domir} R Documentation

## Dominance analysis methods

### Description

Parses input object to obtain valid elements, determines all required combinations/subsets of elements (depends on input type), submits subsets to a function, and computes dominance decomposition statistics based on the returned values from the function.

### Usage

domir(.obj, ...)

## S3 method for class 'formula'
domir(
.obj,
.fct,
.set = NULL,
.wst = NULL,
.all = NULL,
.cdl = TRUE,
.cpt = TRUE,
.rev = FALSE,
...
)

## S3 method for class 'Formula'
domir(...)

## S3 method for class 'list'
domir(...)


### Arguments

 .obj A formula, Formula, or list. Parsed to produce subsets of elements to submit to .fct. Always submits subsets of .obj the same type to .fct as the same type or class as the input object. ... Passes arguments to other methods; passes arguments to function in .fct. .fct A function/closure 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 type or class as .obj. Elements of the list can be named. .wst Not yet used. .all A formula, Formula, or list. Must be the same type or class as .obj. .adj A formula, Formula, or list. Must be the same type or class as .obj. .cdl Logical. If FALSE then conditional dominance matrix is not computed and method to produce general dominance statistics changes. .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.

### Details

#### Element Parsing

.objs elements are parsed and used to determine the required number of subsets included the dominance analysis. How the elements are parsed is determined depends on .objs type or class method.

##### formula

The formula method applies the standard terms function parsing which separates term names on the right hand side of the formula. All terms separated by + are considered a separate element for generating subsets.

Any terms on the left hand side of .obj are retained and passed through to all subsets.

##### Formula and list

The Formula and list methods are not yet implemented.

By default, each parsed element in .obj will be used as a separate element to generate subsets and will obtain a separate contribution to the returned value.

#### Changing Element Parsing

All methods' default behavior of using all elements to generate subsets can be overriden using .set, .all, and .adj arguments.

Elements in .set, .all, and .adj must also be present in .obj. The entries in three arguments change .objs parsing behavior but still depend on .obj as the primary input object.

##### .set

.set binds together elements in .obj such that they form a single new element. The elements in .obj bound together contribute jointly to the returned value.

If elements in .set are named, the .set element's name will be used in the "domir" object returned and all printed results.

The formula method for .set does not allow any element to have a left hand side.

##### .all

.all binds elements in .obj to all subsets. The elements in .obj bound together by .all are given precedence in ascribing the returned value and contribute jointly to Value_All. Value_All is determined prior to conducting the dominance analysis and its value is removed from the returned values for all subsets.

The formula method for .all does not allow a left hand side.

##### .adj

.adj binds elements in .obj to all subsets. The elements in .obj bound together by .adj are considered external to the dominance analysis but are adjusted for given they affect the returned value. Elements in .adj contribute jointly to Value_Adjust and have a higher precedence than those bound in .all. Value_Adjust is determined prior to conducting the dominance analysis and its value is removed from the returned values for all subsets as well as from Value_All.

The formula method for .adj does not allow a left hand side but allows constants/intercepts (i.e., ~ 1) to be included as a valid element in the right hand size even when not explicitly included in .obj.

All element parsing methods for domir will submit subsets generated as an object of the same type as .obj (i.e., a formula in .obj will be submitted as a formula) to the .fct as the first, unnamed argument.

#### .fct as Analysis Pipeline

The function in .fct will be called repeatedly, once for each subset of elements created from .obj.

.fct is expected to be a complete analysis pipeline that receives a subset of elements from .obj, uses the subset of elements from .obj in the type/class as received to generate a predictive model, and extracts a returned value of the appropriate type to dominance analyze.

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

domir is intended to be strict about input and output requirements for functions in .fct and applies a series of checks to ensure the input and output adhere to these requirements. In most circumstances, the user will have to make their own named or anonymous function to supply to .fct to meet domirs requirements.

### Value

Returns an object of class "domir" which is a composed of the following elements:

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

Logical matrix of complete dominance designations. The .obj elements represented in each row indicates dominance status; the .obj elements represented in each column indicates dominated-by status.

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.

### Examples

## Basic linear model with r-square

lm_r2 <- function(fml, data) {
lm_res <- lm(fml, data = data)
r2 <- summary(lm_res)[["r.squared"]]
return(r2) }

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 linear model 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)
mlm_rxy <- cancor(mlm_pred, data[dvnames])\$cor[[1]]^2
return(mlm_rxy)
}

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 using AIC

lm_aic <- function(fml, data) {
lm_res <- lm(fml, data = data)
aic <- AIC(lm_res)
return(aic) }

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


[Package domir version 1.0.0 Index]