Type:	Package
Title:	Estimate and Simulate from Location Dependent Marked Point Processes
Version:	1.1.2
Maintainer:	Lane Drew <lanetdrew@gmail.com>
Description:	A suite of tools for estimating, assessing model fit, simulating from, and visualizing location dependent marked point processes characterized by regularity in the pattern. You provide a reference marked point process, a set of raster images containing location specific covariates, and select the estimation algorithm and type of mark model. 'ldmppr' estimates the process and mark models and allows you to check the appropriateness of the model using a variety of diagnostic tools. Once a satisfactory model fit is obtained, you can simulate from the model and visualize the results. Documentation for the package 'ldmppr' is available in the form of a vignette.
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
Imports:	stats, bundle, Rcpp (≥ 1.0.12), terra, doParallel, xgboost, parsnip (≥ 1.4.0), dials, recipes, rsample, tune, workflows, magrittr, hardhat, ggplot2, spatstat.geom, spatstat.explore, nloptr, GET, progress, progressr, future, furrr, foreach, yardstick
LinkingTo:	Rcpp, RcppArmadillo
URL:	https://github.com/lanedrew/ldmppr, https://lanedrew.github.io/ldmppr/
BugReports:	https://github.com/lanedrew/ldmppr/issues
RoxygenNote:	7.3.3
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0), dplyr, rstudioapi, parallelly, ranger
VignetteBuilder:	knitr
Depends:	R (≥ 3.5.0)
Config/testthat/edition:	3
NeedsCompilation:	yes
Packaged:	2026-03-01 21:30:38 UTC; lanedrew
Author:	Lane Drew [aut, cre, cph], Andee Kaplan [aut]
Repository:	CRAN
Date/Publication:	2026-03-01 21:50:02 UTC

ldmppr: Estimate and Simulate from Location Dependent Marked Point Processes

Description

A suite of tools for estimating, assessing model fit, simulating from, and visualizing location dependent marked point processes characterized by regularity in the pattern. You provide a reference marked point process, a set of raster images containing location specific covariates, and select the estimation algorithm and type of mark model. 'ldmppr' estimates the process and mark models and allows you to check the appropriateness of the model using a variety of diagnostic tools. Once a satisfactory model fit is obtained, you can simulate from the model and visualize the results. Documentation for the package 'ldmppr' is available in the form of a vignette.

Author(s)

Maintainer: Lane Drew lanetdrew@gmail.com (ORCID) [copyright holder]

Authors:

• Andee Kaplan (ORCID)

See Also

Useful links:

• https://github.com/lanedrew/ldmppr

• https://lanedrew.github.io/ldmppr/

• Report bugs at https://github.com/lanedrew/ldmppr/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling 'rhs(lhs)'.

calculates c_theta

Description

calculates c_theta

Usage

C_theta2_i(xgrid, ygrid, tgrid, data, params, bounds)

Arguments

Value

returns the product.

Check the fit of an estimated model using global envelope tests

Description

Performs global envelope tests for nonparametric L, F, G, J, E, and V summary functions (spatstat/GET). These tests assess goodness-of-fit of the estimated model relative to a reference marked point pattern. The reference marked point pattern can be supplied directly via reference_data (a marked ppp object), or derived internally from a ldmppr_fit object.

Usage

check_model_fit(
  reference_data = NULL,
  t_min = 0,
  t_max = 1,
  process = c("self_correcting"),
  process_fit = NULL,
  anchor_point = NULL,
  raster_list = NULL,
  scaled_rasters = FALSE,
  mark_model = NULL,
  xy_bounds = NULL,
  include_comp_inds = FALSE,
  thinning = TRUE,
  edge_correction = "none",
  competition_radius = 15,
  n_sim = 2500,
  save_sims = TRUE,
  verbose = TRUE,
  seed = 0,
  parallel = FALSE,
  num_cores = max(1L, parallel::detectCores() - 1L),
  set_future_plan = FALSE,
  mark_mode = NULL,
  fg_correction = c("km", "rs"),
  max_attempts = NULL
)

Arguments

Details

This function relies on the spatstat package for the calculation of the point pattern metrics and the GET package for the global envelope tests. The L, F, G, J, E, and V functions are a collection of non-parametric summary statistics that describe the spatial distribution of points and marks in a point pattern. See the documentation for Lest(), Fest(), Gest(), Jest(), Emark(), and Vmark() for more information. Also, see the global_envelope_test() function for more information on the global envelope tests.

Value

an object of class "ldmppr_model_check".

References

Baddeley, A., Rubak, E., & Turner, R. (2015). *Spatial Point Patterns: Methodology and Applications with R*. Chapman and Hall/CRC Press, London. ISBN 9781482210200. Available at: https://www.routledge.com/Spatial-Point-Patterns-Methodology-and-Applications-with-R/Baddeley-Rubak-Turner/p/book/9781482210200.

