Repository navigation
Expand file tree
/
Copy pathgp.Rd
More file actions
159 lines (142 loc) · 6.55 KB
/
Copy pathgp.Rd
File metadata and controls
159 lines (142 loc) · 6.55 KB
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/formula-gp.R
\name{gp}
\alias{gp}
\title{Set up Gaussian process terms in \pkg{brms}}
\usage{
gp(
...,
by = NA,
k = NA,
cov = "exp_quad",
iso = TRUE,
gr = TRUE,
cmc = TRUE,
scale = TRUE,
c = 5/4
)
}
\arguments{
\item{...}{One or more predictors for the GP.}
\item{by}{A numeric or factor variable of the same length as
each predictor. In the numeric vector case, the elements multiply
the values returned by the GP. In the factor variable
case, a separate GP is fitted for each factor level.}
\item{k}{Optional number of basis functions for computing Hilbert-space
approximate GPs. If \code{NA} (the default), exact GPs are computed.}
\item{cov}{Name of the covariance kernel. Currently supported are
\code{"exp_quad"} (exponentiated-quadratic kernel; default),
\code{"matern32"} (Matern 3/2 kernel), \code{"matern52"} (Matern 5/2 kernel),
and \code{"exponential"} (exponential kernel; alias: \code{"matern12"}).}
\item{iso}{A flag to indicate whether an isotropic (\code{TRUE}; the
default) or a non-isotropic GP should be used.
In the former case, the same amount of smoothing is applied to all
predictors. In the latter case, predictors may have different smoothing.
Ignored if only a single predictor is supplied.}
\item{gr}{Logical; Indicates if auto-grouping should be used (defaults
to \code{TRUE}). If enabled, observations sharing the same
predictor values will be represented by the same latent variable
in the GP. This will improve sampling efficiency
drastically if the number of unique predictor combinations is small
relative to the number of observations.}
\item{cmc}{Logical; Only relevant if \code{by} is a factor. If \code{TRUE}
(the default), cell-mean coding is used for the \code{by}-factor, that is
one GP per level is estimated. If \code{FALSE}, contrast GPs are estimated
according to the contrasts set for the \code{by}-factor.}
\item{scale}{Logical; If \code{TRUE} (the default), predictors are
scaled so that the maximum Euclidean distance between two points
is 1. This often improves sampling speed and convergence.
Scaling also affects the estimated length-scale parameters
in that they resemble those of scaled predictors (not of the original
predictors) if \code{scale} is \code{TRUE}.}
\item{c}{Numeric value only used in approximate GPs. Defines the
multiplicative constant of the predictors' range over which
predictions should be computed. A good default could be \code{c = 5/4}
but we are still working on providing better recommendations.}
}
\value{
An object of class \code{'gp_term'}, which is a list
of arguments to be interpreted by the formula
parsing functions of \pkg{brms}.
}
\description{
Set up a Gaussian process (GP) term in \pkg{brms}. The function does not
evaluate its arguments -- it exists purely to help set up a model with
GP terms.
}
\details{
A GP is a stochastic process, which
describes the relation between one or more predictors
\eqn{x = (x_1, ..., x_d)} and a response \eqn{f(x)}, where
\eqn{d} is the number of predictors. A GP is the
generalization of the multivariate normal distribution
to an infinite number of dimensions. Thus, it can be
interpreted as a prior over functions. The values of \eqn{f( )}
at any finite set of locations are jointly multivariate
normal, with a covariance matrix defined by the covariance
kernel \eqn{k_p(x_i, x_j)}, where \eqn{p} is the vector of parameters
of the GP:
\deqn{(f(x_1), \ldots f(x_n) \sim MVN(0, (k_p(x_i, x_j))_{i,j=1}^n) .}
The smoothness and general behavior of the function \eqn{f}
depends only on the choice of covariance kernel.
For a more detailed introduction to Gaussian processes,
see \url{https://en.wikipedia.org/wiki/Gaussian_process}.
For mathematical details on the supported kernels, please see the Stan manual:
\url{https://mc-stan.org/docs/functions-reference/matrix_operations.html}
under "Gaussian Process Covariance Functions".
There are several parameters estimated for GPs, the most important of which
are as follows:
\tabular{llll}{
\strong{Parameter} \tab \strong{Notation} \tab \strong{Support} \tab \strong{Meaning} \cr
\code{lscale} \tab \eqn{\ell} \tab \eqn{\mathbb{R}^+} \tab length-scale of the GP's covariance kernel \cr
\code{sdgp} \tab \eqn{\sigma} \tab \eqn{\mathbb{R}^+} \tab marginal standard deviation of the GP's covariance kernel \cr
\code{zgp} \tab \eqn{z} \tab \eqn{\mathbb{R}} \tab latent variable values of the training data \cr
}
Assuming an exponentiated quadratic covariance structure, the parameters
can be broadly interpreted as follows (see also
\url{https://mc-stan.org/docs/stan-users-guide/gaussian-processes.html#gaussian-process-regression}).
Note that in the above documentation the parameter \eqn{\sigma} is denoted
as \eqn{\alpha} instead, and the parameter \eqn{\ell} as \eqn{\rho}.
The length-scale \eqn{\ell} controls the frequency of the functions
represented by the GP prior i.e., values of \eqn{\ell \gg 0} lead to
lower-frequency functions, while values of \eqn{\ell \approx 0} lead to
higher-frequency functions. In slightly simpler terms, \eqn{\ell} sets
the distance over which observations in the input space are strongly
correlated. The marginal standard deviation \eqn{\sigma} controls the
magnitude of the range of the function represented by the GP i.e., it
represents how much the values of the function tend to deviate from the
mean level. Lastly, the parameter \eqn{z} represents latent variable values
per observation (or unique input point).
}
\examples{
\dontrun{
# simulate data using the mgcv package
dat <- mgcv::gamSim(1, n = 30, scale = 2)
# fit a simple GP model
fit1 <- brm(y ~ gp(x2), dat, chains = 2)
summary(fit1)
me1 <- conditional_effects(fit1, ndraws = 200, spaghetti = TRUE)
plot(me1, ask = FALSE, points = TRUE)
# fit a more complicated GP model and use an approximate GP for x2
fit2 <- brm(y ~ gp(x0) + x1 + gp(x2, k = 10) + x3, dat, chains = 2)
summary(fit2)
me2 <- conditional_effects(fit2, ndraws = 200, spaghetti = TRUE)
plot(me2, ask = FALSE, points = TRUE)
# fit a multivariate GP model with Matern 3/2 kernel
fit3 <- brm(y ~ gp(x1, x2, cov = "matern32"), dat, chains = 2)
summary(fit3)
me3 <- conditional_effects(fit3, ndraws = 200, spaghetti = TRUE)
plot(me3, ask = FALSE, points = TRUE)
# compare model fit
loo(fit1, fit2, fit3)
# simulate data with a factor covariate
dat2 <- mgcv::gamSim(4, n = 90, scale = 2)
# fit separate gaussian processes for different levels of 'fac'
fit4 <- brm(y ~ gp(x2, by = fac), dat2, chains = 2)
summary(fit4)
plot(conditional_effects(fit4), points = TRUE)
}
}
\seealso{
\code{\link{brmsformula}}
}