check.tols: Construct and Check Tolerance Input
In optweight: Targeted Stable Balancing Weights Using Optimization

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/check_functions.R

Checks whether proposed tolerance values for tols are suitable in number and order for submission to optweight. Users should include one value per item in formula. The output can also be used as an input to tols in optweight.

check.tols(formula,
           data = NULL,
           tols,
           stop = FALSE)

## S3 method for class 'optweight.tols'
print(x, internal = FALSE, digits = 5, ...)

`formula`	A formula with the covariates to be balanced with `optweight` on the right hand side. See `glm` for more details. Interactions and functions of covariates are allowed. Lists of formulas are not allowed; multiple formulas must be checked one at a time.
`data`	An optional data set in the form of a data frame that contains the variables in `formula`.
`tols`	A vector of balance tolerance values in standardized mean difference units for each covariate. These should be in the order corresponding to the order of the corresponding variable in `formula`, except for interactions, which will appear after all lower-order terms. If only one value is supplied, it will be applied to all covariates.
`stop`	`logical`; if `TRUE`, an error will be thrown if the number of values in `tols` is not equal to the correct number of covariates in `formula`, and no messages will be displayed if the `tols` input is satisfactory. If `FALSE`, a message will be displayed if the number of values in `tols` is not equal to the correct number of covariates in `formula`, and other messages will be displayed.
`x`	An `optweight.tols` object; the output of a call to `check.tols`.
`internal`	`logical`; whether to print the tolerance values that are to be used internally by `optweight`. See Value section.
`digits`	How many digits to print.
`...`	Ignored.

The purpose of check.tols is to allow users to ensure that their proposed input to tols in optweight is correct both in the number of entries and their order. This is especially important when factor variables and interactions are included in the formula because factor variables are split into several dummies and interactions are moved to the end of the variable list, both of which can cause some confusion and potential error when entering tols values.

Factor variables are internally split into a dummy variable for each level, but the user only needs to specify one tolerance value per original variable; check.tols automatically expands the tols input to match the newly created variables.

Interactions (e.g., a:b or a*b in the formula input) are always sent to the end of the variable list even if they are specified elsewhere in the formula. It is important to run check.tols to ensure the order of the proposed tols corresponds to the represented order of covariates used in optweight. You can run check.tols with no tols input to see the order of covariates that is required.

check.tols was designed to be used primarily for its message printing and print method, but you can also assign its output to an object for use as an input to tols in optweight.

Note that only one formula and vector of tolerance values can be assessed at a time; for multiple treatment periods, each formula and tolerance vector must be entered seperately.

An optweight.tols object, which is a named vector of tolerance values, one for each variable specified in formula. This should be used as user inputs to optweight. The "internal.tols" attribute contains the tolerance values to be used internally by optweight. These will differ from the vector values when there are factor variables that are split up; the user only needs to submit one tolerance per factor variable, but seperate tolerance values are produced for each new dummy created.

Noah Greifer

check.targets

library("cobalt")
data("lalonde", package = "cobalt")

#Checking if the correct number of entries are included:
check.tols(treat ~ age + educ + married +
                nodegree + re74, data = lalonde,
                tols = c(.01, .02, .03, .04))

#Checking the order of interactions; notice they go
#at the end even if specified at the beginning. The
#.09 values are where the interactions might be expected
#to be, but they are in fact not.
c <- check.tols(treat ~ age:educ + married*race +
                nodegree + re74, data = lalonde,
                tols = c(.09, .01, .01, .09, .01, .01))

print(c, internal = TRUE)