R6 class functionality for modeling spatial correlations
within a spatially-explicit model. It provides functionality for calculating
correlations between region cells using a distance-based function:
a*exp(-distance/b), where a (amplitude) and b (breadth) are
configurable model attributes. It then calculates the Cholesky decomposition of
the correlation matrix (via chol), which is utilized to
generate (optionally temporal) correlated normal deviates. A compacted version of
the decomposed matrix can also generated for computational efficiency.
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> SpatialCorrelation
attachedA list of dynamically attached attributes (name-value pairs).
model_attributesA vector of model attribute names.
regionA Region (or inherited class) object specifying the study region.
coordinatesData frame (or matrix) of X-Y population (WGS84) coordinates in longitude (degrees West) and latitude (degrees North) (get and set), or distance-based coordinates dynamically returned by region raster (get only).
distance_scaleScale of distance values in meters (default = 1). Usage: set to 1 for values in meters, or to 1000 for values in kilometers.
correlation_amplitudeCorrelation function: a*exp(-distance/b) a parameter. Represents the amplitude or maximum magnitude of correlation values between model cells.
correlation_breadthCorrelation function: a*exp(-distance/b) b parameter. Represents the breadth of the correlation between region cells. Typically estimated via average distance between correlated region cells.
correlation_matrixCorrelation matrix calculated via correlation function: a*exp(-distance/b).
t_decomposition_matrixThe transposed Cholesky decomposition of the correlation matrix (see chol).
compact_onlyBoolean to indicate that only the compact versions of matrices will be maintained once calculated.
t_decomposition_compact_matrixA compact (rows) version of the transposed Cholesky decomposition of the correlation matrix.
t_decomposition_compact_mapA map of the original region cell rows for the compact transposed decomposition matrix.
attribute_aliasesA list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA vector of warning messages encountered when setting model attributes.
new()Initialization method sets given attributes individually and/or from a list.
SpatialCorrelation$new(compact_only = TRUE, attribute_aliases = NULL, ...)compact_onlyBoolean to indicate that only the compact versions of matrices will be maintained once calculated.
attribute_aliasesOptional list of extra alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
...Parameters passed via a params list or individually.
calculate_distance_matrix()Returns a matrix with the calculated distance (in meters by default) between each pair of region cells.
SpatialCorrelation$calculate_distance_matrix(use_longlat = NULL)use_longlatOptional boolean indicating use of (WGS84) coordinates in longitude (degrees West) and latitude (degrees North).
Matrix with distances between region cells.
calculate_correlations()Calculates the correlation matrix by applying the distance-based correlation function.
SpatialCorrelation$calculate_correlations(
distance_matrix = NULL,
decimals = NULL,
threshold = 1e-07,
...
)distance_matrixOptional pre-calculated matrix with distances between region cells.
decimalsOptional number of decimal places for correlation values.
thresholdOptional threshold (minimum value) for correlation values (default 0.0000001).
...Parameters passed via a params list or individually.
calculate_cholesky_decomposition()Calculates the transposed Cholesky decomposition of the correlation matrix (via chol).
SpatialCorrelation$calculate_cholesky_decomposition(
distance_matrix = NULL,
decimals = NULL,
threshold = 1e-07,
...
)distance_matrixOptional pre-calculated matrix with distances between region cells.
decimalsOptional number of decimal places for correlation values.
thresholdOptional threshold (minimum value) for correlation values (default 0.0000001).
...Parameters passed via a params list or individually.
calculate_compact_decomposition()Compacts the transposed Cholesky decomposition of the correlation matrix into the minimal number of rows, which are mapped to the original matrix.
SpatialCorrelation$calculate_compact_decomposition(distance_matrix = NULL, ...)distance_matrixOptional pre-calculated matrix with distances between region cells.
...Parameters passed via a params list or individually.
get_compact_decomposition()Returns a compact transposed Cholesky decomposition of the correlation matrix and a corresponding map of region cell indices in a list with names: matrix, map.
SpatialCorrelation$get_compact_decomposition(distance_matrix = NULL, ...)distance_matrixOptional pre-calculated matrix with distances between region cells.
...Parameters passed via a params list or individually.
List containing a compact Cholesky decomposition matrix and a corresponding map of region cell indices (for the compacted rows).
generate_correlated_normal_deviates()Generates correlated normal deviates using the spatial correlation, utilizing the optional random seed and optional temporal correlation across time steps.
SpatialCorrelation$generate_correlated_normal_deviates(
random_seed = NULL,
temporal_correlation = 1,
time_steps = 1
)random_seedOptional seed for the random generation of correlated deviates.
temporal_correlationOptional temporal correlation coefficient (0-1; default = 1).
time_stepsOptional number of time steps for temporal correlation (default = 1 or none).
Array (non-temporal) or matrix (temporal) of correlated normal deviates.
clone()The objects of this class are cloneable with this method.
SpatialCorrelation$clone(deep = FALSE)deepWhether to make a deep clone.
# U Island example region
coordinates <- data.frame(
x = rep(seq(177.01, 177.05, 0.01), 5),
y = rep(seq(-18.01, -18.05, -0.01), each = 5)
)
template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent
template_raster[][-c(7, 9, 12, 14, 17:19)] <- NA # make U Island
region <- Region$new(template_raster = template_raster)
# Spatial correlation
env_corr <- SpatialCorrelation$new(region = region, amplitude = 0.4, breadth = 500)
env_corr$calculate_distance_matrix() # m
env_corr$calculate_correlations(decimals = 5)
env_corr$correlation_matrix
env_corr$calculate_cholesky_decomposition(decimals = 2)
env_corr$t_decomposition_matrix
env_corr$get_compact_decomposition()
# Scale to km
env_corr$distance_scale <- 1000
env_corr$calculate_distance_matrix() # km
Run the code above in your browser using DataLab