Package 'TruncatedPCQM'

Adjusted Moment-based Estimators for Right-censored PCQM Data

Description

Computes various density estimators (DK, Cottam, Pollard, Shen, Morisita) using adjusted moments to account for right-censoring in PCQM data.

Usage

adjusted_moments(
  distances,
  C = 20,
  q = 4,
  l = 1,
  init_method = "Pollard_censored"
)

Arguments

distances	A numeric vector, matrix, data.frame, or list of point-to-tree distances. For matrix/data.frame inputs, each row represents a sampling point and each column a sector.
C	Maximum search radius (censoring threshold). Distances exceeding C are treated as right-censored observations. Default is 20.
q	Number of sectors per sampling point. Default is 4.
l	Neighbor order. Default is 1.
init_method	Method for obtaining initial $\lambda$ estimate used in NBD-based estimators. One of: "Pollard_censored" (default), "Cottam_censored", or "DK_censored" (only for l = 1).

Value

An object of class "pcqm_moments" containing:

• DK_censored: Diggle-Koedam estimator value (NA if l is not 1)

• Cottam_censored: Cottam-type estimator value

• Pollard_censored: Pollard-type estimator value

• Shen_censored: Shen's NBD-based estimator value (NA if estimated k < 1)

• Morisita_censored: Morisita's first estimator value (NA if l = 1)

• k_hat: Estimated aggregation parameter k from Shen's estimator

• censored_rate: Proportion of censored sectors

• n_points: Number of sampling points

• n_sectors: Total number of sectors analyzed

• n_censored: Number of censored observations (R > C)

• call: Original function call

Examples

distances_matrix <- matrix(c(
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000,    7.655136,   13.815876,   10.423496,
     6.094721,    4.135461,    7.732912,    5.454545,
  9999.000000, 9999.000000,   14.787289,   15.670821,
  9999.000000,    9.825537,   11.611850,   15.757861,
  9999.000000,    9.670381,   14.055394,   17.075678,
    11.529219,    4.464136,    7.793114,   11.309553,
    13.307828,    5.864490,   13.309636,    5.897720,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000,   18.201084, 9999.000000,
  9999.000000,    7.809056,   12.612496,    5.601366,
     9.201294, 9999.000000,    8.353524,    9.683701,
     6.592604,   19.117869,   19.758384,   12.923507,
    15.574824,   10.643719,    9.494539,    7.382031,
     9.143077, 9999.000000,   15.551414,    5.266916,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    18.604278,    7.279454,    9.385355,    5.573127,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    11.980811, 9999.000000,   11.853695,   14.405252
), nrow = 20, ncol = 4, byrow = TRUE)


moment_result <- adjusted_moments(
  distances = distances_matrix,
  C = 20,
  q = 4,
  l = 2,
  init_method = "Pollard_censored"
)

moment_result

---

CSR-based Maximum Likelihood Estimator for Right-censored PCQM Data

Description

Computes the maximum likelihood estimate (MLE) of population density under complete spatial randomness (CSR), accounting for right-censored point-centered quarter method (PCQM) distances.

Usage

csr_mle(
  distances,
  C = 20,
  q = 4,
  l = 1,
  lambda_lower = 1e-04,
  lambda_upper = 1
)

Arguments

distances	A numeric vector, matrix, data.frame, or list of point-to-tree distances. For matrix/data.frame inputs, each row represents a sampling point and each column a sector.
C	Maximum search radius (censoring threshold). Distances exceeding C are treated as right-censored observations. Default is 20.
q	Number of sectors per sampling point. Default is 4.
l	Neighbor order. Default is 1.
lambda_lower	Lower bound for $\lambda$ in numerical optimization. Must be positive. Default is 1e-4.
lambda_upper	Upper bound for $\lambda$ in numerical optimization. Must be positive. Default is 1.

Value

An object of class "pcqm_csr_mle" containing:

• lambda: MLE of population density (individuals per unit area)

• logLik: Maximized log-likelihood value

• n_obs: Number of fully observed (non-censored) distances

• n_censored: Number of censored observations (R > C)

• n_sectors: Total number of sectors analyzed

• n_points: Inferred number of sampling points

• censored_rate: Proportion of censored sectors

• call: Original function call

Examples

