Skip to contents

Family functions in singleRcapture package

Source: R/Chao.R, R/Hurdleztgeom.R, R/Hurdleztnegbin.R, and 18 more
singleRmodels.Rd

Package singleRcapture utilizes various family type functions that specify variable parts of population size estimation, regression, diagnostics and other necessary information that depends on the model. These functions are used as model argument in estimatePopsize function.

Usage

chao(lambdaLink = "loghalf", ...)

Hurdleztgeom(
  lambdaLink = c("log", "neglog"),
  piLink = c("logit", "cloglog", "probit"),
  ...
)

Hurdleztnegbin(
  nSim = 1000,
  epsSim = 1e-08,
  eimStep = 6,
  lambdaLink = c("log", "neglog"),
  alphaLink = c("log", "neglog"),
  piLink = c("logit", "cloglog", "probit"),
  ...
)

Hurdleztpoisson(
  lambdaLink = c("log", "neglog"),
  piLink = c("logit", "cloglog", "probit"),
  ...
)

oiztgeom(
  lambdaLink = c("log", "neglog"),
  omegaLink = c("logit", "cloglog", "probit"),
  ...
)

oiztnegbin(
  nSim = 1000,
  epsSim = 1e-08,
  eimStep = 6,
  lambdaLink = c("log", "neglog"),
  alphaLink = c("log", "neglog"),
  omegaLink = c("logit", "cloglog", "probit"),
  ...
)

oiztpoisson(
  lambdaLink = c("log", "neglog"),
  omegaLink = c("logit", "cloglog", "probit"),
  ...
)

zelterman(lambdaLink = "loghalf", ...)

zotgeom(lambdaLink = c("log", "neglog"), ...)

zotnegbin(
  nSim = 1000,
  epsSim = 1e-08,
  eimStep = 6,
  lambdaLink = c("log", "neglog"),
  alphaLink = c("log", "neglog"),
  ...
)

zotpoisson(lambdaLink = c("log", "neglog"), ...)

ztHurdlegeom(
  lambdaLink = c("log", "neglog"),
  piLink = c("logit", "cloglog", "probit"),
  ...
)

ztHurdlenegbin(
  nSim = 1000,
  epsSim = 1e-08,
  eimStep = 6,
  lambdaLink = c("log", "neglog"),
  alphaLink = c("log", "neglog"),
  piLink = c("logit", "cloglog", "probit"),
  ...
)

ztHurdlepoisson(
  lambdaLink = c("log", "neglog"),
  piLink = c("logit", "cloglog", "probit"),
  ...
)

ztgeom(lambdaLink = c("log", "neglog"), ...)

ztnegbin(
  nSim = 1000,
  epsSim = 1e-08,
  eimStep = 6,
  lambdaLink = c("log", "neglog"),
  alphaLink = c("log", "neglog"),
  ...
)

ztoigeom(
  lambdaLink = c("log", "neglog"),
  omegaLink = c("logit", "cloglog", "probit"),
  ...
)

ztoinegbin(
  nSim = 1000,
  epsSim = 1e-08,
  eimStep = 6,
  lambdaLink = c("log", "neglog"),
  alphaLink = c("log", "neglog"),
  omegaLink = c("logit", "cloglog", "probit"),
  ...
)

ztoipoisson(
  lambdaLink = c("log", "neglog"),
  omegaLink = c("logit", "cloglog", "probit"),
  ...
)

ztpoisson(lambdaLink = c("log", "neglog"), ...)

Arguments

a link for Poisson parameter, "log" by default except for zelterman's and chao's models where only (x2) is possible.

...

Additional arguments, not used for now.

a link for probability parameter, "logit" by default

nSim, epsSim

if working weights cannot be computed analytically these arguments specify maximum number of simulations allowed and precision level for finding them numerically respectively.

eimStep

a non negative integer describing how many values should be used at each step of approximation of information matrixes when no analytic solution is available (e.g. "ztnegbin"), default varies depending on a function. Higher value usually means faster convergence but may potentially cause issues with convergence.

a link for dispersion parameter, "log" by default

a link for inflation parameter, "logit" by default

Value

A object of class family containing objects:

  • makeMinusLogLike – A factory function for creating the following functions: (), , ^2^T functions from the y vector and the X_vlm matrix (or just X if applied to model with single linear predictor)which has the deriv argument with possible values in c(0, 1, 2) that determine which derivative to return; the default value is 0, which represents the minus log-likelihood.

  • links – A list with link functions.

  • mu.eta, variance – Functions of linear predictors that return expected value and variance. The type argument with 2 possible values ("trunc" and "nontrunc") that specifies whether to return E(Y|Y>0), var(Y|Y>0) or E(Y), var(Y) respectively; the deriv argument with values in c(0, 1, 2) is used for indicating the derivative with respect to the linear predictors, which is used for providing standard errors in the predict method.

  • family – A string that specifies name of the model.

  • valideta, validmu – For now it only returns TRUE. In the near future, it will be used to check whether applied linear predictors are valid (i.e. are transformed into some elements of the parameter space subjected to the inverse link function).

  • funcZ, Wfun – Functions that create pseudo residuals and working weights used in IRLS algorithm.

  • devResids – A function that given the linear predictors prior weights vector and response vector returns deviance residuals. Not all family functions have these functions implemented yet.

  • pointEst, popVar – Functions that given prior weights linear predictors and in the latter case also estimate of cov() and X_vlm matrix return point estimate for population size and analytic estimation of its variance.There is a additional boolean parameter contr in the former function that if set to true returns contribution of each unit.

  • etaNames – Names of linear predictors.

  • densityFunction – A function that given linear predictors returns value of PMF at values x. Additional argument type specifies whether to return P(Y|Y>0) or P(Y).

  • simulate – A function that generates values of a dependent vector given linear predictors.

  • getStart – An expression for generating starting points.

