| Type: | Package |
| Title: | Mobility Oriented-Parity Metric |
| Version: | 0.1.3 |
| Maintainer: | Marlon E. Cobos <manubio13@gmail.com> |
| Date: | 2025-04-22 |
| Description: | A set of tools to perform multiple versions of the Mobility Oriented-Parity metric. This multivariate analysis helps to characterize levels of dissimilarity between a set of conditions of reference and another set of conditions of interest. If predictive models are transferred to conditions different from those over which models were calibrated (trained), this metric helps to identify transfer conditions that differ substantially from those of calibration. These tools are implemented following principles proposed in Owens et al. (2013) <doi:10.1016/j.ecolmodel.2013.04.011>, and expanded to obtain more detailed results that aid in interpretation as in Cobos et al. (2024) <doi:10.21425/fob.17.132916>. |
| URL: | https://github.com/marlonecobos/mop |
| BugReports: | https://github.com/marlonecobos/mop/issues |
| Imports: | doSNOW (≥ 1.0), foreach (≥ 1.5), methods, parallel, Rcpp,snow (≥ 0.4), stats, terra (≥ 1.6-7), utils |
| License: | GPL (≥ 3) |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Depends: | R (≥ 3.5) |
| LazyData: | true |
| LinkingTo: | Rcpp |
| NeedsCompilation: | yes |
| Packaged: | 2025-04-23 02:25:16 UTC; marlon |
| Author: | Marlon E. Cobos [aut, cre], Hannah L. Owens [aut], Jorge Soberón [aut], A. Townsend Peterson [aut] |
| Repository: | CRAN |
| Date/Publication: | 2025-04-24 11:40:06 UTC |
mop: Mobility Oriented-Parity Metric
Description
mop contains a set of tools to calculate the Mobility Oriented-Paritymetric, which allows a user to compare a set of conditions of referenceversus another set of of interest.
Details
The main goals of the MOP metric are to explore conditions in the set ofinterest that are non-analogous to those in the reference set, and toquantify how different conditions in the set of interest are from thereference set. The tools included here help to identify conditions outsidethe ranges of the reference set with greater detail than in otherimplementations. These tools are based on the methods proposed byOwens et al. (2013;doi:10.1016/j.ecolmodel.2013.04.011).
Functions in mop
mop,mop_distance,out_range,match_na_raster
Data included
reference_matrix,matrix_of_interest,reference_layers,layers_of_interest
Author(s)
Maintainer: Marlon E. Cobosmanubio13@gmail.com (ORCID)
Authors:
Hannah L. Owenshannah.owens@gmail.com (ORCID)
Jorge Soberónjsoberon@ku.edu (ORCID)
A. Townsend Petersontown@ku.edu (ORCID)
See Also
Useful links:
Example of variables for a set of interest
Description
ASpatRaster object representing variables in a set of interest. Variablesrepresent future bioclimatic variables downloaded from the WorldClim database(https://worldclim.org/).
Format
ASpatRaster object.
Value
No return value. Used with functionrast tobring raster variables to analysis.
Examples
layers_of_interest <- terra::rast(system.file("extdata", "layers_of_interest.tif", package = "mop"))terra::plot(layers_of_interest)Match NA cells for all layers in SpatRaster
Description
Option to match cells with NA values in a SpatRaster with multiple layers.
Usage
match_na_raster(layers)Arguments
layers | a |
Value
ASpatRaster object with NA cells matching in all layers.
Examples
# datalayers <- terra::rast(system.file("extdata", "reference_layers.tif", package = "mop"))# add NA in some placeslayers[20:24, 10:16][, 3] <- NAterra::plot(layers)# match NAsmatched <- match_na_raster(layers)terra::plot(matched)Example of matrix with variables in a set of interest
Description
A numeric table representing variables in a set of interest.
Usage
matrix_of_interestFormat
A matrix with 723 rows and 6 columns.
Examples
data("matrix_of_interest", package = "mop")head(matrix_of_interest)Analysis of extrapolation risks using the MOP metric
Description
Analysis to calculate the mobility-oriented parity metric and othersub-products to represent dissimilarities and non-analogous conditionswhen comparing a set of reference conditions (M;m) against anotherset of conditions of interest (G;g).
Usage
mop(m, g, type = "basic", calculate_distance = FALSE, where_distance = "in_range", distance = "euclidean", scale = FALSE, center = FALSE, fix_NA = TRUE, percentage = 1, comp_each = 2000, tol = NULL, rescale_distance = FALSE, parallel = FALSE, n_cores = NULL, progress_bar = TRUE)Arguments
m | a |
g | a |
type |
|
calculate_distance |
|
where_distance |
|
distance |
|
scale | scaling options, |
center |
|
fix_NA |
|
percentage |
|
comp_each |
|
tol | tolerance to detect linear dependencies when calculatingMahalanobis distances. The default, NULL, uses |
rescale_distance |
|
parallel |
|
n_cores |
|
progress_bar |
|
Details
type options return results that differ in the detail of how non-analogousconditions are identified.
basic - makes calculation as proposed by Owens et al. (2013)doi:10.1016/j.ecolmodel.2013.04.011.
simple - calculates how many variables in the set of interest arenon-analogous to those in the reference set.
detailed - calculates five additional extrapolation metrics. See
mop_detailedunderValuebelow for full details.
where_distance options determine what values should be used to calculatedissimilarity
in_range - only conditions inside
mrangesout_range - only conditions outside
mrangesall - all conditions
When the variables used to represent conditions have different units,scaling and centering are recommended. This step is only valid when Euclideandistances are used.
Value
A object of classmop_results containing:
summary - a list with details of the data used in the analysis:
variables - names of variables considered.
type - type of MOP analysis performed.
scale - value according to the argument
scale.center - value according to the argument
center.calculate_distance - value according to the argument
calculate_distance.distance - option regarding distance used.
percentage - percentage of
mused as reference fordistance calculation.rescale_distance - value according to the argument
rescale_distance.fix_NA - value according to the argument
fix_NA.N_m - total number of elements (cells with values or validrows) in
m.N_g - total number of elements (cells with values or validrows) in
g.m_ranges - matrix with ranges of variables in reference conditions(
m).
mop_distances - if
calculate_distance= TRUE, a SpatRaster orvector with distance values for the set of interest (g). Higher valuesrepresent greater dissimilarity compared to the set of reference (m).mop_basic - a SpatRaster or vector, for the set of interest,representing conditions in which at least one of the variables isnon-analogous to the set of reference. Values should be: 1 for non-analogousconditions, and NA for conditions inside the ranges of the reference set.
mop_simple - a SpatRaster or vector, for the set of interest,representing how many variables in the set of interest are non-analogous tothose in the reference set. NA is used for conditions inside the ranges ofthe reference set.
mop_detailed - a list containing:
interpretation_combined - a data.frame to help identify combinationsof variables intowards_low_combined andtowards_high_combined thatare non-analogous to
m.towards_low_end - a SpatRaster or matrix for all variablesrepresenting where non-analogous conditions were found towards low valuesof each variable.
towards_high_end - a SpatRaster or matrix for all variablesrepresenting where non-analogous conditions were found towards highvalues of each variable.
towards_low_combined - a SpatRaster or vector with valuesrepresenting the identity of the variables found to have non-analogousconditions towards low values. If vector, interpretation requires the useof the data.frameinterpretation_combined.
towards_high_combined - a SpatRaster or vector with valuesrepresenting the identity of the variables found to have non-analogousconditions towards high values. If vector, interpretation requires theuse of the data.frameinterpretation_combined.
See Also
Examples
# datareference_layers <- terra::rast(system.file("extdata", "reference_layers.tif", package = "mop"))layers_of_interest <- terra::rast(system.file("extdata", "layers_of_interest.tif", package = "mop"))# analysismop_res <- mop(m = reference_layers, g = layers_of_interest)summary(mop_res)MOP distance calculation
Description
Calculates distances from each of the points of interest ing_matrixto a defined percentage of the reference conditions inm_matrix.
Usage
mop_distance(m_matrix, g_matrix, distance = "euclidean", percentage = 1, comp_each = 2000, tol = NULL, parallel = FALSE, n_cores = NULL, progress_bar = TRUE)Arguments
m_matrix | matrix of variables representing the set of conditions to beused as reference. Each column represents a variable. |
g_matrix | matrix of variables representing the set of conditions to becompared against the reference conditions (where distances are to becalculated). Each column represents a variable. Variable names must matchthose in |
distance |
|
percentage |
|
comp_each |
|
tol | tolerance to detect linear dependencies when calculatingMahalanobis distances. The default, NULL, uses |
parallel |
|
n_cores |
|
progress_bar |
|
Value
A numeric vector with values of distances calculated according toparameters used.
Examples
# datadata("reference_matrix", package = "mop")data("matrix_of_interest", package = "mop")# analysismop_dist <- mop_distance(m_matrix = reference_matrix, g_matrix = matrix_of_interest)Constructor of S3 objects of class mop_results
Description
Constructor of S3 objects of class mop_results
Usage
new_mop_results(summary = new("list"), mop_distances = NULL, mop_basic = NULL, mop_simple = NULL, mop_detailed = new("list"))Arguments
summary | a list with a summary of the data and parameters used inanalysis. Default = empty list. |
mop_distances | a |
mop_basic | a |
mop_simple | a |
mop_detailed | a list with a detailed representation of mop resultsin conditions outside the range of reference. Default = empty list. |
Value
An object of classmop_results.
Detect values outside ranges of reference conditions
Description
Options to identify which values in a set of conditions of interest(g_matrix) are outside the range of a set of conditions ofreference (m_matrix).
Usage
out_range(m_matrix, g_matrix, type = "basic")Arguments
m_matrix | matrix of variables representing the set of conditions to beused as reference. Each column represents a variable. |
g_matrix | matrix of variables representing the set of conditions to becompared against the reference conditions (where conditions outside rangeare to be detected). Each column represents a variable. Variable names mustmatch those in |
type |
|
Details
Results are produced according totype:
basic - helps to identify conditions outside ranges, in general, one orvariables are only counted as
1. This is always returned.simple - identifies the number of variables with conditions outsideranges, for each condition of interest outside ranges, the number ofnon-analogous variables is returned.
detailed - produces various results (including the two above):
high_all - identifies non-analogous conditions towards high values ofvariables, for each variable independently.
low_all - identifies non-analogous conditions towards low values ofvariables, for each variable independently.
high_combined - values are used to identify combinations of variableswith non-analogous conditions towards high values of the variables.
low_combined - values are used to identify combinations of variableswith non-analogous conditions towards low values of the variables.
interpretation - a
data.frameto help identify which variables areconsidered in combined results.
Value
A list containing the ranges inm_matrix, results from analysisaccording totype, and table to help with interpretations. NA valuesrepresent conditions of interest inside ranges of reference conditions.SeeDetails.
Examples
# datadata("reference_matrix", package = "mop")data("matrix_of_interest", package = "mop")# analysisout <- out_range(m_matrix = reference_matrix, g_matrix = matrix_of_interest)Print a short version of elements in mop objects
Description
Print a short version of elements in mop objects
Usage
## S3 method for class 'mop_results'print(x, ...)Arguments
x | object of class mop_results. |
... | further arguments to be passed to or from other methods. Ignoredin this function. |
Value
A short description of objects in the console.
Example of variables for a set of reference
Description
ASpatRaster object representing variables in a set of reference. Variablesrepresent current bioclimatic variables downloaded from the WorldClimdatabase (https://worldclim.org/).
Format
ASpatRaster object.
Value
No return value. Used with functionrast tobring raster variables to analysis.
Examples
reference_layers <- terra::rast(system.file("extdata", "reference_layers.tif", package = "mop"))terra::plot(reference_layers)Example of matrix with variables in a set of reference
Description
A numeric table representing variables in a set of reference.
Usage
reference_matrixFormat
A matrix with 723 rows and 6 columns.
Examples
data("reference_matrix", package = "mop")head(reference_matrix)Summary of attributes and results
Description
Summary of attributes and results
Usage
## S3 method for class 'mop_results'summary(object, ...)Arguments
object | object of class mop_results. |
... | additional arguments affecting the summary produced. Ignored inthis function. |
Value
A printed summary.