Myllymäki, M., & Mrkvička, T. (2023). GET: Global envelopes in R. arXiv:1911.06583 [stat.ME]. doi:10.48550/arXiv.1911.06583.

Examples

# Note: The example below is provided for illustrative purposes and may take some time to run.

data(small_example_data)

file_path <- system.file("extdata", "example_mark_model.rds", package = "ldmppr")
mark_model <- load_mark_model(file_path)

raster_paths <- list.files(system.file("extdata", package = "ldmppr"),
                           pattern = "\\.tif$", full.names = TRUE)
raster_paths <- raster_paths[!grepl("_med\\.tif$", raster_paths)]
rasters <- lapply(raster_paths, terra::rast)
scaled_raster_list <- scale_rasters(rasters)

reference_data <- generate_mpp(
  locations = small_example_data[, c("x", "y")],
  marks = small_example_data$size,
  xy_bounds = c(0, 25, 0, 25)
)

estimated_parameters <- c(
  0.05167978, 8.20702166, 0.02199940, 2.63236890,
  1.82729512, 0.65330061, 0.86666748, 0.04681878
)

# Keep parallel=FALSE in examples to avoid setup overhead.
example_model_fit <- check_model_fit(
  reference_data = reference_data,
  t_min = 0,
  t_max = 1,
  process = "self_correcting",
  process_fit = estimated_parameters,
  raster_list = scaled_raster_list,
  scaled_rasters = TRUE,
  mark_model = mark_model,
  xy_bounds = c(0, 25, 0, 25),
  include_comp_inds = TRUE,
  thinning = TRUE,
  edge_correction = "none",
  competition_radius = 10,
  n_sim = 100,
  save_sims = FALSE,
  verbose = TRUE,
  seed = 90210,
  parallel = FALSE
)

plot(example_model_fit, which = 'combined')

calculates sum of values < t

Description

calculates sum of values < t

Usage

conditional_sum(obs_t, eval_t, y)

Arguments

Value

the conditional sum.

calculates sum of values < t

Description

calculates sum of values < t

Usage

conditional_sum_logical(obs_t, eval_t, y)

Arguments

Value

the conditional sum.

calculates distance in one dim

Description

calculates distance in one dim

Usage

dist_one_dim(eval_t, obs_t)

Arguments

Value

distance between a single t and the vector of all t values.

Estimate point process parameters using log-likelihood maximization

Description

Estimate spatio-temporal point process parameters by maximizing the (approximate) full log-likelihood using nloptr.

Usage

estimate_process_parameters(
  data,
  process = c("self_correcting"),
  grids,
  budgets,
  parameter_inits = NULL,
  delta = NULL,
  parallel = FALSE,
  num_cores = max(1L, parallel::detectCores() - 1L),
  set_future_plan = FALSE,
  strategy = c("local", "global_local", "multires_global_local"),
  global_algorithm = "NLOPT_GN_CRS2_LM",
  local_algorithm = "NLOPT_LN_BOBYQA",
  starts = list(global = 1L, local = 1L, jitter_sd = 0.35, seed = 1L),
  finite_bounds = NULL,
  refine_best_delta = TRUE,
  rescore_control = list(enabled = TRUE, top = 5L, objective_tol = 1e-06, param_tol =
    0.1, avoid_bound_solutions = TRUE, bound_eps = 1e-08),
  verbose = TRUE
)

Arguments

Details

For the self-correcting process, arrival times must lie on (0,1) and can be supplied directly in data as time, or constructed from size via the gentle-decay (power-law) mapping power_law_mapping using delta. When delta is a vector, the model is fit for each candidate value and the best objective is selected.

This function supports multi-resolution estimation via a ldmppr_grids schedule. If multiple grid levels are provided, the coarsest level may use a global optimizer followed by local refinement, and subsequent levels run local refinement only.

Value

an object of class "ldmppr_fit" containing the best nloptr fit and (optionally) stored fits from global restarts and/or a delta search.

References

Møller, J., Ghorbani, M., & Rubak, E. (2016). Mechanistic spatio-temporal point process models for marked point processes, with a view to forest stand data. Biometrics, 72(3), 687-696. doi:10.1111/biom.12466.

Examples

# Load example data
data(small_example_data)

# Define grids and budgets
ub <- c(1, 25, 25)
g  <- ldmppr_grids(upper_bounds = ub, levels = list(c(10,10,10)))
b  <- ldmppr_budgets(
  global_options = list(maxeval = 150),
  local_budget_first_level = list(maxeval = 50, xtol_rel = 1e-2),
  local_budget_refinement_levels = list(maxeval = 25, xtol_rel = 1e-2)
)

# Estimate parameters using a single delta value
fit <- estimate_process_parameters(
  data = small_example_data,
  grids = g,
  budgets = b,
  delta = 1,
  strategy = "global_local",
  global_algorithm = "NLOPT_GN_CRS2_LM",
  local_algorithm  = "NLOPT_LN_BOBYQA",
  starts = list(global = 2, local = 2, jitter_sd = 0.25, seed = 1),
  verbose = TRUE
)
coef(fit)
logLik(fit)


