Package 'zmctp'

zmctp: Zero-Modified Complex Triparametric Pearson Distribution

Description

The zmctp package extends the Complex Triparametric Pearson (CTP) distribution with a zero-inflated mixture. It provides distribution functions, likelihood fitting and numerical boundary diagnostics.

Details

Main functions:

• dctp, pctp, qctp, rctp - CTP distribution functions

• dzictp, pzictp, qzictp, rzictp - Zero-Modified CTP distribution functions

• ctp.fit - Fit CTP model

• zictp.fit - Fit Zero-Modified CTP model

Author(s)

Maintainer: Rasheedat Oladoja [email protected] (ORCID)

Authors:

• Kabir Opeyemi Olorede (ORCID)

See Also

Useful links:

• https://github.com/roladoja/zmctp

• Report bugs at https://github.com/roladoja/zmctp/issues

---

Maximum likelihood fitting for CTP

Description

Fit an independent-observation CTP model in the finite-variance domain.

Usage

ctp.fit(
  x,
  a_start = NULL,
  b_start = NULL,
  gama_start = NULL,
  method = "L-BFGS-B",
  penalty = 1e+10
)

Arguments

x	Nonempty numeric vector of finite nonnegative integer counts, with at least one positive count and maximum at most 1,000,000.
a_start, b_start, gama_start	Optional finite scalar starting values. A supplied triple must have b_start > 0, gama_start > 0, and gama_start > 2*a_start+2. A partial triple supplements safe defaults. An inconsistent gamma margin is replaced with a safe margin with a warning, as in version 0.1.3.
method	An optim method used to supplement the default multistart Nelder-Mead search and nlminb polishing. Supported values are "L-BFGS-B", "BFGS", "Nelder-Mead", and "CG".
penalty	Positive finite objective penalty, retained for compatibility. Values too small to exceed the initial feasible objectives are increased.

Details

Coordinates are $(a,\log b,\log(\gamma-2a-2))$. The final transformed coordinates are retained. Six fixed starting triples are used, with a user-supplied start added when present. The two best finite Nelder-Mead solutions are polished with nlminb and the requested supplementary method. Convergence requires a successful optimiser within 1e-4 log-likelihood units of the best finite point.

Wald standard errors require convergence, b >= 1e-6, variance margin at least 1e-3, and a positive definite observed Hessian with minimum eigenvalue greater than 1e-10 times its maximum. Missing uncertainty is reported as NULL, with an explanation in diagnostics. No Hessian jitter or negative-variance clipping is used.

The frequency table includes unobserved counts through the sample maximum and a final upper-tail bin. Pearson and the historically named wald_chisq statistics are descriptive discrepancies, not calibrated tests. The latter is the sum of squared standardised observations.

Value

An object of class ctpfit, retaining fields estimates, se, vcov, logLik, AIC, BIC, pearson_chisq, wald_chisq, fitted_freq, data, converged, near_boundary, method, and raw_optim. Additional fields theta, attempts, and diagnostics record transformed coordinates, search outcomes and numerical flags. The raw_optim$par coordinates are now a, log_b, and log_margin; they should not be interpreted as natural parameters.

Examples

x <- rep(0:4, c(30, 16, 8, 3, 1))
fit <- ctp.fit(x)
fit$estimates
fit$diagnostics

---

CTP distribution

Description

Density, distribution, quantile and random-generation functions for the complex triparametric Pearson distribution.

Usage

dctp(x, a, b, gama, log = FALSE)

pctp(q, a, b, gama, lower.tail = TRUE, log.p = FALSE)

qctp(
  p,
  a,
  b,
  gama,
  lower.tail = TRUE,
  log.p = FALSE,
  max_q = 1000,
  max_count = 1000000L
)

rctp(n, a, b, gama)

Arguments

x	Numeric vector of counts. Nonintegers and negative values have probability zero; missing values propagate.
a, b, gama	Finite scalar parent parameters, with b >= 0 and gama > max(0, 2*a). The spelling gama is retained.
log	Return log probabilities.
q	Numeric vector of quantiles; values are rounded down.
lower.tail	Return $P(X \le q)$ if true and $P(X > q)$ otherwise.
log.p	Probabilities are on the log scale.
p	Numeric vector of probabilities. Missing values propagate.
max_q	Initial search endpoint, retained for compatibility. It is expanded as needed, rather than returned as a capped quantile.
max_count	Maximum search endpoint, at most 1,000,000. Failure to bracket a requested quantile raises an error.
n	Number of draws, a nonnegative integer.

Details

The probability at zero is evaluated from a shifted log-gamma expansion. Subsequent log probabilities use the recurrence

