Package {DAST}

Extract AGHQ draw blocks for theta and random effects

Description

Extract AGHQ draw blocks for theta and random effects

Usage

aghq_extract_draw_blocks(samps, coef_meta, time_varying_betas)

(Internal) Build combined mesh from a list of sf polygons

Description

Just in case some maps have additional polygons outside the first extent

Usage

build_combined_mesh(polygon_list, mesh_args, make_mesh)

Arguments

Value

An 'inla.mesh' object or 'NULL' if 'make_mesh = FALSE'.

Canonicalize posterior draw parameter names

Description

Canonicalize parameter draw names for consistency across shared vs. time-varying intercepts/slopes while leaving random effects and hyperparameters unchanged.

Usage

canonicalize_draw_names(old_names, coef_meta, time_varying_betas)

Arguments

Value

Character vector of canonicalized draw names.

Compute coefficient metadata (number of timepoints, covariates, and their names)

Description

Compute coefficient metadata (number of timepoints, covariates, and their names)

Usage

compute_coef_meta(data)

Arguments

Fit a multi-map disaggregation model (via AGHQ, TMB, or MCMC)

Description

Top-level fitting wrapper with engine dispatch and engine-specific argument handling. Engine-specific controls should be supplied via engine.args.

Usage

disag_model_mmap(
  data,
  priors = NULL,
  family = "poisson",
  link = "log",
  engine = c("AGHQ", "TMB", "MCMC"),
  time_varying_betas = FALSE,
  fixed_effect_betas = TRUE,
  engine.args = NULL,
  aghq_k = 2,
  field = TRUE,
  iid = TRUE,
  silent = TRUE,
  starting_values = NULL,
  optimizer = NULL,
  verbose = FALSE,
  ...
)

Arguments

Value

A fitted model object of class disag_model_mmap_tmb, disag_model_mmap_aghq, or disag_model_mmap_mcmc (all also inherit disag_model_mmap).

Fit a multi-map disaggregation model via TMB + AGHQ

Description

Builds the TMB ADFun object for a multi-map disaggregation model, then fits the model via AGHQ with desired number of quadrature points.

Usage

disag_model_mmap_aghq(
  data,
  priors = NULL,
  family = "poisson",
  link = "log",
  time_varying_betas = FALSE,
  fixed_effect_betas = TRUE,
  aghq_k = 1,
  field = TRUE,
  iid = TRUE,
  silent = TRUE,
  starting_values = NULL,
  optimizer = NULL,
  outer_derivative_method = "tmb",
  verbose = FALSE
)

Arguments

Value

An object of class 'disag_model_mmap_aghq' (a list with '$aghq_model', '$data', and '$model_setup').

Fit a multi-map disaggregation model via tmbstan MCMC

Description

Builds the shared TMB ADFun object for a multi-map disaggregation model, then samples from it with tmbstan::tmbstan(). This engine supports parameter estimation only; prediction is not implemented for MCMC fits.

Usage

disag_model_mmap_mcmc(
  data,
  priors = NULL,
  family = "poisson",
  link = "log",
  time_varying_betas = FALSE,
  fixed_effect_betas = TRUE,
  chains = 4L,
  iter = 2000L,
  warmup = NULL,
  thin = 1L,
  cores = NULL,
  seed = NULL,
  refresh = NULL,
  laplace = FALSE,
  lower = numeric(0),
  upper = numeric(0),
  control = NULL,
  field = TRUE,
  iid = TRUE,
  silent = TRUE,
  starting_values = NULL,
  verbose = FALSE,
  ...
)

Arguments

Value

An object of class 'disag_model_mmap_mcmc' with components stanfit, obj, data, and model_setup.

Fit a multi-map disaggregation model via TMB

Description

Builds the TMB ADFun object for a multi-map disaggregation model, then fits the model by maximizing the TMB objective and approximates uncertainty via the optimized Hessian.

Usage