# Estimate parameters using multiple delta values (delta search)
g2 <- ldmppr_grids(upper_bounds = ub, levels = list(c(8,8,8), c(12,12,12)))
fit_delta <- estimate_process_parameters(
  data = small_example_data, # x,y,size
  grids = g2,
  budgets = b,
  delta = c(0.35, 0.5, 0.65, 0.9, 1.0),
  parallel = TRUE,
  set_future_plan = TRUE,
  num_cores = 2,
  strategy = "multires_global_local",
  starts = list(local = 1),
  refine_best_delta = FALSE,
  verbose = FALSE
)
plot(fit_delta)

Extract covariate values from a set of rasters

Description

Extract covariate values from a set of rasters

Usage

extract_covars(locations, raster_list)

Arguments

Value

a data.frame of covariates (no ID column; unique names).

Examples

# Load example raster data
raster_paths <- list.files(system.file("extdata", package = "ldmppr"),
  pattern = "\\.tif$", full.names = TRUE
)
raster_paths <- raster_paths[!grepl("_med\\.tif$", raster_paths)]
rasters <- lapply(raster_paths, terra::rast)

# Scale the rasters
scaled_raster_list <- scale_rasters(rasters)

# Load example locations
locations <- small_example_data %>%
  dplyr::select(x, y) %>%
  as.matrix()

# Extract covariates
example_covars <- extract_covars(locations, scaled_raster_list)
head(example_covars)

calculates full product for one grid point

Description

calculates full product for one grid point

Usage

full_product(xgrid, ygrid, tgrid, data, params)

Arguments

Value

returns the product.

Evaluate reference self-correcting log-likelihood

Description

Reference implementation used for parity checks and validation. For production estimation, prefer full_sc_lhood_fast().

Usage

full_sc_lhood(xgrid, ygrid, tgrid, tobs, data, params, bounds)

Arguments

Value

Full self-correcting log-likelihood value.

Evaluate optimized self-correcting log-likelihood

Description

Optimized implementation used by estimation workflows. Intended to be numerically consistent with full_sc_lhood().

Usage

full_sc_lhood_fast(xgrid, ygrid, tgrid, tobs, data, params, bounds)

Arguments

Value

Full self-correcting log-likelihood value.

Generate a marked process given locations and marks

Description

Creates an object of class "ppp" that represents a marked point pattern in the two-dimensional plane.

Usage

generate_mpp(locations, marks = NULL, xy_bounds = NULL)

Arguments

Value

a ppp object with marks.

Examples

# Load example data
data(small_example_data)

# Generate a marked point process
generate_mpp(
  locations = small_example_data %>% dplyr::select(x, y),
  marks = small_example_data$size,
  xy_bounds = c(0, 25, 0, 25)
)

Fast spatio-temporal interaction for the self-correcting model

Description

Computes $g_i = exp(-alpha3 * sum_{j<i} 1[ ||x_i-x_j|| <= beta3 AND (t_i - t_j) >= gamma3 ])$ for i = 1..n, with g_0 = exp(0) = 1.

Usage

interaction_st_fast(data, params)

Arguments

Value

NumericVector length n of exp(-alpha3 * counts)

Internal helpers (not part of the public API)

Description

These functions are used internally by ldmppr and are not intended to be called directly by users.

Usage

new_ldmppr_model_check(
  combined_env,
  envs,
  curve_sets,
  sim_metrics = NULL,
  settings = list(),
  call = NULL
)

new_ldmppr_sim(
  process,
  mpp,
  realization,
  params,
  bounds,
  anchor_point,
  thinning,
  edge_correction,
  include_comp_inds,
  competition_radius,
  call = NULL,
  meta = list()
)

new_ldmppr_mark_model(
  engine,
  fit_engine = NULL,
  xgb_raw = NULL,
  recipe = NULL,
  outcome = "size",
  feature_names = NULL,
  rasters = NULL,
  info = list()
)

new_ldmppr_fit(
  process,
  fit,
  fits = NULL,
  mapping = NULL,
  settings = NULL,
  grid = NULL,
  data_summary = NULL,
  data = NULL,
  data_original = NULL,
  engine = "nloptr",
  call = NULL,
  timing = NULL
)

preprocess_new_data(object, new_data)

rehydrate_xgb(object)

as_mark_model(mark_model)

.build_sc_matrix(data, delta = NULL)

.default_sc_param_bounds(txy, upper_bounds)

a %||% b

.require_pkgs(pkgs)

.coerce_training_df(x, delta = NULL, xy_bounds = NULL)

infer_xy_bounds_from_ppp(ppp)

infer_anchor_from_ppp(ppp)

infer_anchor_from_df(df)

resolve_sc_params(process_fit)