$p(k+1)/p(k) = ((a+k)^2+b^2)/((gama+k)(k+1)).$

Probabilities are not renormalised on the requested support. Moment existence is checked by moment functions, not by density functions. Recurrences have a work limit of 1,000,000 counts and signal an error when that limit is insufficient. At b = 0, nonpositive integer a gives a terminating distribution.

Value

Numeric vector of probabilities, cumulative probabilities, quantiles, or integer random draws. Quantiles return Inf at probability one for an infinite-support distribution.

Examples

dctp(0:5, 1, 0.5, 6)
pctp(c(-Inf, 0, 2, Inf), 1, 0.5, 6)
qctp(c(0, 0.5, 0.99, 1), 1, 0.5, 6)
set.seed(123)
rctp(10, 1, 0.5, 6)

---

Zero-inflated CTP distribution

Description

A mixture of a point mass at zero and a CTP parent. The historical package name uses "zero-modified"; this nonnegative mixing-probability model adds zeros relative to the same parent distribution.

Usage

dzictp(x, a, b, gama, omega, log = FALSE)

pzictp(q, a, b, gama, omega, lower.tail = TRUE, log.p = FALSE)

qzictp(
  p,
  a,
  b,
  gama,
  omega,
  lower.tail = TRUE,
  log.p = FALSE,
  max_q = 1000,
  max_count = 1000000L
)

rzictp(n, a, b, gama, omega)

Arguments

x	Numeric vector of counts. Nonintegers and negative values have probability zero; missing values propagate.
a, b, gama	Finite scalar parent parameters, with b >= 0 and gama > max(0, 2*a). The spelling gama is retained.
omega	Scalar mixing probability in [0, 1]. Zero gives the parent distribution; one gives a point mass at zero. Positive values increase the zero probability whenever the parent is nondegenerate.
log	Return log probabilities.
q	Numeric vector of quantiles; values are rounded down.
lower.tail	Return $P(X \le q)$ if true and $P(X > q)$ otherwise.
log.p	Probabilities are on the log scale.
p	Numeric vector of probabilities. Missing values propagate.
max_q	Initial search endpoint, retained for compatibility. It is expanded as needed, rather than returned as a capped quantile.
max_count	Maximum search endpoint, at most 1,000,000. Failure to bracket a requested quantile raises an error.
n	Number of draws, a nonnegative integer.

Details

$P(Y=0)=omega+(1-omega)P(X=0)$ and $P(Y=k)=(1-omega)P(X=k)$ for $k>0$. Quantile search limits and endpoint conventions are as in dctp.

Value

Numeric vector of probabilities, cumulative probabilities or quantiles, or integer random draws.

Examples

dzictp(0:5, 1, 0.5, 6, 0.3)
pzictp(0:5, 1, 0.5, 6, 0.3)
qzictp(c(0.1, 0.5, 0.9), 1, 0.5, 6, 0.3)
rzictp(10, 1, 0.5, 6, 0.3)

---

Moments of the CTP distribution

Description

Moments of the CTP distribution

Usage

mean_ctp(a, b, gama)

var_ctp(a, b, gama)

skew_ctp(a, b, gama)

Arguments

a, b, gama

Scalar parent parameters; see dctp.

Details

For an infinite-support parent the mean, variance and third moment require gama > 2*a+1, gama > 2*a+2, and gama > 2*a+3, respectively. A nonexisting mean or variance returns Inf with a warning; nonexisting skewness returns NaN with a warning. Terminating parents are handled separately.

Value

A scalar mean, variance or skewness.

Examples

mean_ctp(1, 0.5, 6)
var_ctp(1, 0.5, 6)
skew_ctp(1, 0.5, 6)

---

Moments of the zero-inflated CTP distribution

Description

Moments of the zero-inflated CTP distribution

Usage

mean_zictp(a, b, gama, omega)

var_zictp(a, b, gama, omega)

skew_zictp(a, b, gama, omega)

Arguments

a, b, gama	Scalar parent parameters; see dctp.
omega	Scalar mixing probability in [0, 1].

Details

Moment domains are the same as for the parent, except that omega = 1 gives mean and variance zero. Skewness of a degenerate distribution is undefined and returns NaN.

Value

A scalar mean, variance or skewness.

Examples

mean_zictp(1, 0.5, 6, 0.3)
var_zictp(1, 0.5, 6, 0.3)
skew_zictp(1, 0.5, 6, 0.3)

---

Mode of the CTP distribution

Description

Mode of the CTP distribution

Usage

mode_ctp(a, b, gama)

Arguments

a, b, gama

Scalar parent parameters; see dctp.

Details

