Learn R Programming

cgam (version 1.34)

shapeselect: Shape selection for constrained additive models

Description

Fits an additive model by selecting variables with shape or order constraints for each predictor using Cone Information Bayesian Criterion (CBIC). The function can perform forward selection or stepwise (forward/backward) updates over a set of candidate shapes appropriate to each predictor type.

Usage

shapeselect(
  xmat,
  y,
  types = NULL,
  direction = c("both", "forward"),
  family = gaussian(link = "identity"),
  boundary.knots = NULL,
  nsim = 500,
  pnt = TRUE,
  parallel = FALSE,
  user_edfus = NULL,
  scale.method = c("minmax", "zscore", "none"),
  set4 = FALSE,
  tune = c("cv5", "cv10", "gcv", "none"),
  cv_seed = 123
)

Value

An object of class "shapeselect" containing the fitted model and the selection results. Important components include:

shps

Numeric shape code for each predictor; zero denotes an unselected predictor.

shapes

Character labels describing the selected shape for each predictor.

active

Indices of the selected predictors.

active_shps

Shape codes for the selected predictors.

mod_tried

Data frame recording the selection path and criterion values.

etahat

Fitted linear predictors.

muhat

Fitted mean responses on the response scale.

etacomps

Data frame of fitted component contributions, with one row per original predictor.

coefskeep

Estimated coefficients for the final model.

For numeric predictors, the shape codes are 9 (smooth increasing), 10 (smooth decreasing), 11 (smooth convex), 12 (smooth concave), 13 (smooth increasing convex), 14 (smooth increasing concave), 15 (smooth decreasing convex), 16 (smooth decreasing concave), and 19 (smooth unconstrained). When set4 = TRUE, only codes 9--12 and 19 are considered. Code 0 denotes a numeric predictor that is not selected; the corresponding label in shapes is "out of the model". Code 17 represents a flat shape when it occurs in the fitted object.

For nominal predictors, code 1 denotes that the predictor is included in the model, and code 0 denotes that it is not selected. Their corresponding labels in shapes are "in the model" and "out of the model", respectively.

Arguments

xmat

A data frame or matrix of predictors. Numeric predictors should be used with types = "num", and factor predictors with types = "nom". Column names are used in the output when available. Numeric predictors are fitted using shape-constrained smooth functions, whereas nominal predictors are included in or excluded from the model.

y

A response vector with length equal to nrow(xmat). For a Gaussian model, y should be numeric; for a binomial model, it should be binary.

types

A character vector of length ncol(xmat) specifying the type of each predictor. Currently supported values are "num" for numeric predictors and "nom" for nominal categorical predictors.

direction

The direction of the model search. "forward" performs forward selection of predictors and their shapes. "both" performs forward selection followed by backward revisions, including the removal of predictors. The default is "both".

family

A family object or a character string naming a family function. It specifies the error distribution and link function, as in glm(). Currently supported families are Gaussian and binomial.

boundary.knots

An optional list of boundary knots for the numeric predictors. The default is NULL. For a numeric predictor, the corresponding element should be a numeric vector containing at least two finite values, such as the values returned by range(x, na.rm = TRUE). For a nominal predictor, the corresponding element should be NULL.

nsim

The number of simulations used to estimate the mean effective degrees of freedom in the CBIC calculation at each selection step.

pnt

Logical; if TRUE, include penalty-related calculations during model fitting. The default is TRUE.

parallel

Logical. Whether to enable parallel computation. The default is FALSE. If parallel is TRUE, then the default number of cores = 2. To use a different number of cores for example, to use 4 cores, run: options(cgam.cores = 4L)

user_edfus

An optional numeric vector of three positive finite starting effective degrees of freedom. If NULL, starting values are determined automatically and tuned before variable selection. This argument is primarily intended for package maintenance and development.

scale.method

The scaling method for numeric predictors. "minmax" scales each predictor to the unit interval, "zscore" standardizes each predictor using its mean and standard deviation, and "none" performs no scaling. The default is "minmax".

set4

Logical; if TRUE, consider only the four basic smooth shapes for numeric predictors: increasing, decreasing, convex, and concave. If FALSE, also consider combined monotonicity-and-curvature shapes.

tune

The method used to tune the effective degrees of freedom of selected numeric predictors. Choices are "cv5", "cv10", "gcv", and "none". The default is "cv5".

cv_seed

An integer random seed used for cross-validation when tune is not "none". The default is 123.

Details

The algorithm begins with an intercept-only fit, then evaluates each inactive predictor under a set of allowable shapes (depending on types). At each step it selects the predictor/shape combination that improves the chosen information criterion.

Examples

Run this code
# Example 1: gaussian response, two numeric predictors, unpenalized
library(MASS)
data("Rubber", package = "MASS")
y <- Rubber[, 1]
xmat <- Rubber[, -1]
# the sample size = 30. For a small sample, it is better to use pnt = FALSE
ans <- shapeselect(xmat, y, types = c("num", "num"), pnt = FALSE)
# print out the chosen predictors and their shapes
print (ans)
# plot chosen components
plot(ans)
# make a prediction
xtest <- data.frame(hard = mean(Rubber$hard), tens = mean(Rubber$tens))
pfit <- predict(ans, xtest, type = "response")$fit

# Example 2: binomial response, one nominal predictor and six numeric predictors, penalized 
# each numeric predictor has 4 shape options
data(Pima.tr, package = "MASS")

df <- Pima.tr |> dplyr::filter(age <= 70) |>
  dplyr::mutate(npreg_grp = cut(npreg, breaks = c(-Inf, 0, 1, 5, 9, Inf),
      labels = c("0", "1", "2", "3", "4"), ordered_result = FALSE)) |>
  dplyr::select(-npreg) |>
  dplyr::select(npreg_grp, dplyr::everything())

y <- as.integer(df$type == "Yes")
xmat <- df[, 1:7, drop = FALSE]

# Default nsim = 500
if (FALSE) {
ans <- shapeselect(xmat, y, types = c("nom", rep("num", 6)), family = "binomial",
  nsim = 200, pnt = TRUE, set4 = TRUE)

print(ans)
plot(ans)
}

Run the code above in your browser using DataLab