palm: A package to fit point process models via the Palm likelihood

Description

First proposed by Tanaka, Ogata, and Stoyan (2008), maximisation of the Palm likelihood can provide computationally efficient parameter estimation for point process models in situations where the full likelihood is intractable. This package contains functions to fit a variety of point process models, but is chiefly concerned with Neyman-Scott point processes (NSPPs).

Details

The development of this package was motivated by the analysis of capture-recapture surveys on which individuals cannot be identified—the data from which can conceptually be seen as a NSPP (Fewster, Stevenson, and Borchers, 2016). As such, some of the functions in this package are specifically for the estimation of cetacean density from two-camera aerial surveys; see Stevenson, Borchers, and Fewster (2019).

This package can also fit void processes, which, along with NSPPs, have been fitted to patterns of colon cancer and stroma cell locations (Jones-Todd et al., 2019).

The main functions of this package are summarised below.

Model fitting

• The fit.ns function fits NSPPs.

• The fit.twocamera function estimates animal density from two-camera aerial surveys. This model is a NSPP and can be fitted using fit.ns, but it is more straightforward to use fit.twocamera.

• The fit.void function fits void point processes.

Variance estimation

Variance estimation is achieved by parametric bootstrap. The boot.palm function carries out this procedure from an object generated by one of the fitting functions, above. Confidence intervals and standard errors can be calculated from an object returned by boot.palm using confint.palm and coef.palm, respectively.

Data simulation

• The sim.ns function simulates data from NSPPs.

• The sim.twocamera function simulates detection data from two-camera aerial surveys.

• The sim.void function simulates data from void point processes.

References

Fewster, R. M., Stevenson, B. C., and Borchers, D. L. (2016) Trace-contrast methods for capture-recapture without capture histories. Statistical Science, 31: 245–258.

Jones-Todd, C. M., Caie, P., Illian, J. B., Stevenson, B. C., Savage, A., Harrison, D. J., and Bown, J. L. (2019). Identifying prognostic structural features in tissue sections of colon cancer patients using point pattern analysis. Statistics in Medicine, 38: 1421–1441.

Stevenson, B. C., Borchers, D. L., and Fewster, R. M. (2019) Cluster capture-recapture to account for identification uncertainty on aerial surveys of animal populations. Biometrics, 75: 326–336.

Tanaka, U., Ogata, Y., and Stoyan, D. (2008) Parameter estimation and model selection for Neyman-Scott point processes. Biometrical Journal, 50: 43–57.

Bootstrapping for fitted models

Description

Carries out a parametric bootstrap procedure for models fitted using the palm package.

Usage

boot.palm(fit, N, prog = TRUE)

Arguments

Value

The original model object containing additional information from the bootstrap procedure. These are accessed by functions such as summary.palm and confint.palm. The bootstrap parameter estimates can be found in the boots component of the returned object.

Examples

## Fit model.
fit <- fit.ns(example.2D, lims = rbind(c(0, 1), c(0, 1)), R = 0.5)
## Carry out bootstrap.
fit <- boot.palm(fit, N = 100)
## Inspect standard errors and confidence intervals.
summary(fit)
confint(fit)
## Estimates are very imprecise---these data were only used as
## they can be fitted and bootstrapped quickly for example purposes.

Extract parameter estimates.

Description

Extracts estimated parameters from an object returned by the fitting functions in this package, such as fit.ns, fit.void, and fit.twocamera.

Usage

## S3 method for class 'palm'
coef(object, se = FALSE, ...)

## S3 method for class 'palm_twocamerachild'
coef(object, se = FALSE, report.2D = TRUE, ...)

Arguments

Extracts Neyman-Scott point process parameter confidence intervals.

Description

Extracts confidence intervals for estimated and derived parameters from a model fitted using fit.ns, fit.void, or fit.twocamera, then bootstrapped using boot.palm.

Usage

## S3 method for class 'palm'
confint(object, parm = NULL, level = 0.95, method = "percentile", ...)

Arguments

Details