resolve_reference_ppp(reference_data, process_fit, xy_bounds)

.as_sc_params(process_fit)

.infer_xy_bounds(process_fit)

.infer_anchor_point(process_fit)

new_ldmppr_budgets(
  global_options,
  local_budget_first_level,
  local_budget_refinement_levels = NULL
)

is_ldmppr_budgets(x)

as_ldmppr_budgets(x, ...)

.validate_ldmppr_budgets(b)

new_ldmppr_grids(levels, upper_bounds, labels = NULL, include_endpoints = TRUE)

is_ldmppr_grids(x)

as_ldmppr_grids(x, ...)

.validate_ldmppr_grids(g)

.ldmppr_make_grid_schedule(
  upper_bounds,
  levels,
  labels = NULL,
  include_endpoints = TRUE
)

infer_rasters_from_mark_model(mm)

infer_scaled_flag_from_mark_model(mm)

.apply_resid_bootstrap(mu, rb)

.inv_transform(z, transform)

.inv_powerlaw_time_to_size(t, smin, smax, delta)

.build_mark_predictors(
  sim_realization,
  raster_list,
  scaled_rasters,
  xy_bounds,
  include_comp_inds,
  competition_radius,
  edge_correction
)

.predict_marks_legacy(
  sim_realization,
  raster_list,
  scaled_rasters,
  mark_model,
  xy_bounds,
  include_comp_inds,
  competition_radius,
  edge_correction,
  seed = NULL
)

Create an optimization budget specification for estimate_process_parameters()

Description

ldmppr_budgets() defines per-stage optimization options (budgets) used by estimate_process_parameters for NLopt via nloptr.

Usage

ldmppr_budgets(
  global_options = NULL,
  local_budget_first_level = NULL,
  local_budget_refinement_levels = NULL
)

Arguments

Details

The returned object is an S3 class. Use summary() and as.data.frame() methods to inspect.

Value

an object of class "ldmppr_budgets".

See Also

ldmppr_grids-class for methods and details.

Examples

b <- ldmppr_budgets(
  global_options = list(maxeval = 150),
  local_budget_first_level = list(maxeval = 300, xtol_rel = 1e-5),
  local_budget_refinement_levels = list(maxeval = 150, xtol_rel = 1e-5)
)
b

Optimization budget specification object

Description

Objects of class ldmppr_budgets define optimizer budget/options used by estimate_process_parameters.

Usage

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

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

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

## S3 method for class 'ldmppr_budgets'
as.data.frame(x, ...)

## S3 method for class 'ldmppr_budgets'
length(x)

## S3 method for class 'ldmppr_budgets'
x[i, ...]

## S3 method for class 'ldmppr_budgets'
as.list(x, ...)

Arguments

Details

A ldmppr_budgets is a list with (at minimum):

• global_options: list of NLopt options for the global stage (e.g., maxeval, maxtime).

• local_budget_first_level: list of NLopt options for the local stage at the first/coarsest grid level.

• local_budget_refinement_levels: optional list of NLopt options for local refinement levels (used only when estimate_process_parameters(strategy = "multires_global_local")).

Value

print()

prints a brief description of configured budgets.

summary()

returns a summary.ldmppr_budgets.

as.data.frame()

a compact table of the global/local budget entries (when present).

length()

number of available local budget stages (1 or 2).

[ ]

subset local budget stages (keeps global options).

as.list()

returns the underlying list structure.

Functions

• print(ldmppr_budgets): Print a brief summary of optimization budgets.

• summary(ldmppr_budgets): Summarize an optimization budget specification.

• print(summary.ldmppr_budgets): Print a summary produced by summary.ldmppr_budgets().

• as.data.frame(ldmppr_budgets): Convert budgets to a data.frame.

• length(ldmppr_budgets): Number of available local budget stages.

