-
Notifications
You must be signed in to change notification settings - Fork 1
/
ff.Rd
111 lines (103 loc) · 5.11 KB
/
ff.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pffr-ff.R
\name{ff}
\alias{ff}
\title{Construct a function-on-function regression term}
\usage{
ff(
X,
yind = NULL,
xind = seq(0, 1, l = ncol(X)),
basistype = c("te", "t2", "ti", "s", "tes"),
integration = c("simpson", "trapezoidal", "riemann"),
L = NULL,
limits = NULL,
splinepars = if (basistype != "s") {
list(bs = "ps", m = list(c(2, 1), c(2, 1)), k
= c(5, 5))
} else {
list(bs = "tp", m = NA)
},
check.ident = TRUE
)
}
\arguments{
\item{X}{an n by \code{ncol(xind)} matrix of function evaluations
\eqn{X_i(s_{i1}),\dots, X_i(s_{iS})}; \eqn{i=1,\dots,n}.}
\item{yind}{\emph{DEPRECATED} used to supply matrix (or vector) of indices of
evaluations of \eqn{Y_i(t)}, no longer used.}
\item{xind}{vector of indices of evaluations of \eqn{X_i(s)},
i.e, \eqn{(s_{1},\dots,s_{S})}}
\item{basistype}{defaults to "\code{\link[mgcv]{te}}", i.e. a tensor product
spline to represent \eqn{\beta(t,s)}. Alternatively, use \code{"s"} for
bivariate basis functions (see \code{mgcv}'s \code{\link[mgcv]{s}}) or
\code{"t2"} for an alternative parameterization of tensor product splines
(see \code{mgcv}'s \code{\link[mgcv]{t2}}).}
\item{integration}{method used for numerical integration. Defaults to
\code{"simpson"}'s rule for calculating entries in \code{L}. Alternatively
and for non-equidistant grids, \code{"trapezoidal"} or \code{"riemann"}.
\code{"riemann"} integration is always used if \code{limits} is specified}
\item{L}{optional: an n by \code{ncol(xind)} matrix giving the weights for
the numerical integration over \eqn{s}.}
\item{limits}{defaults to NULL for integration across the entire range of
\eqn{X(s)}, otherwise specifies the integration limits \eqn{s_{hi}(t),
s_{lo}(t)}: either one of \code{"s<t"} or \code{"s<=t"} for
\eqn{(s_{hi}(t), s_{lo}(t)) = (t, 0]} or \eqn{[t, 0]}, respectively, or a
function that takes \code{s} as the first and \code{t} as the second
argument and returns TRUE for combinations of values \code{(s,t)} if
\code{s} falls into the integration range for the given \code{t}. This is
an experimental feature and not well tested yet; use at your own risk.}
\item{splinepars}{optional arguments supplied to the \code{basistype}-term.
Defaults to a cubic tensor product B-spline with marginal first difference
penalties, i.e. \code{list(bs="ps", m=list(c(2, 1), c(2,1)))}. See
\code{\link[mgcv]{te}} or \code{\link[mgcv]{s}} in \pkg{mgcv} for details}
\item{check.ident}{check identifiability of the model spec. See Details and
References. Defaults to \code{TRUE}.}
}
\value{
A list containing \item{call}{a "call" to
\code{\link[mgcv]{te}} (or \code{\link[mgcv]{s}} or \code{\link[mgcv]{t2}})
using the appropriately constructed covariate and weight matrices}
\item{data}{a list containing the necessary covariate and weight matrices}
}
\description{
Defines a term \eqn{\int^{s_{hi, i}}_{s_{lo, i}} X_i(s)\beta(t,s)ds} for
inclusion in an \code{mgcv::gam}-formula (or \code{bam} or \code{gamm} or
\code{gamm4:::gamm4}) as constructed by \code{\link{pffr}}. \cr Defaults to a
cubic tensor product B-spline with marginal first order differences penalties
for \eqn{\beta(t,s)} and numerical integration over the entire range
\eqn{[s_{lo, i}, s_{hi, i}] = [\min(s_i), \max(s_i)]} by using Simpson
weights. Can't deal with any missing \eqn{X(s)}, unequal lengths of
\eqn{X_i(s)} not (yet?) possible. Unequal integration ranges for different
\eqn{X_i(s)} should work. \eqn{X_i(s)} is assumed to be numeric (duh...).
}
\details{
If \code{check.ident==TRUE} and \code{basistype!="s"} (the default), the
routine checks conditions for non-identifiability of the effect. This occurs
if a) the marginal basis for the functional covariate is rank-deficient
(typically because the functional covariate has lower rank than the spline
basis along its index) and simultaneously b) the kernel of Cov\eqn{(X(s))} is
not disjunct from the kernel of the marginal penalty over \code{s}. In
practice, a) occurs quite frequently, and b) occurs usually because
curve-wise mean centering has removed all constant components from the
functional covariate. \cr If there is kernel overlap, \eqn{\beta(t,s)} is
constrained to be orthogonal to functions in that overlap space (e.g., if the
overlap contains constant functions, constraints "\eqn{\int \beta(t,s) ds =
0} for all t" are enforced). See reference for details.\cr A warning is
always given if the effective rank of Cov\eqn{(X(s))} (defined as the number
of eigenvalues accounting for at least 0.995 of the total variance in
\eqn{X_i(s)}) is lower than 4. If \eqn{X_i(s)} is of very low rank,
\code{\link{ffpc}}-term may be preferable.
}
\references{
For background on \code{check.ident}:\cr Scheipl, F., Greven,
S. (2016). Identifiability in penalized function-on-function regression
models. Electronic Journal of Statistics, 10(1), 495--526.
\url{https://projecteuclid.org/journals/electronic-journal-of-statistics/volume-10/issue-1/Identifiability-in-penalized-function-on-function-regression-models/10.1214/16-EJS1123.full}
}
\seealso{
\code{mgcv}'s \code{\link[mgcv]{linear.functional.terms}}
}
\author{
Fabian Scheipl, Sonja Greven
}