Bootstrap parameter estimates can be found in the boots component of the model object, so alternative confidence interval methods can be calculated by hand.

Examples

## Fitting model.
fit <- fit.ns(example.2D, lims = rbind(c(0, 1), c(0, 1)), R = 0.5)
## Carrying out bootstrap.
fit <- boot.palm(fit, N = 100)
## Calculating 95% confidence intervals.
confint(fit)
## Estimates are very imprecise---these data were only used as
## they can be fitted and bootstrapped quickly for example purposes.

1-dimensional example data

Description

Simulated data from a Neyman-Scott point process, with children points generated in the interval [0, 1]. The number of children spawned by each parent is from a Binomial(4, 0.5) distribution.

Usage

example.1D

Format

A matrix.

2-dimensional example data

Description

Simulated data from a Neyman-Scott point process, with children points generated on the unit square. The number of children spawned by each parent is from a Binomial(2, 0.5) distribution.

Usage

example.2D

Format

A matrix.

Two-camera example data.

Description

Simulated data from a two-camera aerial survey.

Usage

example.twocamera

Format

A list.

Fitting a Neyman-Scott point process model

Description

Estimates parameters for a Neyman-Scott point process by maximising the Palm likelihood. This approach was first proposed by Tanaka et al. (2008) for two-dimensional Thomas processes. Further generalisations were made by Stevenson, Borchers, and Fewster (2019) and Jones-Todd et al. (2019).

Usage

fit.ns(
  points,
  lims,
  R,
  disp = "gaussian",
  child.dist = "pois",
  child.info = NULL,
  sibling.list = NULL,
  edge.correction = "pbc",
  start = NULL,
  bounds = NULL,
  use.bobyqa = FALSE,
  trace = FALSE
)

Arguments

Details

The parameter D is the density of parent points, which is always estimated. Possible additional parameters are

• lambda, the expected number of children generated per parent (when child.dist = "pois").

• p, the proportion of the x possible children that are generated (when child.dist = "binomx").

• kappa, the average length of the surface phase of a diving cetacean (when child.dist = "twocamera"; see Stevenson, Borchers, and Fewster, 2019).

• sigma, the standard deviation of dispersion along each dimension (when disp = "gaussian").

• tau, the maximum distance a child can be from its parent (when disp = "uniform").

The "child.info" argument is required when child.dist is set to "twocamera". It must be a list that comprises (i) a component named w, providing the halfwidth of the detection zone; (ii) a component named b, providing the halfwidth of the survey area; (iii) a component named l, providing the time lag between cameras (in seconds); and (iv) a component named tau, providing the mean dive-cycle duration. See Stevenson, Borchers, and Fewster (2019) for details.

Value

An R6 reference class object.

References

Jones-Todd, C. M., Caie, P., Illian, J. B., Stevenson, B. C., Savage, A., Harrison, D. J., and Bown, J. L. (in press). Identifying prognostic structural features in tissue sections of colon cancer patients using point pattern analysis. Statistics in Medicine, 38: 1421–1441.

Stevenson, B. C., Borchers, D. L., and Fewster, R. M. (2019) Cluster capture-recapture to account for identification uncertainty on aerial surveys of animal populations. Biometrics, 75: 326–336.

Tanaka, U., Ogata, Y., and Stoyan, D. (2008) Parameter estimation and model selection for Neyman-Scott point processes. Biometrical Journal, 50: 43–57.

See Also

Use coef.palm to extract estimated parameters, and plot.palm to plot the estimated Palm intensity function. Use boot.palm to run a parametric bootstrap, allowing calculation of standard errors and confidence intervals.

See sim.ns to simulate from a Neyman-Scott point process.

Examples