disag_model_mmap_tmb(
  data,
  priors = NULL,
  family = "poisson",
  link = "log",
  time_varying_betas = FALSE,
  fixed_effect_betas = TRUE,
  iterations = 1000,
  field = TRUE,
  iid = TRUE,
  hess_control_parscale = NULL,
  hess_control_ndeps = 1e-04,
  outer_derivative_method = "tmb",
  silent = TRUE,
  starting_values = NULL,
  verbose = FALSE
)

Arguments

Value

An object of class 'disag_model_mmap_tmb' (a list with '$obj', '$opt', '$sd_out', '$data', and '$model_setup').

Get categorical levels from a raster layer

Description

Extracts categorical levels from a raster layer, either from defined levels or from unique values in the raster.

Usage

get_categorical_levels(raster_layer)

Arguments

Value

Character vector of level names

Construct design and projection matrices for prediction

Description

Internal helper for 'predict.disag_model_mmap_aghq()'. Builds per-time design matrices (with intercept), the SPDE projection matrix, and the coordinate table for raster reconstruction.

Usage

get_predict_matrices(
  data,
  new_data = NULL,
  expected_cov_names = NULL,
  time_varying_betas = FALSE
)

Arguments

Value

A list with elements: - 'X_list': list of design matrices (each n_cells x p, with "Intercept"). - 'A': SPDE projection matrix (n_cells x n_knots). - 'coords': data.frame of x/y coordinates for each cell.

Get Default Prior Values for Disaggregation Model

Description

Calculates the default Penalized Complexity (PC) prior parameters and Gaussian priors that will be used by disag_model_mmap() if the user does not provide overrides.

Usage

get_priors(data)

Arguments

Details

The default priors are dynamic and depend on the input data:

• Range (Rho): The lower bound prior_rho_min is set to 1/3 of the diagonal length of the study area's bounding box.

• Spatial SD (Sigma): The upper bound prior_sigma_max is set to the coefficient of variation of the polygon response counts.

Value

A named list of prior specifications.

Examples

# Create minimal polygon and covariate inputs for one time point.
polygons <- sf::st_sf(
  area_id = 1:2,
  response = c(10, 12),
  geometry = sf::st_sfc(
    sf::st_polygon(list(rbind(c(0, 0), c(1, 0), c(1, 2), c(0, 2), c(0, 0)))),
    sf::st_polygon(list(rbind(c(1, 0), c(2, 0), c(2, 2), c(1, 2), c(1, 0)))),
    crs = 3857
  )
)
covariate <- terra::rast(
  ncols = 2, nrows = 2, xmin = 0, xmax = 2, ymin = 0, ymax = 2,
  crs = "EPSG:3857"
)
terra::values(covariate) <- c(1, 2, 3, 4)

data <- suppressMessages(prepare_data_mmap(
  polygon_shapefile_list = list(polygons),
  covariate_rasters_list = list(covariate),
  make_mesh = FALSE
))

# Inspect defaults and modify a prior for a later model fit.
defaults <- get_priors(data)
defaults[c("prior_rho_min", "prior_sigma_max")]
my_priors <- defaults
my_priors$prior_rho_prob <- 0.05

Detect if a raster layer is categorical

Description

Determines if a raster layer should be treated as categorical based on multiple criteria: 1. Explicit definition in categorical_covariate_baselines 2. Presence of defined levels in the raster 3. Small number of unique values

Usage

is_categorical_layer(
  raster_layer,
  layer_name,
  categorical_baselines = NULL,
  max_categories = 10
)

Arguments

Value

Logical indicating if the layer should be treated as categorical

Build the TMB ADFun object for multi-map disaggregation

Description

Internal helper. Converts data, priors, and model settings into the list of inputs required by 'TMB::MakeADFun()'.

Usage

make_model_object_mmap(
  data,
  priors = NULL,
  family = "gaussian",
  link = "identity",
  time_varying_betas = FALSE,
  fixed_effect_betas = TRUE,
  field = TRUE,
  iid = TRUE,
  silent = TRUE,
  starting_values = NULL,
  optimizer = NULL,
  verbose = FALSE
)

Arguments

Value

A 'TMB::ADFun' object ready for 'marginal_laplace_tmb()'.

Normalize fixed-effect parameter names

Description

Normalize fixed-effect parameter names to consistent labels.

Usage

