nauf_model.frame: Create a model frame using 'nauf' contrasts.
In CDEager/nauf: Regression with NA Values in Unordered Factors

Description Usage Arguments Details Value See Also Examples

nauf_model.frame creates a model frame which employs nauf_contrasts for unordered factors.

1
2
3

nauf_model.frame(formula, data = NULL, subset = NULL, na.action = na.pass,
  drop.unused.levels = TRUE, xlev = NULL, contrasts = NULL,
  ncs_scale = attr(formula, "standardized.scale"), ...)

`formula, data, subset, ...`	See `model.frame`.
`na.action, drop.unused.levels, xlev, contrasts`	Changes from default values for these arguments are ignored with a warning.
`ncs_scale`	A positive number passed as the `scale` argument to `named_contr_sum` for all unordered factor contrasts. The default is to first check whether `formula` comes from a `standardized` object returned by `standardize`. If it is, then the `scale` argument from the `standardize` call is used. If it is not, then `ncs_scale` is set to `1`. The value for `ncs_scale` can also be set explicitly. If it is set explicitly and `formula` is from a `standardized` object with a different scale than the explicitly set value, then the explicitly set value is used and a warning is issued.

First, the default method for model.frame is called. Then any variable in the resulting model frame that is not an unordered factor but has only two unique non-NA values is coerced to an unordered factor. Unordered factors are then assigned contrasts with named_contr_sum, passing ncs_scale as the function's scale argument. Then, necessary contrast changes in interaction terms and random effects slopes are determined as described in nauf_contrasts.

The recommended usage is to first standardize the regression variables, and then use the formula and data elements in the resulting standardized object as arguments to nauf_model.frame. When this is done, ncs_scale is obtained from the standardized.scale attribute of the formula, unless ncs_scale is specified as a value which does not match the standardized scale, in which case the explicitly specified ncs_scale argument is used with a warning. If standardize is not used prior to calling nauf_model.frame, then ncs_scale defaults to 1 unless explicitly specified in the function call, in which case the specified value is used.

Changes from the following default values are ignored with a warning:

na.action = na.pass: This default value is required in order for NA values to be treated as defined in nauf_contrasts.
drop.unused.levels = TRUE: This default value is set because nauf_model.frame assumes that data is not new data. To create a nauf.frame with new data, the terms attribute of an already existing nauf.frame (which has class nauf.terms) can be used as the formula argument to model.frame.
xlev = NULL: This default is necessary for the same reasons as the default value for drop.unused.levels.
contrasts = NULL: For unordered factors, contrasts are automatically created with named_contr_sum, as sum contrasts are necessary to implement nauf_contrasts. To specify custom contrasts for ordered factors, the custom contrasts should be explicitly assigned to the ordered factor in data (this is automatically done if standardize is used first as recommended).

A model frame with second class attribute nauf.frame. Its formula attribute has class nauf.formula and its terms attribute has class nauf.terms.

nauf_contrasts for a description of the contrasts applied to unordered factors, nauf_model.matrix for obtaining a fixed effects model matrix, and nauf_glFormula for obtaining both fixed effects and random effects model matrices.

dat <- plosives
dat$spont[dat$dialect == "Valladolid"] <- NA
form <- intdiff ~ voicing * dialect * spont +
  (1 + voicing * spont | speaker) + (1 + dialect | item)

## default behavior when standardize is not used
# defaults to ncs_scale = 1
mf <- nauf_model.frame(form, dat)

# uses specified ncs_scale = 0.5
mf_0.5 <- nauf_model.frame(form, dat, ncs_scale = 0.5)

## standardize first (recommended use)
sobj <- standardize(form, dat)
sobj_0.5 <- standardize(form, dat, scale = 0.5)

# uses ncs_scale = 1 from attr(sobj$formula, "standardized.scale")
mf_sobj <- nauf_model.frame(sobj$formula, sobj$data)

# uses ncs_scale = 0.5 from attr(sobj_0.5$formula, "standardized.scale")
mf_sobj_0.5 <- nauf_model.frame(sobj_0.5$formula, sobj_0.5$data)

## Not run: 
## not recommended
# uses specified ncs_scale = 0.5 and issues a warning since
# attr(sobj$formula, "standardized.scale") = 1
mf_warning <- nauf_model.frame(sobj$formula, sobj$data, ncs_scale = 0.5)

## End(Not run)