distances_matrix <- matrix(c(
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000,    7.655136,   13.815876,   10.423496,
     6.094721,    4.135461,    7.732912,    5.454545,
  9999.000000, 9999.000000,   14.787289,   15.670821,
  9999.000000,    9.825537,   11.611850,   15.757861,
  9999.000000,    9.670381,   14.055394,   17.075678,
    11.529219,    4.464136,    7.793114,   11.309553,
    13.307828,    5.864490,   13.309636,    5.897720,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000,   18.201084, 9999.000000,
  9999.000000,    7.809056,   12.612496,    5.601366,
     9.201294, 9999.000000,    8.353524,    9.683701,
     6.592604,   19.117869,   19.758384,   12.923507,
    15.574824,   10.643719,    9.494539,    7.382031,
     9.143077, 9999.000000,   15.551414,    5.266916,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    18.604278,    7.279454,    9.385355,    5.573127,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    11.980811, 9999.000000,   11.853695,   14.405252
), nrow = 20, ncol = 4, byrow = TRUE)

csr_result <- csr_mle(
  distances = distances_matrix,
  C = 20,
  q = 4,
  l = 2,
  lambda_lower = 1e-4,
  lambda_upper = 1
)

csr_result

---

NBD-based Maximum Likelihood Estimator for Right-censored PCQM Data

Description

Computes the maximum likelihood estimate (MLE) of population density under Negative Binomial model, accounting for right-censored point-centered quarter method (PCQM) distances.

Usage

nbd_mle(
  distances,
  C = 20,
  q = 4,
  l = 1,
  init_method = "Shen_censored",
  lambda_lower = 1e-04,
  lambda_upper = 1
)

Arguments

distances	A numeric vector, matrix, data.frame, or list of point-to-tree distances. For matrix/data.frame inputs, each row represents a sampling point and each column a sector.
C	Maximum search radius (censoring threshold). Distances exceeding C are treated as right-censored observations. Default is 20.
q	Number of sectors per sampling point. Default is 4.
l	Neighbor order. Default is 1.
init_method	Method for obtaining initial parameter values. One of: "Shen_censored" (default), "Pollard_censored", "Cottam_censored", or "DK_censored" (l=1 only).
lambda_lower	Lower bound for $\lambda$ in numerical optimization. Must be positive. Default is 1e-4.
lambda_upper	Upper bound for $\lambda$ in numerical optimization. Must be positive. Default is 1.

Value

An object of class "pcqm_nbd_mle" containing:

• lambda: MLE of population density (individuals per unit area)

• k: MLE of aggregation parameter (smaller values indicate stronger aggregation)

• logLik: Maximized log-likelihood value

• n_obs: Number of fully observed (non-censored) distances

• n_censored: Number of censored observations (R > C)

• n_sectors: Total number of sectors analyzed

• n_points: Inferred number of sampling points

• censored_rate: Proportion of censored sectors

• call: Original function call

Examples

distances_matrix <- matrix(c(
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000,    7.655136,   13.815876,   10.423496,
     6.094721,    4.135461,    7.732912,    5.454545,
  9999.000000, 9999.000000,   14.787289,   15.670821,
  9999.000000,    9.825537,   11.611850,   15.757861,
  9999.000000,    9.670381,   14.055394,   17.075678,
    11.529219,    4.464136,    7.793114,   11.309553,
    13.307828,    5.864490,   13.309636,    5.897720,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000,   18.201084, 9999.000000,
  9999.000000,    7.809056,   12.612496,    5.601366,
     9.201294, 9999.000000,    8.353524,    9.683701,
     6.592604,   19.117869,   19.758384,   12.923507,
    15.574824,   10.643719,    9.494539,    7.382031,
     9.143077, 9999.000000,   15.551414,    5.266916,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    18.604278,    7.279454,    9.385355,    5.573127,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    11.980811, 9999.000000,   11.853695,   14.405252
), nrow = 20, ncol = 4, byrow = TRUE)

nbd_result <- nbd_mle(
  distances = distances_matrix,
  C = 20,
  q = 4,
  l = 2,
  init_method = "Pollard_censored",
  lambda_lower = 1e-4,
  lambda_upper = 10
)

nbd_result

---

Print Methods for PCQM Density Estimation Objects

Description

Provides formatted console output for fitted PCQM (Point-Centered Quarter Method) density estimation results under different model assumptions. The following specialized print methods for S3 classes are supported:

• print.pcqm_csr_mle – display CSR-based PCQM maximum likelihood estimation results.

• print.pcqm_moments – display adjusted moment-based PCQM density estimators.

• print.pcqm_nbd_mle – display NBD-based PCQM maximum likelihood estimation results.

Usage

## S3 method for class 'pcqm_csr_mle'
print(x, digits = 6, ...)

## S3 method for class 'pcqm_moments'
print(x, digits = 6, ...)

## S3 method for class 'pcqm_nbd_mle'
print(x, digits = 6, ...)

Arguments

