whatif.opt: Counterfactual evaluation, optimised for dsmextra

In densitymodelling/dsmextra: A Toolkit for Extrapolation Assessments in Density Surface Models

Description

Implements the methods described in King and Zeng (2007) for evaluating counterfactuals.

Usage

whatif.opt(
  formula = NULL,
  data,
  cfact,
  nearby = 1,
  miss = "list",
  no.partitions,
  verbose = TRUE
)

Arguments

formula	An optional formula without a dependent variable, allowing transformations of combinations of the variables in both data and cfact.
data	Either a model output object, or a n-by-k non-character (logical or numeric) matrix or data frame of observed covariate data with n data points or units and k covariates.
cfact	Counterfactuals.
nearby	Scalar indicating which reference data points are considered to be 'nearby' (i.e. within ‘nearby’ mean geometric Gower's distance of) prediction points.
miss	Optional string indicating the strategy for dealing with missing data.
no.partitions	Integer. Number of desired partitions of the data (default of 10).
verbose	Logical. Show or hide possible warnings and messages.

Details

The whatif function from the Whatif package (Gandrud et al. 2017) may not run on very large datasets. To circumvent this problem, whatif.opt sets the calculations performed by whatif to run on partitions of the data instead, for greater efficiency. whatif.opt can be called internally within compute_nearby by using two additional arguments, namely:

max.size	Threshold above which partitioning will be triggered
no.partitions	Number of required partitions

In practice, a run of compute_nearby begins with a quick assessment of the dimensions of the input data, i.e. the reference and target data.frames. If the product of their dimensions (i.e. number of samples multiplied by number of prediction grid cells) exceeds the value set for max.size, then no.partitions subsets of the data will be created and the computations run on each using map functions from the purrr package (Henry and Wickham 2019). This means that a smaller max.size will trigger partitioning on correspondingly smaller datasets. By default, max.size is set to 1e7. This value was chosen arbitrarily, and should be sufficiently large as to obviate the need for partitioning on most datasets.

Value

A list object containing extrapolation values in both data.frame and raster format.

Author(s)

Phil J. Bouchet

References

Gandrud C, King G, Stoll H, Zeng L (2017). WhatIf: Evaluate Counterfactuals. R package version 1.5-9. https://CRAN.R-project.org/package=WhatIf.

King G, Zeng L (2007). When can history be our guide? The pitfalls of counterfactual inference. International Studies Quarterly 51, 183–210. DOI: 10.1111/j.1468-2478.2007.00445.x

Henry L, Wickham H (2019). purrr: Functional Programming Tools. R package version 0.3.2. https://CRAN.R-project.org/package=purrr.

See Also

compute_nearby

densitymodelling/dsmextra documentation built on Feb. 12, 2022, 4:40 a.m.