Details

Most of these functions are based on some "base" distribution with support N_0=N 0 that describe distribution of Y before truncation. Currently they include: P(Y=y|,)= arraycc ^ye^-y! & Poisson distribution
(y+^-1)(^-1)y! (^-1^-1+)^^-1 (^-1+)^y & negative binomial distribution
^y(1+)^y+1 & geometric distribution array . where is the Poisson parameter and is the dispersion parameter. Geometric distribution is a special case of negative binomial distribution when =1 it is included because negative binomial distribution is quite troublesome numerical regression in fitting. It is important to know that PMF of negative binomial distribution approaches the PMF of Poisson distribution when 0^+.

Note in literature on single source capture recapture models the dispersion parameter which introduces greater variability in negative binomial distribution compared to Poisson distribution is generally interpreted as explaining the unobserved heterogeneity i.e. presence of important unobserved independent variables. All these methods for estimating population size are tied to Poisson processes hence we use as parameter symbol instead of to emphasize this connection. Also will not be hard to see that all estimators derived from modifying the "base" distribution are unbiased if assumptions made by respective models are not violated.

The zero truncated models corresponding to "base" distributions are characterized by relation: P(Y=y|Y>0)= arraycc P(Y=y)1-P(Y=0) & when y 0
0 & when y=0 array. which allows us to estimate parameter values using only observed part of population. These models lead to the following estimates, respectively: aligned N &= _k=1^N_obs11-(-_k) & For Poisson distribution
N &= _k=1^N_obs11-(1+\alpha_k_k)^-_k^-1 & For negative binomial distribution
N &= _k=1^N_obs1+_k_k & For geometric distribution aligned

One common way in which assumptions of zero truncated models are violated is presence of one inflation the presence of which is somewhat similar in single source capture-recapture models to zero inflation in usual count data analysis. There are two ways in which one inflation may be understood, they relate to whether P(Y=0) is modified by inflation. The first approach is inflate ( parameter) zero truncated distribution as: P_new(Y=y|Y>0) = arraycc + (1 - )P_old(Y=1|Y>0)& when: y = 1
(1 - ) P_old(Y=y|Y>0) & when: y 1 array. which corresponds to: P_new(Y=y) = arraycc P_old(Y=0) & when: y = 0
(1 - P(Y=0)) + (1 - )P_old(Y=1) & when: y = 1
(1 - ) P_old(Y=y) & when: y > 1 array. before zero truncation. Models that utilize this approach are commonly referred to as zero truncated one inflated models. Another way of accommodating one inflation in SSCR is by putting inflation parameter on base distribution as: P_new(Y=y) = arraycc + (1 - )P_old(Y=1)& when: y = 1
(1 - ) P_old(Y=y) & when: y 1 array. which then becomes: P_new(Y=y|Y>0) = arraycc 1 - (1-)P_old(Y=0) + (1 - )1 - (1-)P_old(Y=0)P_old(Y=1)& when: y = 1
(1 - )1 - (1-)P_old(Y=0)P_old(Y=y) & when: y > 1 array. after truncation. It was shown by Böhning in 2022 paper that these approaches are equivalent in terms of maximizing likelihoods if we do not put formula on . They can however lead to different population size estimates.

For zero truncated one inflated models the formula for population size estimate N does not change since P(y=0) remains the same but estimation of parameters changes all calculations.

For one inflated zero truncated models population size estimates are expressed, respectively by: aligned N &= _k=1^N_obs11-(1-_k)(-_k) & For base Poisson distribution
N &= _k=1^N_obs11-(1-_k)(1+\alpha_k_k)^-_k^-1 & For base negative binomial distribution
N &= _k=1^N_obs1+_k_k + _k & For base geometric distribution aligned

Zero one truncated models ignore one counts instead of accommodating one inflation by utilizing the identity _ztoi=f_1f_1N_obs +(N_obs-f_1)(1-f_1N_obs ) + _zot where _zot is the log likelihood of zero one truncated distribution characterized by probability mass function: P(Y=y|Y>1)= arraycc P(Y=y)1-P(Y=0)-P(Y=1) & when y > 1
0 & when y 0, 1 array. where P(Y) is the probability mass function of the "base" distribution. The identity above justifies use of zero one truncated, unfortunately it was only proven for intercept only models, however numerical simulations seem to indicate that even if the theorem cannot be extended for (non trivial) regression population size estimation is still possible.

For zero one truncated models population size estimates are expressed by: aligned N &= f_1 + _k=1^N_obs 1-_k(-_k)1-(-_k)-_k(-_k) & For base Poisson distribution
N &= f_1 + _k=1^N_obs 1-_k(1+_k_k)^-1-_k^-1 1-(1+_k_k)^-_k^-1-_k(1+_k_k)^-1-_k^-1 & For base negative binomial distribution
N &= f_1 + _k=1^N_obs _k^2+_k+1_k^2 & For base geometric distribution aligned

Pseudo hurdle models are experimental and not yet described in literature.

Lastly there are chao and zelterman models which are based on logistic regression on the dummy variable Z = arraycc 0 & if Y = 1
1 & if Y = 2 array. based on the equation: logit(p_k)= (_k2)= x_k=_k where _k is the Poisson parameter.

The zelterman estimator of population size is expressed as: N=_k=1^N_obs1-(-_k) and chao estimator has the form: N=N_obs+_k=1^f_1+f_2 1_k+ _k^22

See also

estimatePopsize()

Author

Piotr Chlebicki, Maciej Beręsewicz