Model description

Notation conventions

Bold lowercase for vectors
Bold subscript $\boldsymbol{s}$ since x, y
Bold uppercase for matrices
$\phi$ for all ‘dispersion’ parameters for consistency with code
Family titles link to TMB or sdmTMB source code
Attempt to link math symbols to argument options in model and code symbols

Basic model structure

\[ \begin{align} \mathbb{E}(y_{\boldsymbol{s},t}) &= \mu_{\boldsymbol{s},t},\\ \mu_{\boldsymbol{s},t} &= f^{-1} \left( \boldsymbol{X} \boldsymbol{\beta} + \omega_s + \epsilon_{\boldsymbol{s},t} \right),\\ \boldsymbol{\omega} &\sim \operatorname{MVNormal} \left( \boldsymbol{0}, \boldsymbol{\Sigma}_\omega \right),\\ \boldsymbol{\epsilon}_t &\sim \operatorname{MVNormal} \left( \boldsymbol{0}, \boldsymbol{\Sigma}_{\epsilon} \right). \end{align} \] where $f$ is a link function (e.g., log or logit) and $f^{-1}$ is its inverse link.

$\boldsymbol{X} \boldsymbol{\beta}$ is defined by the formula argument and represents the “fixed effect” model matrix and a corresponding vector of coefficients
$\omega_s$ are included if include_spatial = TRUE or if there is no spatiotemporal component (time = NULL)
$\epsilon_{\boldsymbol{s},t}$ are included if there are multiple time elements and spatial_only = FALSE (the default if there are multiple time elements)

Random or multi-level intercepts

\[ \begin{align} \mu_{\boldsymbol{s},t} &= f^{-1} \left( \ldots + \alpha_{g} + \ldots \right),\\ \alpha_g &\sim \operatorname{Normal} \left(0, \sigma_\alpha^2 \right),\\ \end{align} \]

where $\alpha_g$ is an example optional “random” intercept—an intercept centered on zero that varies by level $g$ and is constrained by $\sigma_\alpha$. This is defined by the formula argument via the (1 | g) syntax as in lme4 or glmmTMB.

Time-varying regression parameters

\[ \begin{align} \mu_{\boldsymbol{s},t} &= f^{-1} \left( \ldots + \gamma_{t} x_{\boldsymbol{s},t} + \ldots \right),\\ \gamma_{t=1} &\sim \operatorname{Uniform} \left(-\infty, \infty \right),\\ \gamma_{t>1} &\sim \operatorname{Normal} \left(\gamma_{t-1}, \sigma^2_{\gamma} \right), \end{align} \]

where $\gamma_t$ is an example optional time-varying regression parameter and $x_{,t} is the corresponding predictor value. This is defined via the time_varying argument. E.g., ~ 0 + x. The first value is given an implicit uniform prior. I.e., the same variable should not appear in the fixed effect formula since the initial value is estimated as part of the time-varying formula.

Spatial regression parameters

\[ \begin{align} \mu_{\boldsymbol{s},t} &= f^{-1} \left( \ldots + \zeta_s x_t + \ldots \right),\\ \boldsymbol{\zeta} &\sim \operatorname{MVNormal} \left( \boldsymbol{0}, \boldsymbol{\Sigma}_\zeta \right), \end{align} \]

where $\zeta_s$ is a regression parameter that varies spatially and $x_t$ is a predictor that is constant for a given time $t$. Currently, $x_t$ must be the time variable itself. If you are interested in using a different predictor, contact the developers.

AR1 spatiotemporal random fields

Dropping the optional $\omega_s$ for simplicity:

\[ \begin{align} \mu_{\boldsymbol{s},t} &= f^{-1} \left( \boldsymbol{X} \boldsymbol{\beta} + \delta_{\boldsymbol{s},t} \right),\\ \boldsymbol{\delta}_{t=1} &\sim \operatorname{MVNormal} (\boldsymbol{0}, \boldsymbol{\Sigma}_{\epsilon}),\\ \boldsymbol{\delta}_{t>1} &= \rho \boldsymbol{\delta}_{t-1} + \sqrt{1 - \rho^2} \boldsymbol{\epsilon}_t, \: \boldsymbol{\epsilon}_t \sim \operatorname{MVNormal} \left(\boldsymbol{0}, \boldsymbol{\Sigma}_{\epsilon} \right), \end{align} \]

where $\rho$ is the correlation between subsequent spatiotemporal random fields. The $\rho \boldsymbol{\delta}_{t-1} + \sqrt{1 - \rho^2}$ scales the spatiotemporal variance by the correlation such that it represents the steady-state marginal variance.

Random walk spatiotemporal random fields

Dropping the optional $\omega_s$ for simplicity:

\[ \begin{align} \mu_{\boldsymbol{s},t} &= f^{-1} \left( \boldsymbol{X} \boldsymbol{\beta} + \delta_{\boldsymbol{s},t} \right),\\ \boldsymbol{\delta}_{t=1} &\sim \operatorname{MVNormal} (\boldsymbol{0}, \boldsymbol{\Sigma}_{\epsilon}),\\ \boldsymbol{\delta}_{t>1} &= \boldsymbol{\delta}_{t-1} + \boldsymbol{\epsilon}_t, \: \boldsymbol{\epsilon}_t \sim \operatorname{MVNormal} \left(\boldsymbol{0}, \boldsymbol{\Sigma}_{\epsilon} \right), \end{align} \]

Offset terms

Offset terms can be included with the reserved word offset in the formula. E.g., y ~ x + offset.

These are included in the linear predictor as

\[ \begin{align} \mu_{\boldsymbol{s},t} &= f^{-1} \left( \ldots + O_{\boldsymbol{s},t} + \ldots \right), \end{align} \] where $O_{\boldsymbol{s},t}$ is an offset term—a log transformed variable without a coefficient (assuming a log link).

Threshold models

Linear breakpoint threshold models

TODO

These models can be fit by including + breakpt(x) in the model formula, where x is a covariate.

Logistic threshold models

The form is

\[ s(x)=\tau + \psi\ { \left[ 1+{ e }^{ -\ln\ \left(19\right) \cdot \left( x-s50 \right) / \left(s95 - s50 \right) } \right] }^{-1}, \] where $\psi$ is a scaling parameter (controlling the height of the y-axis for the response, and is unconstrained), $\tau$ is an intercept, $s50$ is a parameter controlling the point at which the function reaches 50% of the maximum ($\psi$), and $s95$ is a parameter controlling the point at which the function reaches 95%. The parameter $s50$ is unconstrained, and $s95$ is constrained to be larger than $s50$.

These models can be fit by including + logistic(x) in the model formula, where x is a covariate.

Observation model families

Binomial

Internally parameterized as the robust version.

Beta

\[ \operatorname{Beta} \left(\mu \phi, 1 - \mu \phi \right) \]

where $\phi$ is variance.

\[ \operatorname{Binomial} \left( N, \mu \right) \]

$N = 1$ (i.e., ‘size’ currently fixed) and $\mu$ is probability

Gamma

As shape, scale:

\[ \operatorname{Gamma} \left( \phi, \frac{\mu}{\phi} \right) \]

where $\phi$ represents the shape and $\frac{\mu}{\phi}$ represents the scale.

Variance scales quadratically with mean $\mathrm{Var}[y] = \mu + \mu^2 / \phi$.