## Fitting model to example data.
fit <- fit.ns(example.2D, lims = rbind(c(0, 1), c(0, 1)), R = 0.5)
## Printing estimates.
coef(fit)
## Plotting the estimated Palm intensity.
plot(fit)
## Not run: 
## Simulating data and fitting additional models.
set.seed(1234)
## One-dimensional Thomas process.
data.thomas <- sim.ns(c(D = 10, lambda = 5, sigma = 0.025), lims = rbind(c(0, 1)))
## Fitting a model to these data.
fit.thomas <- fit.ns(data.thomas$points, lims = rbind(c(0, 1)), R = 0.5)
## Three-dimensional Matern process.
data.matern <- sim.ns(c(D = 10, lambda = 10, tau = 0.1), disp = "uniform",
                      lims = rbind(c(0, 1), c(0, 2), c(0, 3)))
## Fitting a model to these data.
fit.matern <- fit.ns(data.matern$points, lims = rbind(c(0, 1), c(0, 2), c(0, 3)),
                     R = 0.5, disp = "uniform")

## End(Not run)

Estimation of animal density from two-camera surveys.

Description

Estimates animal density (amongst other parameters) from two-camera aerial surveys. This conceptualises sighting locations as a Neyman-Scott point pattern.

Usage

fit.twocamera(
  points,
  cameras = NULL,
  d,
  w,
  b,
  l,
  tau,
  R,
  edge.correction = "pbc",
  start = NULL,
  bounds = NULL,
  trace = FALSE
)

Arguments

Details

This function is simply a wrapper for fit.ns, and facilitates the fitting of the model proposed by Stevenson, Borchers, and Fewster (2019). This function presents the parameter D.2D (two-dimensional cetacean density in cetaceans per square km) rather than D for enhanced interpretability.

For further details on the cluster capture-recapture estimation approach, see Fewster, Stevenson and Borchers (2016).

Value

An R6 reference class object.

References

Fewster, R. M., Stevenson, B. C., and Borchers, D. L. (2016) Trace-contrast methods for capture-recapture without capture histories. Statistical Science, 31: 245–258.

Stevenson, B. C., Borchers, D. L., and Fewster, R. M. (2019) Cluster capture-recapture to account for identification uncertainty on aerial surveys of animal populations. Biometrics, 75: 326–336.

See Also

Use coef.palm to extract estimated parameters, and plot.palm to plot the estimated Palm intensity function. Use boot.palm to run a parametric bootstrap, allowing calculation of standard errors and confidence intervals.

See sim.twocamera to simulate sightings from a two-camera aerial survey.

Examples

## Fitting model.
fit <- fit.twocamera(points = example.twocamera$points, cameras = example.twocamera$cameras,
                     d = 500, w = 0.175, b = 0.5, l = 20, tau = 110, R = 1)
## Printing estimates.
coef(fit)
## Plotting the estimated Palm intensity.
plot(fit)

Fitting a model to a void point process

Description

Estimates parameters for a void point process by maximising the Palm likelihood. This approach was first proposed by Tanaka et al. (2008) for two-dimensional Thomas processes. Generalisation to d-dimensional void processes was made by Jones-Todd et al. (in press).

Usage

fit.void(
  points,
  lims,
  R,
  edge.correction = "pbc",
  start = NULL,
  bounds = NULL,
  use.bobyqa = FALSE,
  trace = FALSE
)

Arguments

Details

Parameters to estimate are as follows:

• Dc, the baseline density of points prior to the deletion process.

• Dp, the density of unobserved parents that cause voids.

• tau, the radius of the deletion process centred at each parent.

Value

An R6 reference class object.

References

Jones-Todd, C. M., Caie, P., Illian, J. B., Stevenson, B. C., Savage, A., Harrison, D. J., and Bown, J. L. (in press). Identifying prognostic structural features in tissue sections of colon cancer patients using point pattern analysis. Statistics in Medicine, 38: 1421–1441.

Tanaka, U., Ogata, Y., and Stoyan, D. (2008) Parameter estimation and model selection for Neyman-Scott point processes. Biometrical Journal, 50: 43–57.

See Also

Use coef.palm to extract estimated parameters, and plot.palm to plot the estimated Palm intensity function. Use boot.palm to run a parametric bootstrap, allowing calculation of standard errors and confidence intervals.

See sim.void to simulate from a void process.

Examples

