Construct and Check Tolerance Input

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.

Usage

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

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

Arguments

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.

Value

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.

Details

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.

Author

Noah Greifer

See also

check.targets

Examples

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))
#> tols must contain 5 numbers. 4 were included.
#> All values in the output have been assigned NA.
#> - vars:
#> 	age   educ   married   nodegree   re74

#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)
#> - tols:
#>      married         race     nodegree         re74     age:educ married:race 
#>         0.09         0.01         0.01         0.09         0.01         0.01 
#> 
#> - tols used internally by optweight:
#>             married          race_black         race_hispan          race_white 
#>                0.09                0.01                0.01                0.01 
#>            nodegree                re74            age:educ  married:race_black 
#>                0.01                0.09                0.01                0.01 
#> married:race_hispan  married:race_white 
#>                0.01                0.01