normalize_fixed_names(nm, coef_meta, time_varying_betas)

Arguments

Value

Character vector of normalized parameter names.

Convert a TMB parameter vector to a named parameter list using TMB's parList Falls back to slice_params_tmb if parList fails (e.g., shape mismatch)

Description

Convert a TMB parameter vector to a named parameter list using TMB's parList Falls back to slice_params_tmb if parList fails (e.g., shape mismatch)

Usage

parvec_to_param_list(model_output, par_vec)

Visual summary plot of prepared data

Description

Combines polygons, aggregation raster, mesh, and (if present) a covariate into a 2x2 grid.

Usage

## S3 method for class 'disag_data_mmap'
plot(x, y = NULL, ..., covariate = 1, time = 1, max_categories = 10)

Arguments

Value

A ggdraw object (from cowplot) which can be printed.

Plot the offset raster

Description

Draws the aggregation pixel values used in the fit

Usage

plot_aggregation_raster(disag_data, time = 1)

Arguments

Value

A ggplot2 object.

Plot a single covariate raster

Description

Renders one layer of the covariate raster stack, preserving the raster's CRS, and coloring by value with a Viridis scale. Automatically detects and handles categorical covariates with appropriate discrete color scales.

Usage

plot_covariate_raster(disag_data, covariate = 1, time = 1, max_categories = 10)

Arguments

Value

A ggplot2 object.

Plot the SPDE mesh with custom outer/inner boundaries

Description

Plot the SPDE mesh with custom outer/inner boundaries

Usage

plot_mesh(
  disag_data,
  edge_col = "grey70",
  edge_size = 0.2,
  outer_col = "black",
  outer_size = 1,
  inner_col = "blue",
  inner_size = 1,
  node_col = "black",
  node_size = 0.5
)

Arguments

Value

A ggplot2 object.

Plot polygon response data

Description

Draws the prepared polygons colored by the response variable, with an optional title.

Usage

plot_polygons(disag_data, time = 1, show_title = TRUE)

Arguments

Value

A ggplot2 object.

Visual summary plot of prepared data

Description

Combines polygons, aggregation raster, mesh, and (if present) a covariate into a 2x2 grid.

Usage

plot_prepare_summary(disag_data, covariate = 1, time = 1, max_categories = 10)

Arguments

Value

A ggdraw object (from cowplot) which can be printed.

Predict mean & credible intervals for AGHQ-fitted disaggregation model

Description

Given a 'disag_model_mmap_aghq' object, draws from the AGHQ marginal, builds per-cell posterior samples, and returns means and credible-interval rasters.

Usage

## S3 method for class 'disag_model_mmap_aghq'
predict(
  object,
  new_data = NULL,
  predict_iid = FALSE,
  N = 1000,
  CI = 0.95,
  verbose = FALSE,
  ...
)

Arguments

Value

An object of class 'disag_prediction_mmap_aghq' containing: - 'mean_prediction': list of SpatRasters ('prediction', 'field', 'covariates'). - 'uncertainty_prediction': list with 'predictions_ci$lower' & 'upper'.

Prediction guard for MCMC-fitted multi-map disaggregation models

Description

Prediction is intentionally not implemented for MCMC fits. This method provides a clear error directing users to the parameter-estimation outputs.

Usage

## S3 method for class 'disag_model_mmap_mcmc'
predict(object, ...)

Arguments

Value

This function always errors.

Predict for Multi-Map Disaggregation Model fit with TMB

Description

Predict for Multi-Map Disaggregation Model fit with TMB

Usage

## S3 method for class 'disag_model_mmap_tmb'
predict(object, new_data = NULL, predict_iid = FALSE, N = 100, CI = 0.95, ...)

Arguments

Value

An object of class 'disag_prediction_mmap' (also a list) with: - 'mean_prediction': a list containing time-layered 'SpatRaster's named 'time_<time point>': 'prediction' (response-scale mean prediction), 'field' (spatial-field contribution, or 'NULL' when no field was fitted), 'iid' (polygon IID contribution when requested and supported, otherwise 'NULL'), and 'covariates' (covariate-only linear predictor). - 'uncertainty_prediction': a list containing 'realisations', a list of one 'SpatRaster' stack per time point with 'N' Monte Carlo draws, and 'predictions_ci', a list with time-layered 'SpatRaster's 'lower' and 'upper' containing cell-wise credible bounds at level 'CI'.

