The routine can estimate
linear
functional effects of scalar (numeric or factor) covariates that vary
smoothly over \(t\) (e.g. \(z_{1i} \beta_1(t)\), specified as
~z1),
nonlinear, and possibly multivariate functional effects
of (one or multiple) scalar covariates \(z\) that vary smoothly over the
index \(t\) of \(Y(t)\) (e.g. \(f(z_{2i}, t)\), specified in the
formula simply as ~s(z2))
(nonlinear) effects of scalar
covariates that are constant over \(t\) (e.g. \(f(z_{3i})\), specified
as ~c(s(z3)), or \(\beta_3 z_{3i}\), specified as ~c(z3)),
function-on-function regression terms (e.g. \(\int
X_i(s)\beta(s,t)ds\), specified as ~ff(X, yindex=t, xindex=s), see
ff). Terms given by sff and ffpc
provide nonlinear and FPC-based effects of functional covariates,
respectively.
concurrent effects of functional covariates X
measured on the same grid as the response are specified as follows:
~s(x) for a smooth, index-varying effect \(f(X(t),t)\), ~x
for a linear index-varying effect \(X(t)\beta(t)\), ~c(s(x)) for a
constant nonlinear effect \(f(X(t))\), ~c(x) for a constant linear
effect \(X(t)\beta\).
Smooth functional random intercepts
\(b_{0g(i)}(t)\) for a grouping variable g with levels \(g(i)\)
can be specified via ~s(g, bs="re")), functional random slopes
\(u_i b_{1g(i)}(t)\) in a numeric variable u via ~s(g, u,
bs="re")). Scheipl, Staicu, Greven (2013) contains code examples for
modeling correlated functional random intercepts using
mrf-terms.
Use the c()-notation to denote
model terms that are constant over the index of the functional response.
Internally, univariate smooth terms without a c()-wrapper are
expanded into bivariate smooth terms in the original covariate and the
index of the functional response. Bivariate smooth terms (s(), te()
or t2()) without a c()-wrapper are expanded into trivariate
smooth terms in the original covariates and the index of the functional
response. Linear terms for scalar covariates or categorical covariates are
expanded into varying coefficient terms, varying smoothly over the index of
the functional response. For factor variables, a separate smooth function
with its own smoothing parameter is estimated for each level of the
factor.
The marginal spline basis used for the index of the the
functional response is specified via the global argument
bs.yindex. If necessary, this can be overriden for any specific term
by supplying a bs.yindex-argument to that term in the formula, e.g.
~s(x, bs.yindex=list(bs="tp", k=7)) would yield a tensor product
spline over x and the index of the response in which the marginal
basis for the index of the response are 7 cubic thin-plate spline functions
(overriding the global default for the basis and penalty on the index of
the response given by the global bs.yindex-argument).
Use
~-1 + c(1) + ... to specify a model with only a constant and no
functional intercept.
The functional covariates have to be supplied as a \(n\) by <no. of
evaluations> matrices, i.e. each row is one functional observation. For
data on a regular grid, the functional response is supplied in the same
format, i.e. as a matrix-valued entry in data, which can contain
missing values.
If the functional responses are sparse or irregular (i.e., not
evaluated on the same evaluation points across all observations), the
ydata-argument can be used to specify the responses: ydata
must be a data.frame with 3 columns called '.obs', '.index',
'.value' which specify which curve the point belongs to
('.obs'=\(i\)), at which \(t\) it was observed
('.index'=\(t\)), and the observed value
('.value'=\(Y_i(t)\)). Note that the vector of unique sorted
entries in ydata$.obs must be equal to rownames(data) to
ensure the correct association of entries in ydata to the
corresponding rows of data. For both regular and irregular
functional responses, the model is then fitted with the data in long
format, i.e., for data on a grid the rows of the matrix of the functional
response evaluations \(Y_i(t)\) are stacked into one long vector and the
covariates are expanded/repeated correspondingly. This means the models get
quite big fairly fast, since the effective number of rows in the design
matrix is number of observations times number of evaluations of \(Y(t)\)
per observation.
Note that pffr does not use mgcv's default identifiability
constraints (i.e., \(\sum_{i,t} \hat f(z_i, x_i, t) = 0\) or
\(\sum_{i,t} \hat f(x_i, t) = 0\)) for tensor product terms whose
marginals include the index \(t\) of the functional response. Instead,
\(\sum_i \hat f(z_i, x_i, t) = 0\) for all \(t\) is enforced, so that
effects varying over \(t\) can be interpreted as local deviations from
the global functional intercept. This is achieved by using
ti-terms with a suitably modified mc-argument.
Note that this is not possible if algorithm='gamm4' since only
t2-type terms can then be used and these modified constraints are
not available for t2. We recommend using centered scalar covariates
for terms like \(z \beta(t)\) (~z) and centered functional
covariates with \(\sum_i X_i(t) = 0\) for all \(t\) in ff-terms
so that the global functional intercept can be interpreted as the global
mean function.
The family-argument can be used to specify all of the response
distributions and link functions described in
family.mgcv. Note that family = "gaulss" is
treated in a special way: Users can supply the formula for the variance by
supplying a special argument varformula, but this is not modified in
the way that the formula-argument is but handed over to the fitter
directly, so this is for expert use only. If varformula is not
given, pffr will use the parameters from argument bs.int to
define a spline basis along the index of the response, i.e., a smooth
variance function over $t$ for responses $Y(t)$.