Skip to contents

Lognormal, Gamma and generalized gamma families fit positive observations. Poisson-link delta (PLD) families also use sampled zeros.

Usage

lognormal(link = "log")

pld_lognormal(y50 = NULL, link = "log")

pld_gamma(y50 = NULL, link = "log")

gengamma(link = "log", Q = NULL)

pld_gengamma(y50 = NULL, Q = NULL, link = "log")

Arguments

Link for the assessment prediction. Only "log" is supported. For PLD families, the link applies to the overall assessment prediction, the arithmetic mean across zeros and positives. The prediction on the link scale is \(\log\widetilde{Y}_i\). The complementary log-log link applies to the encounter probability described in Details.

y50

Optional positive soft detection scale in the observation's units (the predicted level at which half of observations are expected to be zero). By default, the model estimates a separate scale for each selected fleet or survey.

Q

Optional fixed Prentice shape parameter for generalized gamma. The default estimates a separate signed shape for each selected series.

Value

A family specification for fit_tam() or prepare_tam().

Details

Supply a family in catch_settings$family or index_settings$family. A single family applies to the whole observation type. A named list selects families by fleet or survey, with the default lognormal for unlisted series. Unlabelled catches use the name "Fishery".

Use stats::Gamma() with link = "log" for Gamma observations. For that family and gengamma(), the prediction is the arithmetic mean. Positive-only families exclude sampled zeros.

Let \(Y_i\) be a recorded catch or survey index for an age and year, and let \(\widetilde{Y}_i\) be its prediction from the population model. The catch prediction comes from the Baranov catch equation. The survey prediction is abundance at sampling time scaled by catchability. Poisson-link delta (PLD) uses this prediction to explain both the chance of recording a positive value and the size of positive observations (Thorson 2018, see also the sdmTMB Poisson-link delta guide).

tinyAM adapts Thorson's parameterization by using the assessment prediction as the overall mean. Each fleet or survey \(j\) has a soft detection scale \(\widetilde{Y}_{50,j}\) (the predicted catch or index at which half of observations are expected to be zero). The prediction and the scale use the observation's units.

Encounter. Conditional on the population states and parameters, recording a positive value is a binomial outcome with one trial and probability \(p_{+,i}\). The probability of recording zero is the chance of zero events under a Poisson distribution with mean \(\lambda_i\). $$\lambda_i = \log(2)\frac{\widetilde{Y}_i}{\widetilde{Y}_{50,j}}, \qquad p_{0,i} = \Pr(Y_i = 0) = e^{-\lambda_i}, \qquad p_{+,i} = \Pr(Y_i > 0) = 1-p_{0,i}.$$ Doubling the prediction from the soft detection scale to twice that level lowers the chance of recording zero from 50% to 25%. The encounter component uses a complementary log-log link for the probability of a positive. $$\operatorname{cloglog}(p_{+,i}) = \log\!\big[-\log(1-p_{+,i})\big] = \log\lambda_i.$$

Positive observations. The positive component uses a log link for its arithmetic mean \(m_{+,i}\), with \(\log m_{+,i} = \log\widetilde{Y}_i - \log p_{+,i}\). Dividing by the probability of a positive keeps the average across zeros and positives equal to the assessment prediction. $$m_{+,i} = \frac{\widetilde{Y}_i}{p_{+,i}}, \qquad p_{+,i}\,m_{+,i} = \widetilde{Y}_i.$$

The positive distribution can be lognormal, Gamma, or generalized gamma. For example, with a lognormal positive component, $$\log Y_i \mid Y_i > 0 \sim N\!\left(\log m_{+,i}-\frac{\sigma_i^2}{2},\ \sigma_i^2\right).$$ Here \(\sigma_i\) controls the spread on the log scale. Subtracting \(\sigma_i^2/2\) gives the positive observations an arithmetic mean of \(m_{+,i}\). The default, positive-only lognormal() family uses the assessment prediction as its conditional median.

Likelihood. A recorded zero contributes the log probability of recording zero. A positive contributes the log probability of recording a positive plus the log density of its size. Let \(g_{+,i}\) be the chosen positive density on the log-observation scale. $$\ell_i = \begin{cases} \log p_{0,i}, & Y_i = 0, \\[4pt] \log p_{+,i} + \log g_{+,i}(\log Y_i), & Y_i > 0. \end{cases}$$

The q_link setting determines how the catchability formula maps to catchability in the survey prediction.

Dispersion, shape and observation support

For lognormal families, the observation SD settings specify the log-SD of positives. For Gamma families, they specify the coefficient of variation of positives. Gamma shape is the inverse squared coefficient of variation. For generalized gamma, these settings specify the Prentice scale \(\sigma\). Use one constant scale per generalized gamma series. If a fixed \(Q\) is negative, supply its scale, with no fitted multiplier, satisfying \(1+\sigma Q>0\). Estimated shapes satisfy this finite-mean condition by construction.

