g: Defining terms in CGAIM formula

Description

Functions used to define terms within a cgaim formula. g defines an index with ridge function and s a smooth covariate.

Usage

g(..., label = NULL, acons = list(), Cmat = NULL, bvec = 0,
  fcons = NULL, s_opts = list())
s(x, fcons = NULL, s_opts = list())

Value

A matrix containing the variables passed in ... with additional attributes:

fcons: The shape constraint for smoothing.
s_opts: Arguments passed to the smoothing function.
label: The label of the term.

The following attributes result from a call to g only:

term: The terms in the index.
nterms: The number of variables in the index.
Cmat: The constraint matrix for alpha coefficients.
bvec: The associated boundary vector.

Arguments

...: Variables entering the index. May include vectors and matrices.
label: Character (or any object that can coerced into one) labeling the index. By default, named after the first variable in ....
acons: A list of character naming common constraints to be applied to the index weights alpha. See build_constraints for allowed constraints.
Cmat: A constraint matrix for alpha coefficients. Number of columns must match the number of variables in the index.
bvec: Numeric vector of constraint bounds. Recycled if necessary.
fcons: The type of shape constraint to be applied on the smooth function. See details.
s_opts: A named list of options to be passed to the smoothing of ridge functions. Depends on the method used to smooth additive models. See details.
x: Covariate on which the smooth is applied.

Details

These functions define nonlinear terms in the formula, with g defining an index created from a collection of terms passed through the ... argument while s is applied to a single variable, similarly to s in mgcv.

For indices, g allows the definition of constraints applied to the index only. This is a convenient alternative to passing the whole constraint matrix Cmat in cgaim. Constraints can be defined by a prespecified matrix through the argument Cmat or through the argument acons for common constraints (see build_constraints). Note that any provided Cmat must match the total number of variables in ..., including potential matrix expansion and factors. Both Cmat and acons can be passed to the function, which will bind them internally.

Both g and s allow the definition of shape constraints for the smooth. Eight shape-constraints are currently available: monotone increasing (fcons = "inc"), monotone decreasing (fcons = "dec"), convex (fcons = "cvx"), concave (fcons = "ccv"), increasing and convex(fcons = "inccvx"), decreasing and convex (fcons = "deccvx"), increasing and concave (fcons = "incccv"), decreasing and concave (fcons = "decccv").

Smoothing can be controlled by the s_opts parameter. It is a list of argument depends on the method used for smoothing. See s for smooth_method = "scam". For smooth_method = "cgam", the parameters allowed may vary according to the shape-constraint chosen. The full list can be found in cgam, but only the constraints beginning with s. are allowed for now. No parameter are necessary when smooth_method = "scar" (see scar).

Examples

Run this code

## Simulate some data
n <- 200
x1 <- rnorm(n)
x2 <- rnorm(n)
x3 <- rnorm(n)
x4 <- rnorm(n)
mu <- 4 * exp(8 * x1) / (1 + exp(8 * x1)) + exp(x3)
y <- mu + rnorm(n)
df1 <- data.frame(y, x1, x2, x3, x4)

## Fit an unconstrained the model
ans <- cgaim(y ~ g(x1, x2) + g(x3, x4), data = df1)

## Fit constrained model
ans2 <- cgaim(y ~ g(x1, x2, acons = list(monotone = -1)) + 
  g(x3, x4, fcons = "cvx"), data = df1)
  
## Pass constraint matrices instead
ans3 <- cgaim(y ~ g(x1, x2, Cmat = -diff(diag(2))) + 
  g(x3, x4, fcons = "cvx"), data = df1)
  
## Label indices   
ans4 <- cgaim(y ~ g(x1, x2, label = "foo") + g(x3, x4, label = "bar"), 
  data = df1)