domir {domir}  R Documentation 
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.
domir(.obj, ...)
## S3 method for class 'formula'
domir(
.obj,
.fct,
.set = NULL,
.wst = NULL,
.all = NULL,
.adj = FALSE,
.cdl = TRUE,
.cpt = TRUE,
.rev = FALSE,
...
)
## S3 method for class 'formula_list'
domir(
.obj,
.fct,
.set = NULL,
.wst = NULL,
.all = NULL,
.adj = FALSE,
.cdl = TRUE,
.cpt = TRUE,
.rev = FALSE,
...
)
.obj 
A Parsed to produce list of names. Combinations of subsets the name list are

... 
Passes arguments to other methods during method dispatch;
passes arguments to the function in 
.fct 
A Applied to all subsets of elements as received from 
.set 
A Must be comprised of elements of the same class as 
.wst 
Not yet used. 
.all 
A Must be the same class as 
.adj 
Logical. If 
.cdl 
Logical. If 
.cpt 
Logical. If 
.rev 
Logical. If 
.obj
s 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 formula
s passed to .fct
.
formula_list
The formula_list
creates a name list out of responseterm pairs.
The terms are obtained using terms.formula
applied to each individual
formula in the list.
By default, names obtained from .obj
are all considered separate
'valuegenerating names' with the same priority.
Each valuegenerating name will be a separate element when
computing combination subsets and will be compared to all other
valuegenerating names.
formula
s and formula_list
elements are assumed to have an intercept
except if excplicitly 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 offset
s are included, they are passed, like intercepts, while
sapply
ing subsets to .fct
. Currently, only the formula_list
method
allows offsets
.
All methods' default behavior that considers all valuegenerating 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 valuegenerating names such that
they are of equal priority and are never separated when submitted to
.fct
.
Thus, the elements in .obj
bound together contribute jointly to the
returned value and are considered, effectively, a single
valuegenerating name.
If list elements in .set
are named, this name will be used in all
returned results as the name of the set of valuegenerating names bound
together.
.set
thus considers the valuegenerating names an 'inseparable set' in the
dominance analysis and are always included or excluded together.
.all
.all
gives immediate priority to valuegenerating names.
The valuegenerating 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 valuegenerating names.
The value of .fct
ascribed to the valuegenerating names bound
together in .all
is returned separately from, and not directly
compared to, the other valuegenerating names.
The formula
method for .all
does not allow a left hand side.
.all
includes the valuegenerating 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 interceptonly model should be supplied to .fct
.
This interceptonly subset is given most immediate priority and the
value of .fct
ascribed to it is removed from all other
valuegenerating names and groups including those in .all
.
The formula
method will submit an interceptonly formula to .fct
.
The formula_list
method creates a separate, interceptonly subset for each
of the formula
s in the list.
Both the formula
and formula_list
methods will respect the user's
removal of an intercept. The formula_list
method will also respect the
user's inclusion of an offset
and will include them in the submission to
.fct
.
.adj
then 'adjusts' the returned value for a non0 valuereturning
null model when no value generating names are included.
All methods submit combinations of subsets of names as an
object of the same class as .obj
.
A formula
in .obj
will submit all combinations of subsets of names
as formula
s to .fct
.
A formula_list
in .obj
will submit all combinations of subsets of names
as formula_list
s to .fct
.
In the case that .fct
requires a different class
(i.e.,
a 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 PipelineThe function sapply
ed and to which the combinations of subsets of
names will be applied.
.fct
is expected to be a complete analysis pipeline that receives a
subset of names of the same class
as .obj
, uses the names in the
class
as submitted to generate a returned value of the appropriate
type to dominance analyze. Typically, this returned value is a
fit statistic extracted from a predictive model.
At current, only atomic (i.e., nonlist
), 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 and applies 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.
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
Logical matrix of complete dominance
designations.
The .obj
elements represented in each row indicates dominance status;
the .obj
elements represented in each column indicates
dominatedby 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.
formula
methodPrior to version 1.1.0, the formula
method allowed a formula
to be submitted to .adj
.
Submitting an interceptonly 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 in some cases, offset
s to all combinations of subsets
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
.
Secondorder or higher terms (i.e., interactions like~ a*b
) are parsed
by default but not used differently from firstorder terms for producing
subsets. The values ascribed to such terms may not be valid unless
the user ensures that secondorder and
higher terms are used appropriately in .fct
.
## Linear model returning rsquare
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 rsquare 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
)
}