cgam: Constrained Generalized Additive Model Fitting

Description

The partial linear generalized additive model is fitted using the method of maximum likelihood, where shape or order restrictions can be imposed on the non-parametrically modelled predictors with optional smoothing, and no restrictions are imposed on the optional parametrically modelled covariate.

Usage

1
2

Arguments

formula

A formula object which gives a symbolic description of the model to be fitted. It has the form "response ~ predictor". The response is a vector of length n. The specification of the model can be one of the three exponential families: gaussian, binomial and poisson. The systematic component η is E(y), the log odds of y = 1, and the logarithm of E(y) respectively. A predictor can be a non-parametrically modelled variable with or without a shape or order restriction, or a parametrically modelled unconstrained covariate. In terms of a non-parametrically modelled predictor, the user is supposed to indicate the relationship between the systematic component η and a predictor x in the following way:

Assume that η is the systematic component and x is a predictor:

incr(x): η is increasing in x. See incr for more details.

s.incr(x): η is smoothly increasing in x. See s.incr for more details.

decr(x): η is decreasing in x. See decr for more details.

s.decr(x): η is smoothly decreasing in x. See s.decr for more details.

conc(x): η is concave in x. See conc for more details.

s.conc(x): η is smoothly concave in x. See s.conc for more details.

conv(x): η is convex in x. See conv for more details.

s.conv(x): η is smoothly convex in x. See s.conv for more details.

incr.conc(x): η is increasing and concave in x. See incr.conc for more details.

s.incr.conc(x): η is smoothly increasing and concave in x. See s.incr.conc for more details.

decr.conc(x): η is decreasing and concave in x. See decr.conc for more details.

s.decr.conc(x): η is smoothly decreasing and concave in x. See s.decr.conc for more details.

incr.conv(x): η is increasing and convex in x. See incr.conv for more details.

s.incr.conv(x): η is smoothly increasing and convex in x. See s.incr.conv for more details.

decr.conv(x): η is decreasing and convex in x. See decr.conv for more details.

s.decr.conv(x): η is smoothly decreasing and convex in x. See s.decr.conv for more details.

s(x): η is smooth in x. See s for more details.

tree(x): η has a tree-ordering in x. See tree for more details.

umbrella(x): η has an umbrella-ordering in x. See umbrella for more details.

nsim

The number of simulations used to get the cic parameter. The default is nsim = 1e+2.

family

A parameter indicating the error distribution and link function to be used in the model. It can be a character string naming a family function or the result of a call to a family function. This is borrowed from the glm routine in the stats package. There are three families used in cgam: gaussian, binomial, poisson, and Gamma. Note that if family = Ord is specified, a proportional odds regression model with shape constraints is fitted. This is under development.

cpar

A multiplier to estimate the model variance, which is defined as σ^2 = SSR / (n - cpar * edf). SSR is the sum of squared residuals for the full model and edf is the effective degrees of freedom. The default is cpar = 1.2. The user-defined value must be between 1 and 2. See Meyer, M. C. and M. Woodroofe (2000) for more details.

data

An optional data frame, list or environment containing the variables in the model. The default is data = NULL.

weights

An optional non-negative vector of "replicate weights" which has the same length as the response vector. If weights are not given, all weights are taken to equal 1. The default is weights = NULL.

sc_x

Logical flag indicating if or not continuous predictors are normalized. The default is sc_x = FALSE.

sc_y

Logical flag indicating if or not the response variable is normalized. The default is sc_y = FALSE.

pen

User-defined penalty parameter. It must be non-negative. It will only be used in a warped-plane spline fit or a triangle spline fit. The default is pen = 0.

pnt

Logical flag indicating if or not penalized constrained regression splines are used. It will only be used in a warped-plane spline fit or a triangle spline fit. The default is pnt = TRUE.

Details