x	An object of class "pcqm_csr_mle", "pcqm_moments", or "pcqm_nbd_mle", returned by csr_mle, adjusted_moments, or nbd_mle, respectively.
digits	Number of decimal places to display for numeric estimates. Default is 6.
...	Additional arguments passed to the generic print method (currently unused; included for S3 consistency).

Value

The input model object x, invisibly. These functions are called primarily for their side effect of printing a formatted summary of the PCQM density estimation results to the R console.

See Also

csr_mle for CSR-based MLE estimation; adjusted_moments for adjusted moment estimators; nbd_mle for NBD-based MLE estimation.

Examples

distances_matrix <- matrix(c(
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000,    7.655136,   13.815876,   10.423496,
     6.094721,    4.135461,    7.732912,    5.454545,
  9999.000000, 9999.000000,   14.787289,   15.670821,
  9999.000000,    9.825537,   11.611850,   15.757861,
  9999.000000,    9.670381,   14.055394,   17.075678,
    11.529219,    4.464136,    7.793114,   11.309553,
    13.307828,    5.864490,   13.309636,    5.897720,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000,   18.201084, 9999.000000,
  9999.000000,    7.809056,   12.612496,    5.601366,
     9.201294, 9999.000000,    8.353524,    9.683701,
     6.592604,   19.117869,   19.758384,   12.923507,
    15.574824,   10.643719,    9.494539,    7.382031,
     9.143077, 9999.000000,   15.551414,    5.266916,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    18.604278,    7.279454,    9.385355,    5.573127,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
  9999.000000, 9999.000000, 9999.000000, 9999.000000,
    11.980811, 9999.000000,   11.853695,   14.405252
), nrow = 20, ncol = 4, byrow = TRUE)

# CSR-based MLE
csr_result <- csr_mle(
  distances = distances_matrix,
  C = 20,
  q = 4,
  l = 2,
  lambda_lower = 1e-4,
  lambda_upper = 1
)
print(csr_result)

# Adjusted Moment Estimators
moment_result <- adjusted_moments(
  distances = distances_matrix,
  C = 20,
  q = 4,
  l = 2,
  init_method = "Pollard_censored"
)
print(moment_result)

# NBD-based MLE
nbd_result <- nbd_mle(
  distances = distances_matrix,
  C = 20,
  q = 4,
  l = 2,
  init_method = "Pollard_censored",
  lambda_lower = 1e-4,
  lambda_upper = 10
)
print(nbd_result)

---

Summary Methods for PCQM Density Estimation Objects

Description

Generate structured summary objects and formatted console output for PCQM (Point-Centered Quarter Method) density estimation results under different model assumptions.

Supported S3 methods:

• summary.pcqm_csr_mle

• summary.pcqm_moments

• summary.pcqm_nbd_mle

• print.summary.pcqm_*

Usage

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

## S3 method for class 'summary.pcqm_csr_mle'
print(x, digits = 6, ...)

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

## S3 method for class 'summary.pcqm_moments'
print(x, digits = 6, ...)

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

## S3 method for class 'summary.pcqm_nbd_mle'
print(x, digits = 6, ...)

Arguments

object	Model object returned by csr_mle, adjusted_moments, or nbd_mle.
...	Additional arguments (unused).
x	Summary object returned by corresponding summary() method.
digits	Number of digits to display.

Value

An object of class "summary.pcqm_csr_mle", a named list with components:

model

Character string: "csr_mle".

lambda

Estimated population density (intensity parameter $\lambda$). NA if estimation failed.

logLik

Maximized log-likelihood evaluated at $\hat{\lambda}$.

n_points

Number of focal sampling points.

n_sectors

Total number of sectors.

n_censored

Number of censored sectors.

censored_rate

Proportion of censored sectors.

An object of class "summary.pcqm_moments", a named list with components:

model

Character string: "moments".

estimators

Named numeric vector of valid adjusted moment estimators (NA removed).

k_hat

Estimated aggregation (dispersion) parameter $\hat{k}$.

n_points

Number of focal sampling points.

n_sectors

Total number of sectors.

n_censored

Number of censored sectors.

censored_rate

Proportion of censored sectors.

An object of class "summary.pcqm_nbd_mle", a named list with components:

model

Character string: "nbd_mle".

lambda

Estimated population density (intensity parameter $\lambda$). NA if estimation failed.

k

Estimated aggregation (dispersion) parameter of the Negative Binomial distribution. NA if estimation failed.

logLik

Maximized log-likelihood evaluated at $(\hat{\lambda}, \hat{k})$.

n_points

Number of focal sampling points.

n_sectors

Total number of sectors.

n_censored

Number of censored sectors.

censored_rate

Proportion of censored sectors.

---