Parse Formula

Parse a formula to extract terms and handle special functions

Usage

parseFormula(
  formula,
  data = NULL,
  specials,
  special.default.values = NULL,
  alias.names = NULL
)

Arguments

formula

A model formula (e.g., Y ~ X + Z or Y ~ fun(X, param = value)).

data

An optional data frame containing the variables referenced in the formula.

specials

A character vector of special function names that should be specifically handled.

special.default.values

A named list of named lists specifying default argument values for each special.

alias.names

A named list mapping special names to their alias(es) (e.g., `list("special" = "alias")`).

Value

A list where each element corresponds to a special function in the formula and contains the parsed terms and their arguments.

A named list with an element for each special that contains a named list where each element corresponds to a formula term that is affected by the special that contains the value(s) of the additional argument(s) for this term.

Details

This function parses a model formula, extracts terms, and processes specified 'special' functions and their arguments. It allows defining default values for special functions and specifying aliases for those names.

See also

[stats::terms()], [strip.terms()]

model.design strip.terms

Author

Thomas A. Gerds <[email protected]>

Examples

# Basic usage with specials
parseFormula(Y ~ fun(X, a = 1), specials = "fun")
#> $fun
#> list()
#> 

# With defaults and aliases
parseFormula(Y ~ gfun(X, a = 7), 
             specials = "fun", 
             alias.names = list("fun" = "gfun"),
             special.default.values = list("fun" = list("a" = 0)))
#> list()

# Complex use case with multiple specials
parseFormula(Surv(time, status) ~ age + strata(sex, test = 1) + prop(albumin),
             specials = c("prop", "strata"), 
             special.default.values = list("prop" = list(power = 0), "strata" = list(test = 1)))
#> $prop
#> $prop$albumin
#> $prop$albumin$power
#> [1] 0
#> 
#> 
#> 
#> $strata
#> $strata$sex
#> $strata$sex$test
#> [1] 1
#> 
#> 
#> 
parseFormula(Y~fun(X,a=1),specials="fun",special.default.values=list("fun"=list("a"=0)))
#> $fun
#> $fun$X
#> $fun$X$a
#> [1] 1
#> 
#> 
#> 
parseFormula(Y~fun(X),specials="fun",special.default.values=list("fun"=list("a"=0)))
#> $fun
#> $fun$X
#> $fun$X$a
#> [1] 0
#> 
#> 
#> 
parseFormula(Y~gfun(X,a=7),specials="fun",
             alias.names=list("fun"="gfun"),
             special.default.values=list("fun"=list("a"=0)))
#> list()
parseFormula(formula = Surv(time,status)~age
                            +const(factor(edema))
                            +strata(sex,test=0)
                            +prop(alb)+prop(bili,power=1)
                            +tp(albumin),
                  specials = c("prop","timevar","strata","tp","const"),
                  special.default.values =list("prop" = list(power = 0),
                                               "strata" = list(test = 1)))
#> $prop
#> $prop$alb
#> $prop$alb$power
#> [1] 0
#> 
#> 
#> $prop$bili
#> $prop$bili$power
#> [1] 1
#> 
#> 
#> 
#> $strata
#> $strata$sex
#> $strata$sex$test
#> [1] 0
#> 
#> 
#> 
#> $tp
#> list()
#> 
#> $const
#> list()
#> 
parseFormula(formula = Surv(time,status)~age
                            +const(factor(edema))
                            +strata(sex,test=0)
                            +prop(alb)+prop(bili,power=1)
                            +tp(albumin),
                  specials = c("prop","timevar","strata","tp"),
                  special.default.values =list("prop" = list(power = 0),
                                               "strata" = list(test = 1)),
                  alias.names=list("prop"="const"))
#> list()