share_control selects how each parameter of a joint
(hierarchical) state-space model is treated across individual tracks, and
guards against parameter-sharing combinations that are not identifiable.
Each parameter may be:
"pooled"a single value estimated from all individuals at once.
"hierarchical"an individual-level value drawn from an estimated population distribution, so individual estimates are partially pooled toward the population mean.
"individual"a separate, independent value per individual, as in fit_ssm.
share_control(
sigma = c("hierarchical", "pooled", "individual"),
sigma_g = c("pooled", "individual"),
aniso = c("individual", "common.ratio", "isotropic"),
rho_p = c("individual", "pooled"),
tau = c("pooled", "individual", "hierarchical"),
psi = c("pooled", "individual", "hierarchical"),
rho_o = c("pooled", "individual"),
hier.sigma = c("shared", "xy"),
ho_scale = c("fixed", "pooled"),
group = NULL,
strict = TRUE
)treatment of the process magnitude - the innovation scale
sigma in jmp, and the diffusion magnitude D in jcrw. One of
"hierarchical" (default), "pooled" or "individual". In jcrw this is
half the log determinant of the velocity innovation covariance, which does
not depend on the animal's direction of travel, so an among-individual
variance estimated from it is a statement about how much the animals move
rather than about where they went
treatment of the move persistence random walk scale. One of
"pooled" (default) or "individual". Pooling is what makes g_t
comparable among individuals. jmp only
treatment of the anisotropy of the process covariance. jcrw
only. One of:
"individual"(default) amount and orientation both free per
individual. This imposes no cross-individual structure, and on the sese
elephant seals it is strongly preferred: the individual ratios span 1.12
to 2.70, and a likelihood ratio test against a common ratio gives
17.2 on 3 degrees of freedom, p = 0.0007.
"common.ratio"the amount of anisotropy is shared by all
individuals while each keeps its own orientation. This is the pooling the
jcrw parameterisation makes possible - the shared quantity does not
depend on which way an animal travelled, the free one does - and it is a
testable restriction rather than an assumption, since the null is
interior and an ordinary likelihood ratio test applies. Worth trying, but
not worth assuming.
"isotropic"no anisotropy at all. The process is described by its magnitude alone, and there is no orientation to estimate.
A caution about "common.ratio": it imposes the shared ratio on every
individual and then finds the best orientation given it. An animal with
little real anisotropy will still be handed a confident-looking
orientation, because the reported standard error is conditional on the
imposed ratio rather than reflecting whether there is any anisotropy to
orient.
Note that pooling the anisotropy vector outright is not offered,
because that would force a common orientation as well as a common ratio,
which is the mistake the parameterisation is designed to avoid
treatment of the process error correlation between x and y.
One of "individual" (default) or "pooled". jmp only - jcrw has no
rho_p, since the correlation is absorbed into the anisotropy vector along
with the two variances
treatment of the LS/GPS measurement error dispersion. One of
"pooled" (default), "individual" or "hierarchical"
treatment of the Argos error ellipse semi-minor axis scaling.
One of "pooled" (default), "individual" or "hierarchical"
treatment of the measurement error correlation between x and
y. One of "pooled" (default) or "individual"
structure of the individual random effect on sigma when
sigma = "hierarchical". "shared" (default) gives one scalar deviation
per individual applied to both coordinates; "xy" gives independent
deviations per coordinate. "shared" is the default because it is the
rotation-invariant choice
treatment of the haulout process variance scale factor.
"fixed" (default) uses the constant from ssm_control;
"pooled" estimates it. Estimating it is only possible in a joint fit: it
is not identifiable from one track
name of a variable in the input data defining strata within which the measurement parameters are pooled, or NULL (default)
logical; if TRUE (default), reject parameter combinations that are not identifiable. If FALSE, warn instead
a named list of parameter sharing settings
The defaults implement the recommended structure for the joint
move persistence model: a pooled measurement model, a pooled sigma_g, a
hierarchical process innovation scale, and an individual rho_p.
Measurement model. tau, psi and rho_o describe the
observation system rather than the animal. Argos error is a property of
satellite geometry, transmitter power, antenna and surfacing behaviour, and
is shared by animals carrying comparable tags, so estimating these
separately per individual estimates one quantity many times using a
fraction of the data each time. psi is the clearest case: it scales only
the semi-minor axis of the Argos error ellipse, so it is informed solely by
the anisotropy of the observation residuals and is weakly identified from a
single track. Note that tau scales fixed per-lc variances taken from
independent data (see emf) rather than estimating the error
from scratch, so a pooled tau far from 1 is a statement about how well
those independent values are calibrated for the deployment at hand.
sigma_g is pooled, and this is the point of the model. With an
individual-specific sigma_g, each animal's g_t series is smoothed on
its own scale and the series cannot be compared between animals.
Comparability is usually the entire reason for fitting a move persistence
model to a deployment. This follows Jonsen et al. (2019) and the existing
jmpm model in fit_mpm. sigma_g is also rotation-invariant:
it scales a random walk on a scalar, so it does not depend on which way the
animal travelled.
rho_p is individual by default, and this is deliberate. rho_p
is the correlation between the x and y process innovations, which sets the
tilt of the process covariance ellipse relative to the projected
coordinate axes. It therefore records the animal's direction of travel
rather than a property of its movement. Animals heading in different
directions are not exchangeable in rho_p, and pooling it averages
correlations that may differ in sign, producing an estimate near zero that
reflects nothing but the mixture. Pool it only when all individuals travel
broadly the same way.
The residual frame-dependence. hier.sigma = "shared" gives each
individual one scalar deviation applied to both coordinates, so an
individual's process covariance is a scalar multiple of the population one.
A scalar multiple is rotation-invariant, so the estimated among-individual
variance is a statement about movement magnitude rather than heading. What
it does hold common is the sigma_x : sigma_y ratio, which is
frame-dependent. That is a known approximation, and a fully
rotation-invariant parameterisation - overall magnitude, anisotropy ratio,
and orientation, with orientation always individual - is the intended
replacement.
Identifiability. The central tension in a state-space model is the
partitioning of total variance between the process and the measurement
model. Random effects on both sides let the individual-level deviations
trade off against each other at almost no cost in likelihood, leaving the
variance hyperparameters weakly identified and, with short tracks,
effectively unidentified. share_control therefore refuses to make sigma
hierarchical at the same time as tau or psi. Set strict = FALSE to
downgrade this to a warning.
Grouping. Pooling the measurement parameters assumes a homogeneous
observation process. Mixed tag models, different duty cycles, or different
species all violate that. Use group to name a variable in the input data
defining strata within which the measurement parameters are pooled.
Jonsen ID, McMahon CR, Patterson TA, et al. (2019) Movement responses to environment: fast inference of variation among southern elephant seals with a mixed effects model. Ecology 100(1):e02566
## the recommended defaults
share_control()
#> $sigma
#> [1] "hierarchical"
#>
#> $sigma_g
#> [1] "pooled"
#>
#> $aniso
#> [1] "individual"
#>
#> $rho_p
#> [1] "individual"
#>
#> $tau
#> [1] "pooled"
#>
#> $psi
#> [1] "pooled"
#>
#> $rho_o
#> [1] "pooled"
#>
#> $hier.sigma
#> [1] "shared"
#>
#> $ho_scale
#> [1] "fixed"
#>
#> $group
#> NULL
#>
#> $strict
#> [1] TRUE
#>
## pool the measurement model within tag type
share_control(group = "tag_type")
#> $sigma
#> [1] "hierarchical"
#>
#> $sigma_g
#> [1] "pooled"
#>
#> $aniso
#> [1] "individual"
#>
#> $rho_p
#> [1] "individual"
#>
#> $tau
#> [1] "pooled"
#>
#> $psi
#> [1] "pooled"
#>
#> $rho_o
#> [1] "pooled"
#>
#> $hier.sigma
#> [1] "shared"
#>
#> $ho_scale
#> [1] "fixed"
#>
#> $group
#> [1] "tag_type"
#>
#> $strict
#> [1] TRUE
#>
## fully pooled process scale, for too few individuals to estimate
## among-individual variance
share_control(sigma = "pooled")
#> $sigma
#> [1] "pooled"
#>
#> $sigma_g
#> [1] "pooled"
#>
#> $aniso
#> [1] "individual"
#>
#> $rho_p
#> [1] "individual"
#>
#> $tau
#> [1] "pooled"
#>
#> $psi
#> [1] "pooled"
#>
#> $rho_o
#> [1] "pooled"
#>
#> $hier.sigma
#> [1] "shared"
#>
#> $ho_scale
#> [1] "fixed"
#>
#> $group
#> NULL
#>
#> $strict
#> [1] TRUE
#>