Predict mean for multi-map disaggregation (TMB)

Description

Given a fitted TMB model object and optional new covariate data, compute the mean-only prediction (no uncertainty) for one raster.

Usage

predict_model_mmap(
  model_output,
  new_data = NULL,
  predict_iid = FALSE,
  newdata = NULL
)

Arguments

Value

A list with components: - prediction: SpatRaster of the mean prediction on the response scale. - field: SpatRaster of the spatial field component (or NULL). - iid: SpatRaster of the IID effect (or NULL). - covariates: SpatRaster of the linear predictor from covariates only.

Predict on a single raster for multi-map disaggregation (TMB)

Description

Apply the linear predictor, add spatial field and IID components, then transform via the link to return a SpatRaster prediction.

Usage

predict_single_raster_mmap(model_parameters, objects, link_function)

Arguments

Value

A list with components: - prediction: SpatRaster on the response scale. - field: SpatRaster of field contribution (or NULL). - iid: SpatRaster of IID contribution (or NULL). - covariates: SpatRaster of the covariate linear predictor.

Estimate uncertainty via Monte Carlo for multi-map disaggregation (TMB)

Description

Draw Monte Carlo samples of model parameters, propagate through the prediction function, and compute credible intervals at each cell.

Usage

predict_uncertainty_mmap(
  model_output,
  new_data = NULL,
  predict_iid = FALSE,
  N = 100,
  CI = 0.95,
  newdata = NULL
)

Arguments

Value

A list with components: - realisations: list of SpatRasters of each draw. - predictions_ci: list with 'lower' and 'upper' SpatRaster stacks.

Prepare multi-map disaggregation data

Description

Given lists of polygon sf's, covariate rasters, and aggregation rasters, combines them into a single 'disag_data_mmap' object ready for model fitting.

Usage

prepare_data_mmap(
  polygon_shapefile_list,
  covariate_rasters_list = NULL,
  aggregation_rasters_list = NULL,
  id_var = "area_id",
  response_var = "response",
  categorical_covariate_baselines = NULL,
  sample_size_var = NULL,
  mesh_args = NULL,
  na_action = FALSE,
  make_mesh = TRUE,
  verbose = FALSE
)

Arguments

Value

An object of class 'disag_data_mmap' with components including - 'polygon_data', 'covariate_data', 'aggregation_pixels', ... - 'categorical_covariate_baselines' (normalized baseline labels) - 'categorical_covariate_schema' (internal encoding schema used for fit/predict consistency)

Process a single time point for prepare_data_mmap()

Description

Internal helper called by 'prepare_data_mmap()'. For time index 't', it: 1. Validates the polygon sf and rasters. 2. Handles NAs in the response. 3. Builds or validates the aggregation raster. 4. Extracts and merges covariate + aggregation pixel data. 5. Computes coordinates for mesh fitting and for prediction. 6. Computes the start/end pixel indices per polygon.

Usage

prepare_time_point(
  t,
  poly_sf,
  cov_rasters,
  agg_raster,
  id_var,
  response_var,
  sample_size_var,
  na_action,
  categorical_schema
)

Arguments

Value

A list with elements: - 'poly_data': data.frame of polygon-level info (incl. 'poly_local_id' & 'time'). - 'cov_data': data.frame of pixel-level covariates + 'poly_local_id' + 'time' + 'cell'. - 'agg_pixels': numeric vector of aggregation weights per pixel. - 'coords_fit': coords for mesh-building (only used pixels). - 'coords_pred': coords for full-extent prediction. - 'start_end_index': integer matrix of 0-indexed start/end for each polygon.

Print method for 'disag_data_mmap' objects

Description

Displays a brief overview of a multi-map disaggregation dataset: number of time points, total polygons, and total pixels.

Usage

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

Arguments

Value

Invisibly returns the original 'disag_data_mmap' object.

