Skip to contents

Rescales cloglog suitability output from MaxEnt model as an exponential.

Source: R/rescale_cloglog_suitability.R
rescale_cloglog_suitability.Rd

This function will take the cloglog suitability output from MaxEnt, which is on a 0-1 scale, and re-scale it around a set median value. The range of the values will still be 0-1, but the median will now be the value of the thresh parameter. The scaling function is applied as an exponential, for the purposes of visualizing suitability change around a critical threshold (at the scale of 0-1, it can often be hard to see changes across the suitability threshold if its value is very small). THis function will not work correctly if the desired threshold value is 0.

This function and some of its inputs were co-authored by Jacob Woods.

Usage

rescale_cloglog_suitability(
  xy.predicted,
  thresh,
  exponential.file,
  summary.file,
  rescale.name = NA,
  rescale.thresholds = FALSE
)

Arguments

xy.predicted

Data import. A predicted cloglog suitability with longitude and latitude data. This output should be taken from one of the internal package functions: predict_xy_suitability() or predict_xy_suitability_CV(). See details for specifics of formatting.

thresh

Numeric or Character. This may be imported manually (numeric), or may be selected from one of the thresholds for the model (character). See details for a list of preset options and other usages.

exponential.file

Data import. Should be a .csv file or data frame. Contains a comprehensive list of possible threshold values and the corresponding c1, c2 ans c3 values. Where x is equal to the original suitability value and y is equal to the transformed version of that suitability value, these values are used in the exponential function "y = c1 * c2^x + c3".

summary.file

Data import. Should be a .csv file or data frame. Contains preset values for thresholds. If an import, file path should be in the format produced by the file.path() function (i.e. with '/' instead of '\').

For a global or regional model, this will be a file containing summary statistics that is created by one of the following internal package functions: compute_MaxEnt_summary_statistics(), with a filename ending in "_summary.csv", or compute_MaxEnt_summary_statistics_CV(), with a filename ending in "_summary_all_iterations.csv".

For the regional_ensemble model, this file should end in "_threshold_values.csv"

rescale.name

Character. Descriptive name to be given to column of rescaled values.

rescale.thresholds

Logical. If true, the function will also rescale the list of thesholds given in the thresh presets list. All other thresholds are rescaled with reference to the threshold specified by thresh. This is advised if visualizing with multiple thresholds.

Value

Returns the input data frame with an additional column containing the re-scaled exponential values for the cloglog suitability.

If rescale.thresholds = TRUE, will return a list of data frames. The first object in the list will be the rescaled suitability values, and the second object in the list will be the rescaled thresholds.

Details

Requires the following packages: 'tidyverse', 'cli'.

This function is based on an exponential equation of the form:

f(x) = c_1 * c_2^x + c_3

where x is the input suitability value and f(x) is the transformed value of x with respect to thresh as the median of the range. The function calls a reference table to transform the thresh (z) into its respective value f(z) = 0.5 on the exponential scale. The values for the exponential equation were found using the equation:

log((0.5 - c_3) / c1) / log(c_2)

xy.predicted

Fromatting: Should be a data.frame or .csv file. The columns should be in the order: descriptive columns, x (longitude), y (latitude), cloglog suitability (last column). If an import, file path should be in the format produced by the file.path() function (i.e. with '/' instead of '\').

thresh:

Thresh presets list:

  • MTP = Minimum Training Presence

  • MTP.CC = (regional_ensemble model only) Minimum Training Presence, transformed for climate predictions.

  • MTSS = Maximum training sensitivity plus specificity

  • MTSS.CC = (regional_ensemble model only) Maximum training sensitivity plus specificity, transformed for climate predictions.

Examples