SpatialCorrelation: R6 class representing a spatial correlation.
In poems: Pattern-Oriented Ensemble Modeling System
SpatialCorrelation R Documentation
R6 class representing a spatial correlation.
Description
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.
Super classes
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> SpatialCorrelation
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
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.
Methods
Public methods
-
-
-
-
-
-
-
-
Inherited methods
Method new()
Initialization method sets given attributes individually and/or from a list.
Usage
SpatialCorrelation$new(compact_only = TRUE, attribute_aliases = NULL, ...)
Arguments
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.
Method calculate_distance_matrix()
Returns a matrix with the calculated distance (in meters by default) between each pair of region cells.
Usage
SpatialCorrelation$calculate_distance_matrix(use_longlat = NULL)
Arguments
use_longlatOptional boolean indicating use of (WGS84) coordinates in longitude (degrees West) and latitude (degrees North).
Returns
Matrix with distances between region cells.
Method calculate_correlations()
Calculates the correlation matrix by applying the distance-based correlation function.
Usage
SpatialCorrelation$calculate_correlations(
distance_matrix = NULL,
decimals = NULL,
threshold = 1e-07,
...
)
Arguments
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.
Method calculate_cholesky_decomposition()
Calculates the transposed Cholesky decomposition of the correlation matrix (via chol).
Usage
SpatialCorrelation$calculate_cholesky_decomposition(
distance_matrix = NULL,
decimals = NULL,
threshold = 1e-07,
...
)
Arguments
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.
Method 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.
Usage
SpatialCorrelation$calculate_compact_decomposition(distance_matrix = NULL, ...)
Arguments
distance_matrixOptional pre-calculated matrix with distances between region cells.
...Parameters passed via a params list or individually.
Method 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.
Usage
SpatialCorrelation$get_compact_decomposition(distance_matrix = NULL, ...)
Arguments
distance_matrixOptional pre-calculated matrix with distances between region cells.
...Parameters passed via a params list or individually.
Returns
List containing a compact Cholesky decomposition matrix and a corresponding map of region cell indices (for the compacted rows).
Method generate_correlated_normal_deviates()
Generates correlated normal deviates using the spatial correlation, utilizing the optional random seed and optional temporal correlation across time steps.
Usage
SpatialCorrelation$generate_correlated_normal_deviates(
random_seed = NULL,
temporal_correlation = 1,
time_steps = 1
)
Arguments
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).
Returns
Array (non-temporal) or matrix (temporal) of correlated normal deviates.
Method clone()
The objects of this class are cloneable with this method.
Usage
SpatialCorrelation$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
# 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
poems documentation built on Oct. 7, 2023, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| SpatialCorrelation | R Documentation |
R6 class representing a spatial correlation.
Description
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.
Super classes
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> SpatialCorrelation
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
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.
Methods
Public methods
Inherited methods
Method new()
Initialization method sets given attributes individually and/or from a list.
Usage
SpatialCorrelation$new(compact_only = TRUE, attribute_aliases = NULL, ...)
Arguments
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.
Method calculate_distance_matrix()
Returns a matrix with the calculated distance (in meters by default) between each pair of region cells.
Usage
SpatialCorrelation$calculate_distance_matrix(use_longlat = NULL)
Arguments
use_longlatOptional boolean indicating use of (WGS84) coordinates in longitude (degrees West) and latitude (degrees North).
Returns
Matrix with distances between region cells.
Method calculate_correlations()
Calculates the correlation matrix by applying the distance-based correlation function.
Usage
SpatialCorrelation$calculate_correlations( distance_matrix = NULL, decimals = NULL, threshold = 1e-07, ... )
Arguments
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.
Method calculate_cholesky_decomposition()
Calculates the transposed Cholesky decomposition of the correlation matrix (via chol).
Usage
SpatialCorrelation$calculate_cholesky_decomposition( distance_matrix = NULL, decimals = NULL, threshold = 1e-07, ... )
Arguments
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.
Method 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.
Usage
SpatialCorrelation$calculate_compact_decomposition(distance_matrix = NULL, ...)
Arguments
distance_matrixOptional pre-calculated matrix with distances between region cells.
...Parameters passed via a params list or individually.
Method 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.
Usage
SpatialCorrelation$get_compact_decomposition(distance_matrix = NULL, ...)
Arguments
distance_matrixOptional pre-calculated matrix with distances between region cells.
...Parameters passed via a params list or individually.
Returns
List containing a compact Cholesky decomposition matrix and a corresponding map of region cell indices (for the compacted rows).
Method generate_correlated_normal_deviates()
Generates correlated normal deviates using the spatial correlation, utilizing the optional random seed and optional temporal correlation across time steps.
Usage
SpatialCorrelation$generate_correlated_normal_deviates( random_seed = NULL, temporal_correlation = 1, time_steps = 1 )
Arguments
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).
Returns
Array (non-temporal) or matrix (temporal) of correlated normal deviates.
Method clone()
The objects of this class are cloneable with this method.
Usage
SpatialCorrelation$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
# 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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.