• [: Subset local budget stages (keeps global options).

• as.list(ldmppr_budgets): Extract the underlying list representation.

Fitted point-process model object

Description

Objects of class ldmppr_fit are returned by estimate_process_parameters. They contain the best-fitting optimization result (and optionally multiple fits, e.g. from a delta search) along with metadata used to reproduce the fit.

Usage

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

## S3 method for class 'ldmppr_fit'
coef(object, ...)

## S3 method for class 'ldmppr_fit'
logLik(object, ...)

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

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

## S3 method for class 'ldmppr_fit'
plot(x, ...)

as_nloptr(x, ...)

## S3 method for class 'ldmppr_fit'
as_nloptr(x, ...)

## S3 method for class 'ldmppr_fit'
nobs(object, ...)

## S3 method for class 'ldmppr_fit'
as.data.frame(x, ...)

Arguments

Details

A ldmppr_fit is a list with (at minimum):

• process: process name (e.g. "self_correcting")

• fit: best optimization result (currently an nloptr object)

• mapping: mapping information (e.g. chosen delta, objectives)

• grid: grid definitions used by likelihood approximation

Value

print()

prints a brief summary of the fit.

coef()

returns the estimated parameter vector.

logLik()

returns the log-likelihood at the optimum.

summary()

returns a summary.ldmppr_fit.

plot()

plots diagnostics for multi-fit runs, if available.

Methods (by generic)

• print(ldmppr_fit): Print a brief summary of a fitted model.

• coef(ldmppr_fit): Extract the estimated parameter vector.

• logLik(ldmppr_fit): Log-likelihood at the optimum.

• summary(ldmppr_fit): Summarize a fitted model.

• plot(ldmppr_fit): Plot diagnostics for a fitted model.

• as_nloptr(ldmppr_fit): Extract the underlying nloptr result.

• nobs(ldmppr_fit): Number of observations used in the fitted model.

• as.data.frame(ldmppr_fit): Coerce fit summary to a one-row data frame.

Functions

• print(summary.ldmppr_fit): Print a summary produced by summary.ldmppr_fit.

• as_nloptr(): Extract the underlying nloptr result.

Create a grid schedule for estimate_process_parameters()

Description

ldmppr_grids() constructs a multi-resolution grid schedule used by estimate_process_parameters. The returned object is an S3 class with helper methods; see ldmppr_grids-class.

Usage

ldmppr_grids(upper_bounds, levels, labels = NULL, include_endpoints = TRUE)

Arguments

Value

an object of class "ldmppr_grids".

See Also

ldmppr_grids-class for methods and details.

Examples

# A 3-level coarse-to-fine schedule (counts per dimension)
g <- ldmppr_grids(
  upper_bounds = c(1, 50, 50),
  levels = list(
    c(25, 25, 25),
    c(75, 75, 75),
    c(100, 100, 100)
  )
)
g
length(g)
summary(g)

# Explicit vectors (single level)
g2 <- ldmppr_grids(
  upper_bounds = c(1, 50, 50),
  levels = list(list(
    x = seq(0, 50, by = 2),
    y = seq(0, 50, by = 2),
    t = seq(0, 1,  length.out = 30)
  ))
)
as.data.frame(g2)

Grid schedule object

Description

Objects of class ldmppr_grids define one or more grid "levels" used by estimate_process_parameters. Each level contains numeric vectors x, y, and t defining the approximation grid. Levels are typically ordered from coarse to fine.

Usage

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

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

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

## S3 method for class 'ldmppr_grids'
as.data.frame(x, ...)

## S3 method for class 'ldmppr_grids'
length(x)

## S3 method for class 'ldmppr_grids'
x[i, ...]

## S3 method for class 'ldmppr_grids'
as.list(x, ...)

Arguments

Details

A ldmppr_grids is a list with (at minimum):

• levels: list of levels; each level is a list with x, y, t

• upper_bounds: numeric c(b_t, b_x, b_y)

• labels: optional labels used only for printing

• include_endpoints: logical

Value

print()

prints a brief description of bounds and grid levels.

summary()

returns a summary.ldmppr_grids.

as.data.frame()

returns one row per level with dimensions and ranges.

length()

returns the number of levels.

[ ]

subsets levels, preserving class.

as.list()

returns the underlying list structure.

Functions

• print(ldmppr_grids): Print a brief summary of a grid schedule.

• summary(ldmppr_grids): Summarize a grid schedule.

• print(summary.ldmppr_grids): Print a summary produced by summary.ldmppr_grids().

• as.data.frame(ldmppr_grids): Convert a grid schedule to a data.frame.

• length(ldmppr_grids): Number of levels in a grid schedule.

• [: Subset grid levels.

• as.list(ldmppr_grids): Extract the underlying list representation.

Mark model object

Description

ldmppr_mark_model objects store a fitted mark model and preprocessing information used to predict marks at new locations and times. These objects are typically returned by train_mark_model and can be saved/loaded with save_mark_model and load_mark_model.

Usage

ldmppr_mark_model(
  engine,
  fit_engine = NULL,
  xgb_raw = NULL,
  recipe = NULL,
  outcome = "size",
  feature_names = NULL,
  rasters = NULL,
  info = list()
)

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

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

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

## S3 method for class 'ldmppr_mark_model'
predict(
  object,
  new_data = NULL,
  sim_realization = NULL,
  raster_list = NULL,
  scaled_rasters = FALSE,
  xy_bounds = NULL,
  include_comp_inds = FALSE,
  competition_radius = 15,
  edge_correction = "none",
  seed = NULL,
  ...
)

save_mark_model(object, path, ...)

## S3 method for class 'ldmppr_mark_model'
save_mark_model(object, path, ...)

load_mark_model(path)

Arguments

Details

The model may be backed by different engines (currently "xgboost" and "ranger"). For "xgboost", the object can store a serialized booster payload to make saving/loading robust across R sessions.

Value

print()

prints a brief summary.

predict()

returns numeric predictions for new data.

an object of class "ldmppr_mark_model".

Methods (by generic)

• print(ldmppr_mark_model): Print a brief summary of the mark model.

• summary(ldmppr_mark_model): Summarize a mark model.

• predict(ldmppr_mark_model): Predict marks for new data.

• save_mark_model(ldmppr_mark_model): Save method for ldmppr_mark_model.

Functions

• ldmppr_mark_model(): Create a mark model container.

• print(summary.ldmppr_mark_model): Print a summary produced by summary.ldmppr_mark_model.

• save_mark_model(): Save a mark model to disk.

• load_mark_model(): Load a saved mark model from disk.

Model fit diagnostic object

Description

Objects of class ldmppr_model_check are returned by check_model_fit. They contain global envelope test results and curve sets for multiple summary functions/statistics.

Usage

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

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

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

## S3 method for class 'ldmppr_model_check'
plot(x, which = c("combined", "L", "F", "G", "J", "E", "V"), ...)

Arguments

Details

An ldmppr_model_check is a list with components such as:

• combined_env: a global envelope test object (typically from **GET**)

• envs: named list of envelope test objects (e.g., L, F, G, J, E, V)

• curve_sets: named list of curve set objects

• settings: list of settings used when generating envelopes (e.g., n_sim, thinning)

Value

print()

prints a brief summary of the diagnostic object.

summary()

returns a summary.ldmppr_model_check object.

plot()

plots the combined envelope or a selected statistic envelope.

Methods (by generic)

• print(ldmppr_model_check): Print a brief summary of the diagnostic results.

• summary(ldmppr_model_check): Summarize p-values from the combined and individual envelopes.

• plot(ldmppr_model_check): Plot the combined envelope or a selected statistic.

Functions

• print(summary.ldmppr_model_check): Print a summary produced by summary.ldmppr_model_check.

Simulated marked point process object

Description

ldmppr_sim objects are returned by simulate_mpp. They contain the simulated realization, an associated marked point pattern object, and metadata used to reproduce or inspect the simulation.

Usage

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

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

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

## S3 method for class 'ldmppr_sim'
as.data.frame(x, ...)

## S3 method for class 'ldmppr_sim'
nobs(object, ...)

## S3 method for class 'ldmppr_sim'
plot(x, pattern_type = "simulated", ...)

mpp.ldmppr_sim(x, ...)

Arguments

Details

An ldmppr_sim is a list with at least:

• process: process name (e.g. "self_correcting")

• mpp: a marked point pattern object

• realization: data.frame with columns time, x, y, marks

• params, bounds, and other metadata

Value

For methods:

print()

prints a summary of the simulation.

summary()

returns a summary.ldmppr_sim object.

plot()

returns a ggplot visualization of the marked point pattern.

as.data.frame()

returns the simulated realization as a data.frame.

nobs()

returns the number of points in the realization.

mpp()

returns the marked point pattern object.

Methods (by generic)

• print(ldmppr_sim): Print a brief summary of the simulation.

• summary(ldmppr_sim): Summarize a simulated realization.

• as.data.frame(ldmppr_sim): Coerce to a data.frame of the simulated realization.

• nobs(ldmppr_sim): Number of simulated points.

• plot(ldmppr_sim): Plot the simulated marked point pattern.

Functions

• print(summary.ldmppr_sim): Print a summary produced by summary.ldmppr_sim.

• mpp.ldmppr_sim(): Extract the underlying marked point pattern object.

Medium Example Data

Description

A medium sized example dataset consisting of 111 observations in a (50m x 50m) square domain.

Usage

data("medium_example_data")

Format

## medium_example_data A data frame with 111 rows and 3 columns:

x

x coordinate

y

y coordinate

size

Size

...

Details

The dataset was generated using the Snodgrass dataset available at https://data.ess-dive.lbl.gov/view/doi:10.15485/2476543.

The full code to generate this dataset is available in the package's data_raw directory.

Source

Real example dataset. Code to generate it can be found in data_raw/medium_example_data.R.

calculates part 1-1 full

Description

calculates part 1-1 full

Usage

part_1_1_full(data, params)

Arguments

Value

full likelihood evaluation for part 1.

calculates part 1-2 full

Description

calculates part 1-2 full

Usage

part_1_2_full(data, params)

Arguments

Value

full likelihood evaluation for part 2.

calculates part 1-3

Description

calculates part 1-3

Usage

part_1_3_full(xgrid, ygrid, tgrid, data, params, bounds)

Arguments

Value

full likelihood evaluation for part 3.

calculates part 1-4

Description

calculates part 1-4

Usage

part_1_4_full(data, params)

Arguments

Value

full likelihood evaluation for part 4.

calculates part 1 of the likelihood

Description

calculates part 1 of the likelihood

Usage

part_1_full(xgrid, ygrid, tgrid, data, params, bounds)

Arguments

Value

full evaluation of first part of likelihood.

calculates part 2 of the likelihood

Description

calculates part 2 of the likelihood

Usage

part_2_full(xgrid, ygrid, tgrid, data, params, bounds)

Arguments

Value

full evaluation of second part of likelihood.

Plot a marked point process

Description

Plot a marked point process

Usage

plot_mpp(mpp_data, pattern_type = c("reference", "simulated"))

Arguments

Value

a ggplot object of the marked point process.

Examples

# Load example data
data(small_example_data)
mpp_data <- generate_mpp(
  locations = small_example_data %>% dplyr::select(x, y),
  marks = small_example_data$size,
  xy_bounds = c(0, 25, 0, 25)
)

# Plot the marked point process
plot_mpp(mpp_data, pattern_type = "reference")

Gentle decay (power-law) mapping function from sizes to arrival times

Description

Gentle decay (power-law) mapping function from sizes to arrival times

Usage

power_law_mapping(sizes, delta)

Arguments

Value

vector of arrival times.

Examples

# Generate a vector of sizes
sizes <- runif(100, 0, 100)

# Map the sizes to arrival times using a power-law mapping with delta = .5
power_law_mapping(sizes, .5)

Predict values from the mark distribution

Description

Prefer using the S3 method predict() on an ldmppr_mark_model: predict(mark_model, sim_realization = ..., xy_bounds = ...). This wrapper is retained for backward compatibility and is deprecated.

Usage

predict_marks(
  sim_realization,
  raster_list = NULL,
  scaled_rasters = FALSE,
  mark_model = NULL,
  xy_bounds = NULL,
  include_comp_inds = FALSE,
  competition_radius = 15,
  edge_correction = "none",
  seed = NULL
)

Arguments

Value

a vector of predicted mark values.

Scale a set of rasters

Description

Scale a set of rasters

Usage

scale_rasters(raster_list, reference_resolution = NULL)

Arguments

Value

a list of scaled raster objects.

Examples

# Create two example rasters
rast_a <- terra::rast(
  ncol = 10, nrow = 10,
  xmin = 0, xmax = 10,
  ymin = 0, ymax = 10,
  vals = runif(100)
)

rast_b <- terra::rast(
  ncol = 10, nrow = 10,
  xmin = 0, xmax = 10,
  ymin = 0, ymax = 10,
  vals = runif(100)
)

# Scale example rasters in a list
rast_list <- list(rast_a, rast_b)
scale_rasters(rast_list)

Simulate the spatial component of the self-correcting model (faster)

Description

Simulate the spatial component of the self-correcting model (faster)

Usage

sim_spatial_sc(M_n, params, nsim_t, xy_bounds)

Arguments

Value

a matrix nsim_t x 2 of point locations (x,y).

Simulate the temporal component of the self-correcting model

Description

Simulate the temporal component of the self-correcting model

Usage

sim_temporal_sc(Tmin = 0, Tmax = 1, params = as.numeric(c(0, 0, 0)))

Arguments

Value

a vector of thinned and unthinned temporal samples.

Simulate a realization of a location dependent marked point process

Description

Simulate a realization of a location dependent marked point process

Usage

simulate_mpp(
  process = c("self_correcting"),
  process_fit = NULL,
  t_min = 0,
  t_max = 1,
  anchor_point = NULL,
  raster_list = NULL,
  scaled_rasters = FALSE,
  mark_model = NULL,
  xy_bounds = NULL,
  include_comp_inds = FALSE,
  competition_radius = 15,
  edge_correction = "none",
  thinning = TRUE,
  seed = NULL,
  mark_mode = NULL,
  size_range = NULL,
  delta = NULL
)

Arguments

Value

an object of class "ldmppr_sim".

Examples

# Specify the generating parameters of the self-correcting process
generating_parameters <- c(2, 8, .02, 2.5, 3, 1, 2.5, .2)

# Specify an anchor point
M_n <- c(10, 14)

# Load the raster files
raster_paths <- list.files(system.file("extdata", package = "ldmppr"),
  pattern = "\\.tif$", full.names = TRUE
)
raster_paths <- raster_paths[!grepl("_med\\.tif$", raster_paths)]
rasters <- lapply(raster_paths, terra::rast)

# Scale the rasters
scaled_raster_list <- scale_rasters(rasters)

# Load the example mark model
file_path <- system.file("extdata", "example_mark_model.rds", package = "ldmppr")
mark_model <- load_mark_model(file_path)

# Simulate a realization
example_mpp <- simulate_mpp(
  process = "self_correcting",
  process_fit = generating_parameters,
  t_min = 0,
  t_max = 1,
  anchor_point = M_n,
  raster_list = scaled_raster_list,
  scaled_rasters = TRUE,
  mark_model = mark_model,
  xy_bounds = c(0, 25, 0, 25),
  include_comp_inds = TRUE,
  competition_radius = 10,
  edge_correction = "none",
  thinning = TRUE,
  seed = 90210
)

# Plot the realization and provide a summary
plot(example_mpp, pattern_type = "simulated")
summary(example_mpp)

Simulate from the self-correcting model

Description

Allows the user to simulate a realization from the self-correcting model given a set of parameters and a point to condition on.

Usage

simulate_sc(
  t_min = 0,
  t_max = 1,
  sc_params = NULL,
  anchor_point = NULL,
  xy_bounds = NULL
)

Arguments

Value

a list containing the thinned and unthinned simulation realizations.

Examples

# Specify the generating parameters of the self-correcting process
generating_parameters <- c(2, 8, .02, 2.5, 3, 1, 2.5, .2)

# Specify an anchor point
M_n <- c(10, 14)

# Simulate the self-correcting process
generated_locs <- simulate_sc(
  t_min = 0,
  t_max = 1,
  sc_params = generating_parameters,
  anchor_point = M_n,
  xy_bounds = c(0, 25, 0, 25)
)

Small Example Data

Description

A small example dataset for testing and examples consisting of 121 observations in a (25m x 25m) square domain.

Usage

data("small_example_data")

Format

## small_example_data A data frame with 121 rows and 3 columns:

x

x coordinate

y

y coordinate

size

Size

...

Details

The dataset was generated using the example raster data and an exponential decay size function.

The full code to generate this dataset is available in the package's data_raw directory.

Source

Simulated dataset. Code to generate it can be found in data_raw/small_example_data.R.

calculates spatial interaction

Description

calculates spatial interaction

Usage

spat_interaction(hist, newp, params)

Arguments

Value

calculated probability of new point.

calculates temporal likelihood

Description

calculates temporal likelihood

Usage

temporal_sc(params, eval_t, obs_t)

Arguments

Value

evaluation of full temporal likelihood.

calculates acceptance for thinning mechanism during simulation

Description

calculates acceptance for thinning mechanism during simulation

Usage

thin_st_fast(data, params)

Arguments

Value

LogicalVector length n of whether to keep each point (true) or thin it (false).

Optimized function to compute toroidal distance matrix over a rectangular domain

Description

Optimized function to compute toroidal distance matrix over a rectangular domain

Usage

toroidal_dist_matrix_optimized(location_matrix, x_bound, y_bound)

Arguments

Value

a matrix of toroidal distances.

Examples

# Generate a matrix of locations
location_matrix <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2)
x_bound <- 10
y_bound <- 10

# Compute the toroidal distance matrix
ldmppr:::toroidal_dist_matrix_optimized(location_matrix, x_bound, y_bound)

Train a flexible model for the mark distribution

Description

Trains a predictive model for the mark distribution of a spatio-temporal process. data may be either (1) a data.frame containing columns x, y, size and time, (2) a data.frame containing x, y, size (time will be derived via delta), or (3) a ldmppr_fit object returned by estimate_process_parameters. Allows the user to incorporate location specific information and competition indices as covariates in the mark model.

Usage

train_mark_model(
  data,
  raster_list = NULL,
  scaled_rasters = FALSE,
  model_type = "xgboost",
  xy_bounds = NULL,
  delta = NULL,
  save_model = FALSE,
  save_path = NULL,
  parallel = FALSE,
  num_cores = NULL,
  include_comp_inds = FALSE,
  competition_radius = 15,
  edge_correction = "none",
  selection_metric = "rmse",
  cv_folds = 5,
  tuning_grid_size = 200,
  seed = 0,
  verbose = TRUE
)

Arguments

Value

an object of class "ldmppr_mark_model" containing the trained mark model.

Examples

# Load the small example data
data(small_example_data)

# Load example raster data
raster_paths <- list.files(system.file("extdata", package = "ldmppr"),
  pattern = "\\.tif$", full.names = TRUE
)
raster_paths <- raster_paths[!grepl("_med\\.tif$", raster_paths)]
rasters <- lapply(raster_paths, terra::rast)

# Scale the rasters
scaled_raster_list <- scale_rasters(rasters)


# Train the model
mark_model <- train_mark_model(
  data = small_example_data,
  raster_list = scaled_raster_list,
  scaled_rasters = TRUE,
  model_type = "xgboost",
  xy_bounds = c(0, 25, 0, 25),
  delta = 1,
  parallel = FALSE,
  include_comp_inds = FALSE,
  competition_radius = 10,
  edge_correction = "none",
  selection_metric = "rmse",
  cv_folds = 3,
  tuning_grid_size = 2,
  verbose = TRUE
)

print(mark_model)

calculates euclidean distance

Description

calculates euclidean distance

Usage

vec_dist(x, y)

Arguments

Value

the distance between the two vectors.

calculates euclidean distance between a vector and a matrix

Description

calculates euclidean distance between a vector and a matrix

Usage

vec_to_mat_dist(eval_u, x_col, y_col)

Arguments

Value

a vector of distances between a vector and each row of a matrix.