sitar: Fit SITAR growth curve model

In statist7/sitar: Super Imposition by Translation and Rotation Growth Curve Analysis

Fit SITAR growth curve model

Description

SITAR is a method of growth curve analysis, based on nlme, that summarises a set of growth curves with a mean growth curve as a regression spline, plus a set of up to four fixed and random effects (a, b, c and d) defining how individual growth curves differ from the mean curve.

Usage

sitar(
  x,
  y,
  id,
  data,
  df,
  knots,
  fixed = NULL,
  random = "a + b + c",
  pdDiag = FALSE,
  a.formula = ~1,
  b.formula = ~1,
  c.formula = ~1,
  d.formula = ~1,
  d.adjusted = FALSE,
  stype = c("nsk", "ns"),
  bounds = 0.04,
  start,
  xoffset = "mean",
  bstart = xoffset,
  returndata = FALSE,
  verbose = FALSE,
  correlation = NULL,
  weights = NULL,
  subset = NULL,
  method = "ML",
  na.action = na.fail,
  control = nlmeControl(msMaxIter = 100, returnObject = TRUE),
  keep.data = TRUE
)

## S3 method for class 'sitar'
update(object, ..., evaluate = TRUE)

Arguments

x	vector of ages.
y	vector of measurements.
id	factor of subject identifiers.
data	data frame containing variables x, y and id.
df	degrees of freedom for cubic regression spline (0 or more, see Details).
knots	vector of values for knots (default df quantiles of x distribution).
fixed	character string specifying a, b, c, d fixed effects (default random or the subset of "a + b + c + d" within random).
random	character string specifying a, b, c, d random effects (default "a+b+c"). Alternatively nlme formula e.g. "list(id = pdDiag(a + b + c ~ 1))".
pdDiag	logical which if TRUE fits a diagonal random effects covariance matrix, or if FALSE (default) a general covariance matrix.
a.formula	formula for fixed effect a (default ~ 1).
b.formula	formula for fixed effect b (default ~ 1).
c.formula	formula for fixed effect c (default ~ 1).
d.formula	formula for fixed effect d (default ~ 1).
d.adjusted	logical defining x scale for random effect d (default FALSE means x unadjusted, TRUE means x adjusted with random effects b and c).
stype	version of natural spline curve to be fitted, default "nsk" or "ns". See Details.
bounds	span of x for regression spline, or fractional extension of range (default 0.04).
start	optional numeric vector of initial estimates for the fixed effects, or list of initial estimates for the fixed and random effects (see nlme).
xoffset	optional value of offset for x (either "mean" (default), "apv" or value).
bstart	optional starting value for fixed effect b (either "mean", "apv" or value (default xoffset)).
returndata	logical which if TRUE causes the model matrix to be returned, or if FALSE (default) the fitted model. Setting returndata TRUE is useful in conjunction with subset and subsample for simulation purposes.
verbose	optional logical value to print information on the evolution of the iterative algorithm (see nlme).
correlation	optional corStruct object describing the within-group correlation structure (see nlme).
weights	optional varFunc object or one-sided formula describing the within-group heteroscedasticity structure (see nlme).
subset	optional expression indicating the subset of the rows of data that should be used in the fit (see nlme).
method	character string, either "REML" or "ML" (default) (see nlme).
na.action	function for when the data contain NAs (see nlme).
control	list of control values for the estimation algorithm (see nlme) (default nlmeControl(returnObject = TRUE)).
keep.data	logical to control saving data as part of the model object (default TRUE).
object	object of class sitar.
...	further parameters for update consisting of any of the above sitar parameters.
evaluate	logical to control evaluation. If TRUE (default) the expanded update call is passed to sitar for evaluation, while if FALSE the expanded call itself is returned.

Details

The SITAR model usually has up to three random effects (a, b and c), termed size, timing and intensity respectively. df sets the degrees of freedom for the mean spline curve, taking values from 1 (i.e. linear) upwards. In addition there is a random effect for the slope, d, which is fitted when df = 0, and combined with a, it provides the classic random intercept random slope model, which is similar to the 1 df spline model. In addition d can be fitted, along with a, b and c, to extend SITAR to model variability in the adult slope of the growth curve.

xoffset allows the origin of x to be varied, while bstart specifies the starting value for b, both of which can affect the model fit and particularly b. The values of bstart, knots and bounds are offset by xoffset for fitting purposes, and similarly for fixed effect b.

The formulae a.formula, b.formula, c.formula and d.formula allow for cov.names and can include functions and interactions. make.names is used to ensure that the names of the corresponding model terms are valid. The modified names, not the original names, need to be specified in predict.sitar.

update updates the model by taking the object call, adding any new parameters and replacing changed ones. Where feasible the fixed and random effects of the model being updated are suitably modified and passed via the start argument.

The mean curve is a natural cubic spline, fitted originally with splines::ns but now by default with splines2::nsk, where the choice is set by stype. Both give the same mean curve, but nsk is faster than ns and its fixed effect coefficients have a direct interpretation: added to fixed effect a they give the values of the mean curve at the df right-most knots, while a is the value at the left-most knot. The knots themselves depend on fixed effects b and c (where fitted) and are accessed via attr(object, "knots").

Value

An object inheriting from class sitar representing the nonlinear mixed-effects model fit, with all the components returned by nlme (see nlmeObject for a full description) plus the following components:

fitnlme	the function returning the predicted value of y.
data	copy of data (if keep.data true).
constants	data frame of mean a-b-c-d values for unique combinations of covariates (excluding x).
call.sitar	the internal sitar call that produced the object.
xoffset	the value of xoffset.
ns	the lm object providing starting values for the B-spline curve.

In addition attributes stype and knots are set.

Generic functions such as print, plot, anova and summary have methods to show the results of the fit. The functions residuals, coef, fitted, fixed.effects, random.effects, predict, getData, getGroups, getCovariate and getVarCov can be used to extract some of its components.

Author(s)

Tim Cole [e-mail]

Examples

data(heights)
##  fit simple model
(m1 <- sitar(x=age, y=height, id=id, data=heights, df=5))

##  relate random effects to age at menarche (with censored values +ve)
##  both a (size) and b (timing) are positively associated with age at menarche
(m2 <- update(m1, a.formula = ~abs(men), b.formula = ~abs(men), c.formula = ~abs(men)))

statist7/sitar documentation built on April 13, 2025, 12:57 a.m.