## Not run: 
set.seed(1234)
## Simulating a two-dimensional void process.
void.data <- sim.void(c(Dc = 1000, Dp = 10, tau = 0.05), rbind(c(0, 1), c(0, 1)))
## Fitting model.
fit <- fit.void(void.data$points, rbind(c(0, 1), c(0, 1)), R = 0.5)

## End(Not run)

Plotting an estimated Palm intensity function.

Description

Plots a fitted Palm intensity function from an object returned by fit.ns.

Usage

## S3 method for class 'palm'
plot(x, xlim = NULL, ylim = NULL, show.empirical = TRUE, breaks = 50, ...)

Arguments

Examples

## Fit model.
fit <- fit.ns(example.2D, lims = rbind(c(0, 1), c(0, 1)), R = 0.5)
## Plot fitted Palm intensity.
plot(fit)

Two-camera porpoise data.

Description

Synthetic data constructed from circle-back aerial survey data; see Stevenson, Borchers, and Fewster (2019).

Usage

porpoise.data

Format

A list.

References

Stevenson, B. C., Borchers, D. L., and Fewster, R. M. (2019) Cluster capture-recapture to account for identification uncertainty on aerial surveys of animal populations. Biometrics, 75: 326–336.

Simulating points from a Neyman-Scott point process

Description

Generates points from a Neyman-Scott point process using parameters provided by the user.

Usage

sim.ns(
  pars,
  lims,
  disp = "gaussian",
  child.dist = "pois",
  parents = NULL,
  child.info = NULL
)

Arguments

Details

For a list of possible parameter names, see fit.ns.

The "child.info" argument is required when child.dist is set to "twocamera". It must be a list that comprises (i) a component named w, providing the halfwidth of the detection zone; (ii) a component named b, providing the halfwidth of the survey area; (iii) a component named l, providing the time lag between cameras (in seconds); and (iv) a component named tau, providing the mean dive-cycle duration. See Stevenson, Borchers, and Fewster (2019) for details.

Value

A list. The first component gives the Cartesian coordinates of the generated points. The second component returns the parent locations. A third component may provide sibling information.

References

Stevenson, B. C., Borchers, D. L., and Fewster, R. M. (2019) Cluster capture-recapture to account for identification uncertainty on aerial surveys of animal populations. Biometrics, 75: 326–336.

Examples

## Simulating from a one-dimensional Thomas process.
data.thomas <- sim.ns(c(D = 10, lambda = 5, sigma = 0.025), lims = rbind(c(0, 1)))
## Simulating from a three-dimensional Matern process.
data.matern <- sim.ns(c(D = 10, lambda = 10, tau = 0.1), disp = "uniform",
                      lims = rbind(c(0, 1), c(0, 2), c(0, 3)))

Simulating data from two-camera aerial surveys.

Description

Simulating data from two-camera aerial surveys.

Usage

sim.twocamera(pars, d, w, b, l, tau, parents = NULL)

Arguments

Value

A list. The first component gives the distance along the transect of detected individuals. The second gives the parent locations. The third identifies which parent location generated each detected individual. The fourth gives the distance from the transect centre line of the detection location. The fifth provides observed sibling information.

Examples

twocamera.data <- sim.twocamera(c(D.2D = 1.3, kappa = 27, sigma = 0.02), d = 500,
                                w = 0.175, b = 0.5, l = 20, tau = 110)

Simulating points from a void point process.

Description

Generates points from a void point process using parameters provided by the user.

Usage

sim.void(pars, lims, parents = NULL)

Arguments

Details

For a list of possible parameter names, see fit.ns.

Value

A list. The first component gives the Cartesian coordinates of the generated points. The second component returns the parent locations.

Examples

## Two-dimensional void process.
void.data <- sim.void(c(Dc = 1000, Dp = 10, tau = 0.05), rbind(c(0, 1), c(0, 1)))
## Plotting the data.
plot(void.data$points)
points(void.data$parents, pch = 16, col = "red")

Summarising palm model fits

Description

Provides a useful summary of the model fit.

Usage

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

Arguments