We consider generalized partial linear models with independent observations from an exponential family of the form p(y_i;θ,τ) = exp[\{y_iθ_i - b(θ_i)\}τ - c(y_i, τ)], i = 1,…,n, where the specifications of the functions b and c determine the sub-family of models. The mean vector μ = E(y) has values μ_i = b'(θ_i), and is related to a design matrix of predictor variables through a monotonically increasing link function g(μ_i) = η_i, i = 1,…,n, where η is the systematic component and describes the relationship with the predictors. The relationship between η and θ is determined by the link function b.

For the additive model, the systematic component is specified for each observation by η_i = f_1(x_{1i}) + … + f_L(x_{Li}) + z_i'β, where the functions f_l describe the relationships of the non-parametrically modelled predictors x_l, β is a parameter vector, and z_i contains the values of variables to be modelled parametrically. The non-parametric components are modelled with shape or order assumptions with optional smoothing, and the solution is obtained through an iteratively re-weighted cone projection, with no back-fitting of individual components.

Suppose that η is a n by 1 vector. The matrix form of the systematic component and the predictor is η = φ_1 + … + φ_L + Zβ, where φ_l is the individual component for the lth non-parametrically modelled predictor, l = 1, …, L, and Z is an n by p design matrix for the parametrically modelled covariate.

To model the component φ_l, smooth regression splines or non-smooth ordinal basis functions can be used. The constraints for the component φ_l are in C_l. In the first case, C_l = \{φ_l \in R^n: φ_l = v_l+B_lβ_l, where β_l ≥ 0 and v_l\in V_l \}, where B_l has regression splines as columns and V_l is the linear space contained in C_l, and in the second case, C_l = \{φ \in R^n: A_lφ ≥ 0 and B_lφ = 0\}, for inequality constraint matrix A_l and equality constraint matrix B_l.

The set C_l is a convex cone and the set C = C_1 + … + C_p + Z is also a convex cone with a finite set of edges, where the edges are the generators of C, and Z is the column space of the design matrix Z for the parametrically modelled covariate.

An iteratively re-weighted cone projection algorithm is used to fit the generalized regression model over the cone C.

Value

etahat

The fitted systematic component η.

muhat

The fitted mean value, obtained by transforming the systematic component η by the inverse of the link function.

vcoefs

The estimated coefficients for the basis spanning the null space of the constraint set.

xcoefs

The estimated coefficients for the edges corresponding to the smooth predictors with no shape constraint and shape-restricted predictors.

zcoefs

The estimated coefficients for the parametrically modelled covariate, i.e., the estimation for the vector β.

ucoefs

The estimated coefficients for the edges corresponding to the predictors with an umbrella-ordering constraint.

tcoefs

The estimated coefficients for the edges corresponding to the predictors with a tree-ordering constraint.

coefs

The estimated coefficients for the basis spanning the null space of the constraint set and edges corresponding to the shape-restricted and order-restricted predictors.

cic

The cone information criterion proposed in Meyer(2013a). It uses the "null expected degrees of freedom" as a measure of the complexity of the model. See Meyer(2013a) for further details of cic.

d0

The dimension of the linear space contained in the cone generated by all constraint conditions.

edf0

The estimated "null expected degrees of freedom". It is a measure of the complexity of the model. See Meyer (2013a) and Meyer (2013b) for further details.

edf

The constrained effective degrees of freedom.

etacomps

The fitted systematic component value for non-parametrically modelled predictors. It is a matrix of which each row is the fitted systematic component value for a non-parametrically modelled predictor. If there are more than one such predictors, the order of the rows is the same as the order that the user defines such predictors in the formula argument of cgam.

y

The response variable.

xmat_add

A matrix whose columns represent the shape-restricted predictors and smooth predictors with no shape constraint.

zmat

A matrix whose columns represent the basis for the parametrically modelled covariate. The user can choose to include a constant vector in it or not. It must have full column rank.

ztb

A list keeping track of the order of the parametrically modelled covariate.

tr

A matrix whose columns represent the predictors with a tree-ordering constraint.