Print method for 'disag_model_mmap_aghq' objects

Description

Displays a brief overview of a multi-map disaggregation model: model family, link function, and components included.

Usage

## S3 method for class 'disag_model_mmap_aghq'
print(x, ..., max_print = 30)

Arguments

Value

Invisibly returns the original 'disag_model_mmap_aghq' object.

Print method for 'disag_model_mmap_mcmc' objects

Description

Displays a brief overview of a multi-map disaggregation model fit with the MCMC engine.

Usage

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

Arguments

Value

Invisibly returns the original object.

Print method for 'summary.disag_model_mmap_aghq' objects (direct approach)

Description

Displays the summary information for a multi-map disaggregation model in a well-formatted way, directly using the AGHQ model's summary information.

Usage

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

Arguments

Value

Invisibly returns the original summary object.

Print method for 'summary.disag_model_mmap_mcmc' objects

Description

Displays parameter estimates and MCMC diagnostics for an MCMC-fitted disaggregation model.

Usage

## S3 method for class 'summary.disag_model_mmap_mcmc'
print(x, ..., max_print = 30)

Arguments

Value

Invisibly returns the original summary object.

Rename AGHQ model parameter names

Description

Rename parameter entries in an AGHQ model object (marginals, optimizer outputs, modes, Hessians) using canonicalized names based on coefficient metadata and time-varying structure.

Usage

rename_aghq_model_names(aghq_model, coef_meta, time_varying_betas)

Arguments

Value

AGHQ model object with normalized parameter names in key components.

Prepare prediction objects for multi-map disaggregation (TMB)

Description

Constructs the covariate rasters, field projector, and IID shapefile objects needed by the single-raster prediction routines.

Usage

setup_objects_mmap(
  model_output,
  new_data = NULL,
  predict_iid = FALSE,
  time_index = NULL,
  use_training = FALSE
)

Arguments

Value

A list with elements: - covariates: SpatRaster of covariate layers. - field_objects: list with 'coords' matrix and 'Amatrix' projector (or NULL). - iid_objects: list with 'shapefile' and 'template' (or NULL).

Summary function for disag_data_mmap objects

Description

Prints counts of time points, polygons, pixels, per-time largest/smallest polygon sizes, number of covariates and their summaries and a mesh summary

Usage

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

Arguments

Value

Invisibly returns a list with components: - 'n_times', 'n_polygons', 'n_pixels' - 'per_time': data.frame with 'time', 'min_pixels', 'max_pixels' - 'n_covariates', 'covariate_summaries' (named list of summaries) - 'mesh_nodes', 'mesh_triangles'

Summary method for 'disag_model_mmap_aghq' objects (direct approach)

Description

Creates a simplified summary of a multi-map disaggregation model fit with AGHQ, directly using the AGHQ model's summary information.

Usage

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

Arguments

Value

An object of class 'summary.disag_model_mmap_aghq' containing the summary information.

Summary method for 'disag_model_mmap_mcmc' objects

Description

Summarizes parameter estimates and MCMC diagnostics from the underlying stanfit returned by tmbstan::tmbstan().

Usage

## S3 method for class 'disag_model_mmap_mcmc'
summary(object, pars = NULL, probs = c(0.025, 0.5, 0.975), ...)

Arguments

Value

An object of class 'summary.disag_model_mmap_mcmc'.

Validate inputs to prepare_data_mmap()

Description

Check that all list-arguments are the same length (where required), that required arguments have the correct type, and that 'id_var', 'response_var', and 'sample_size_var' are valid strings.

Usage

validate_prepare_data_inputs(
  polygon_shapefile_list,
  covariate_rasters_list,
  aggregation_rasters_list,
  id_var,
  response_var,
  sample_size_var,
  make_mesh,
  categorical_covariate_baselines = NULL
)

Arguments

Value

Invisibly 'TRUE' if all checks pass; otherwise stops with an error.

Validate covariate layer consistency across time

Description

Validate covariate layer consistency across time

Usage

validate_timevarying_covariates(
  covariate_rasters_list,
  time_varying_betas,
  where = "make_model_object_mmap()"
)

Arguments