Generalized gamma becomes Gamma at \(Q=\sigma\) and mean-parameterized lognormal at \(Q=0\). The latter is the same distribution family as lognormal(), with the population prediction representing the mean rather than the median. pld_gengamma(Q = 0) gives pld_lognormal(). Gamma, generalized gamma and PLD observations are conditionally independent. Use separate SD coefficients for series whose dispersion scales differ. Within-year age correlation (cor_struct = "ar1") can be used for ordinary lognormal series, including lognormal series in a mixed-family fit. Standardized and quantile residuals use marginal observation distributions and retain that correlation. Use a Gaussian one-step-ahead algorithm for correlated observations in an all-lognormal fit. See residuals.tam_fit().

Use zero for a sampled nondetection and NA for a missing observation. Estimating the soft detection scale requires both sampled zeros and positives. A fixed scale can be used with all-positive data. Each fitted series needs at least one positive observation. Catch at structurally unfished ages is deterministic.

For a native-age series, prepare_tam() sums the observations from the modeled plus age through the oldest biological age, separately by year and series. Each age needs one sampled value, including any sampled zeros. An absent age or NA makes that terminal observation missing. The chosen positive-component family applies to the pooled value.

A series with no recorded values above the modeled plus age in the supplied data is treated as already pooled at that age. Older catch rows may be present with missing observations to complete the input grid. The input resolution is determined across all supplied years and is used in each retrospective fold. Biological inputs can extend to older ages.

Observed-catch hindcasts use the original counts and weights by biological age to compute held-out yield. If only pooled counts are available with older biological ages, use proj_settings = list(F_mult = 1) in fit_hindcast().

PLD assumes independent observation errors conditional on the fitted states and a stable soft detection scale across years and ages within each series. Sampling effort, the number of fish aged and common sampling units can alter detection or induce dependence. Check how fitted zero probabilities and positive magnitudes agree with the observations. At very low predictions the positive mean approaches \(\widetilde Y_{50}/\log(2)\).

References

Thorson, J. T. (2018). Three problems with the conventional delta-model for biomass sampling data, and a computationally efficient alternative. Canadian Journal of Fisheries and Aquatic Sciences. doi:10.1139/cjfas-2017-0266

Prentice, R. L. (1974). A log gamma model and its maximum likelihood estimation. Biometrika. doi:10.1093/biomet/61.3.539

Dunic, J. C., Conner, J., Anderson, S. C. and Thorson, J. T. (2025). The generalized gamma is a flexible distribution that outperforms alternatives when modelling catch rate data. ICES Journal of Marine Science. doi:10.1093/icesjms/fsaf040

Albertsen, C. M., Nielsen, A. and Thygesen, U. H. (2017). Choosing the observational likelihood in state-space stock assessment models. Canadian Journal of Fisheries and Aquatic Sciences. doi:10.1139/cjfas-2015-0532

Monnahan et al. (2025). Testing the validity of lognormal likelihoods for abundance indices in stock assessment models using the generalized gamma distribution. ICES Journal of Marine Science. doi:10.1093/icesjms/fsaf071

Examples

lognormal()
#> $name
#> [1] "lognormal"
#> 
#> $link
#> [1] "log"
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
stats::Gamma(link = "log")
#> 
#> Family: Gamma 
#> Link function: log 
#> 
gengamma()
#> $name
#> [1] "gengamma"
#> 
#> $link
#> [1] "log"
#> 
#> $Q
#> NULL
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
pld_lognormal()
#> $name
#> [1] "pld_lognormal"
#> 
#> $y50
#> NULL
#> 
#> $link
#> [1] "log"
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
pld_gamma(y50 = 100)
#> $name
#> [1] "pld_gamma"
#> 
#> $y50
#> [1] 100
#> 
#> $link
#> [1] "log"
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
pld_gengamma(Q = 0)
#> $name
#> [1] "pld_gengamma"
#> 
#> $y50
#> NULL
#> 
#> $Q
#> [1] 0
#> 
#> $link
#> [1] "log"
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
list(RV = pld_lognormal(y50 = 100), Sentinel = lognormal())
#> $RV
#> $name
#> [1] "pld_lognormal"
#> 
#> $y50
#> [1] 100
#> 
#> $link
#> [1] "log"
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
#> 
#> $Sentinel
#> $name
#> [1] "lognormal"
#> 
#> $link
#> [1] "log"
#> 
#> attr(,"class")
#> [1] "tam_observation_family"
#>