umb

A matrix whose columns represent the predictors with an umbrella-ordering constraint.

tree.delta

A matrix whose rows are the edges corresponding to the predictors with a tree-ordering constraint.

umbrella.delta

A matrix whose rows are the edges corresponding to the predictors with an umbrella-ordering constraint.

bigmat

A matrix whose rows are the basis spanning the null space of the constraint set and the edges corresponding to the shape-restricted and order-restricted predictors.

shapes

A vector including the shape and partial-ordering constraints in a cgam fit.

shapesx

A vector including the shape constraints in a cgam fit.

prior.w

User-defined weights.

wt

The weights in the final iteration of the iteratively re-weighted cone projections.

wt.iter

Logical flag indicating if or not iteratively re-weighted cone projections may be used. If the response is gaussian, then wt.iter = FALSE; if the response is binomial or poisson, then wt.iter = TRUE.

family

The family parameter defined in a cgam formula.

SSE0

The sum of squared residuals for the linear part.

SSE1

The sum of squared residuals for the full model.

pvals.beta

The approximate p-values for the estimation of the vector β. A t-distribution is used as the approximate distribution.

se.beta

The standard errors for the estimation of the vector β.

null_df

The degree of freedom for the null model of a cgam fit, i.e., the model only containing a constant vector.

df

The degree of freedom for the null space of a cgam fit.

resid_df_obs

The observed degree of freedom for the residuals of a cgam fit.

null_deviance

The deviance for the null model of a cgam fit, i.e., the model only containing a constant vector.

capm

The number of edges corresponding to the shape-restricted predictors.

capms

The number of edges corresponding to the smooth predictors with no shape constraint.

capk

The number of non-constant columns of zmat.

capt

The number of edges corresponding to the tree-ordering predictors.

capu

The number of edges corresponding to the umbrella-ordering predictors.

xid1

A vector keeping track of the beginning position of the set of edges in bigmat for each shape-restricted predictor and smooth predictor with no shape constraint in xmat.

xid2

A vector keeping track of the end position of the set of edges in bigmat for each shape-restricted predictor and smooth predictor with no shape constraint in xmat.

tid1

A vector keeping track of the beginning position of the set of edges in bigmat for each tree-ordering factor in tr.

tid2

A vector keeping track of the end position of the set of edges in bigmat for each tree-ordering factor in tr.

uid1

A vector keeping track of the beginning position of the set of edges in bigmat for each umbrella-ordering factor in umb.

uid2

A vector keeping track of the end position of the set of edges in bigmat for each umbrella-ordering factor in umb.

zid

A vector keeping track of the positions of the parametrically modelled covariate.

vals

A vector storing the levels of each variable used as a factor.

zid1

A vector keeping track of the beginning position of the levels of each variable used as a factor.

zid2

A vector keeping track of the end position of the levels of each variable used as a factor.

nsim

The number of simulations used to get the cic parameter.

xnms

A vector storing the names of the shape-restricted predictors and the smooth predictors with no shape constraint in xmat.

ynm

The name of the response variable.

znms

A vector storing the names of the parametrically modelled covariate.

is_param

A logical scalar showing if or not a variable is a parametrically modelled covariate, which could be a linear term or a factor.

is_fac

A logical scalar showing if or not a variable is a factor.

knots

A list storing the knots used for each shape-restricted predictor and smooth predictor with no shape constraint. For a smooth, constrained and a smooth, unconstrainted predictor, knots is a vector of more than 1 elements, and for a shape-restricted predictor without smoothing, knots = 0.

numknots

A vector storing the number of knots for each shape-restricted predictor and smooth predictor with no shape constraint. For a smooth, constrained and a smooth, unconstrainted predictor, numknots > 1, and for a shape-restricted predictor without smoothing, numknots = 0.

sps

A character vector storing the space parameter to create knots for each shape-restricted predictor.

ms

The centering terms used to make edges for shape-restricted predictors.