Help for package TruncatedPCQM

Title:

Density Estimation for Point-Centered Quarter Method with Truncated Sampling

Version:

0.1.2

Maintainer:

Wenzhe Huang <51280155097@stu.ecnu.edu.cn>

Description:

Implements a systematic methodology for estimating population density from point-centered quarter method (PCQM) surveys when distance measurements are truncated by a maximum search radius (right-censored). The package provides a unified framework for analyzing such incomplete data, addressing both completely randomly distributed (Poisson) and spatially aggregated (Negative Binomial) populations. Key features include: (1) Adjusted moment-based density estimators for censored distances; (2) Maximum likelihood estimation (MLE) of density under the Poisson (CSR) model; and (3) Simultaneous MLE of density and an aggregation parameter under the Negative Binomial model. For more details, see Huang, Shen, Xing, and Zhao (2026) <doi:10.48550/arXiv.2603.08276>.

License:

GPL (≥ 3)

Encoding:

UTF-8

Language:

RoxygenNote:

7.3.3

Depends:

R (≥ 3.5.0)

Suggests:

testthat (≥ 3.0.0), dplyr (≥ 1.1.0)

Config/testthat/edition:

URL:

https://github.com/rcjhrpyt-droid/TruncatedPCQM

BugReports:

https://github.com/rcjhrpyt-droid/TruncatedPCQM/issues

NeedsCompilation:

Packaged:

2026-03-24 05:50:34 UTC; Lenovo

Author:

Wenzhe Huang [aut, cre], Guochun Shen [aut], Dingliang Xing [aut], Jiangyan Zhao [aut]

Repository:

CRAN

Date/Publication:

2026-03-27 10:30:02 UTC

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.

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.

Adjusted Moment-based Estimators for Right-censored PCQM Data

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Arguments

Value

Examples

Print Methods for PCQM Density Estimation Objects

Description

Usage

Arguments

Value

See Also

Examples

Summary Methods for PCQM Density Estimation Objects

Description

Usage

Arguments

Value