Ties are detected to relative tolerance 1e-10. The recurrence minus one changes sign at most once in the valid domain.

Value

The modal integer, or both adjacent integers in a numerical tie.

Examples

mode_ctp(-1.5, 1.8, 3.8)

---

Mode of the zero-inflated CTP distribution

Description

Mode of the zero-inflated CTP distribution

Usage

mode_zictp(a, b, gama, omega)

Arguments

a, b, gama	Scalar parent parameters; see dctp.
omega	Scalar mixing probability in [0, 1].

Value

The smallest modal integer; ties are resolved to the smallest value.

Examples

mode_zictp(-1.5, 1.8, 3.8, 0.3)

---

Plot method for ctpfit objects

Description

Plot method for ctpfit objects

Usage

## S3 method for class 'ctpfit'
plot(x, type = c("frequency", "cdf", "qq"), ...)

Arguments

x	A ctpfit object
type	Type of plot: "frequency", "cdf", or "qq"
...	Additional graphical parameters

Value

No return value. Called for its side effect of producing a plot.

---

Plot method for zictpfit objects

Description

Creates diagnostic plots for Zero-Modified CTP distribution fits, including frequency comparisons, CDF plots, and Q-Q plots.

Usage

## S3 method for class 'zictpfit'
plot(x, type = c("frequency", "cdf", "qq"), ...)

Arguments

x	A zictpfit object from zictp.fit()
type	Type of plot: "frequency", "cdf", or "qq"
...	Additional graphical parameters

Value

No return value. Called for its side effect of producing a plot.

---

Print method for ctpfit objects

Description

Print method for ctpfit objects

Usage

## S3 method for class 'ctpfit'
print(x, ...)

Arguments

x	A ctpfit object
...	Additional arguments (ignored)

Value

Invisibly returns the original fitted model object. The function is called for its side effect of printing a model summary.

---

Print method for zictpfit objects

Description

Print method for zictpfit objects

Usage

## S3 method for class 'zictpfit'
print(x, ...)

Arguments

x	A zictpfit object
...	Additional arguments (ignored)

Value

Invisibly returns the original fitted model object. The function is called for its side effect of printing a model summary.

---

Summary method for ctpfit objects

Description

Summary method for ctpfit objects

Usage

## S3 method for class 'ctpfit'
summary(object, ...)

Arguments

object	A ctpfit object
...	Additional arguments (ignored)

Value

Invisibly returns the original fitted model object. The function is called for its side effects, producing a formatted summary of parameter estimates, moments, and goodness-of-fit diagnostics.

---

Summary method for zictpfit objects

Description

Summary method for zictpfit objects

Usage

## S3 method for class 'zictpfit'
summary(object, ...)

Arguments

object	A zictpfit object
...	Additional arguments (ignored)

Value

Invisibly returns the original fitted model object. The function is called for its side effects, producing a formatted summary of parameter estimates, moments, and goodness-of-fit diagnostics.

---

Maximum likelihood fitting for zero-inflated CTP

Description

Fits the zero-inflated model while profiling the mixing probability analytically. The exact parent boundary omega = 0 is permitted.

Usage

zictp.fit(
  x,
  a_start = NULL,
  b_start = NULL,
  gama_start = NULL,
  omega_start = NULL,
  method = "BFGS"
)

Arguments

x	Nonempty numeric vector of finite nonnegative integer counts, with at least one positive count and maximum at most 1,000,000.
a_start, b_start, gama_start	Optional finite scalar starting values. A supplied triple must have b_start > 0, gama_start > 0, and gama_start > 2*a_start+2. A partial triple supplements safe defaults. An inconsistent gamma margin is replaced with a safe margin with a warning, as in version 0.1.3.
omega_start	Retained for call compatibility. If supplied it must be a scalar in [0, 1). It does not affect the analytic profile.
method	An optim method used to supplement the default multistart Nelder-Mead search and nlminb polishing. Supported values are "L-BFGS-B", "BFGS", "Nelder-Mead", and "CG".

Details

For a fixed parent with zero probability $f_0$ and observed zero fraction $q$, the profile estimate is zero when $q\le f_0$ and $(q-f_0)/(1-f_0)$ otherwise. A parent fit is included as a feasible nested point. All-zero samples are rejected because the parent parameters are unidentified. In addition to the checks in ctp.fit, Wald uncertainty is withheld within 1e-5 of an omega endpoint. Bootstrap tests remain in the research supplement in this release.

Value

An object of class zictpfit with the fields described in ctp.fit, plus diagnostics$parent_logLik.

Examples

x <- rep(0:4, c(40, 12, 6, 2, 1))
fit <- zictp.fit(x)
fit$estimates

---