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} &= g^{-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 \(g\) is a link function and \(g^{-1}\) is the inverse link.

  • \(\boldsymbol{X} \boldsymbol{\beta}\) is defined by the formula argument

  • \(\omega_s\) are included if include_spatial = TRUE

  • \(\epsilon_{\boldsymbol{s},t}\) are included if there are multiple time elements and spatial_only = FALSE (the default if there are multiple time elements)

Time-varying regression parameters

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

Spatial regression parameters

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

AR1 spatiotemporal random fields

Dropping the optional \(\omega_s\) for simplicity:

\[ \begin{align} \mu_{\boldsymbol{s},t} &= g^{-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} &= \phi \boldsymbol{\delta}_{t-1} + \sqrt{1 - \phi^2} \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} &= g^{-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. Offsets only make sense if the link is log.

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.

Gaussian

\[ \operatorname{Normal} \left( \mu, \phi \right) \] where \(\phi\) is the standard deviation (following Stan convention of SD not variance).

Lognormal

\[ \operatorname{Lognormal} \left( \log \mu - \frac{\phi^2}{2}, \phi \right) \]

Negative Binomial

Internally parameterized as the robust version

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

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

Poisson

\[ \operatorname{Poisson} \left( \mu \right) \]

Student-t

\[ \operatorname{Student-t} \left( \mu, \phi, \nu \right) \]

where \(\nu\), the degrees of freedom, is currently fixed at 3.

Tweedie

Source code as in cplm package. https://link.springer.com/article/10.1007/s11222-012-9343-7

\[ \operatorname{Tweedie} \left(\mu, p, \phi \right), \: 1 < p < 2 \]