nauf (version 1.1.0)

nauf_model.frame: Create a model frame using nauf contrasts.

Description

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

Usage

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"), ...)

Arguments

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.

Value

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

Details

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).

See Also

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.

Examples

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 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)