Package 'climniche' reference manual

Title:	Climate Exposure Relative to a Species' Climatic Niche
Description:	Quantifies climate exposure by comparing projected conditions with the climates associated with a species' current distribution. Location weights define an empirical climatic niche reference, summarised by a weighted centre and radial boundary. The analysis measures local climatic change, movement towards or away from the reference centre, climatic reconfiguration, and distance beyond the boundary. Occurrence records, range maps, and binary or continuous species distribution model outputs can define location weights. Matrix and spatial workflows provide location-level results, distribution-wide summaries, climatic variable contributions and comparisons across future periods.
Authors:	Bohao He [aut, cre]
Maintainer:	Bohao He <[email protected]>
License:	MIT + file LICENSE
Version:	0.3.9
Built:	2026-10-26 12:13:40 UTC
Source:	https://github.com/bohao0813/climniche

Niche Boundary Exceedance

Description

Niche Boundary Exceedance

Usage

boundary_exceedance(
  psi_future,
  boundary_value,
  scale = c("radial", "potential")
)
boundary_exceedance(
  psi_future,
  boundary_value,
  scale = c("radial", "potential")
)

Arguments

psi_future

Future squared niche distance.

boundary_value

Empirical boundary of the current climatic niche reference in squared-distance units.

scale

"radial" returns exceedance beyond the niche boundary distance; "potential" returns exceedance in squared-distance units.

Value

Numeric vector.

Examples

psi <- c(0.5, 1, 2)
boundary_exceedance(psi, boundary_value = 1)
psi <- c(0.5, 1, 2)
boundary_exceedance(psi, boundary_value = 1)

Summarise interval changes in range summaries of Niche Boundary Exceedance

Description

Summarise interval changes in range summaries of Niche Boundary Exceedance

Usage

climniche_change_rate(
  x,
  metric = c("exposed_fraction", "range_wide_relative_exceedance",
    "mean_niche_boundary_exceedance"),
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL
)
climniche_change_rate(
  x,
  metric = c("exposed_fraction", "range_wide_relative_exceedance",
    "mean_niche_boundary_exceedance"),
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL
)

Arguments

x

A climniche_series object.

metric

Range summary used to quantify increase.

scope, aggregation_weight, area_weight, boundary_exceedance_tolerance

Arguments passed to climniche_range_summary().

Details

For a selected range summary $X_t$ , interval rates are

$g_k = \frac{X_{t_{k+1}} - X_{t_k}}{t_{k+1} - t_k}.$

The function reports the largest positive $g_k$ and its interval. Rates should only be compared among analyses using compatible temporal units and projection resolution.

Value

A data frame with one row per model and scenario.

Summarise Niche Boundary Exceedance through time

Description

Summarise Niche Boundary Exceedance through time

Usage

climniche_departure(
  x,
  scope = c("current", "all"),
  persistence = 1L,
  boundary_exceedance_tolerance = NULL
)
climniche_departure(
  x,
  scope = c("current", "all"),
  persistence = 1L,
  boundary_exceedance_tolerance = NULL
)

Arguments

x

A climniche_series object.

scope

"current" for positive reference weights or "all" for every evaluated cell.

persistence

Minimum number of consecutive projections required to identify persistent Niche Boundary Exceedance. This setting affects persistence summaries, not the continuous exceedance values.

boundary_exceedance_tolerance

Optional non-negative boundary tolerance. The fitted value is used by default.

Details

At projection time $t_k$ , let $e_{ik}$ be Niche Boundary Exceedance for cell $i$ , divided by the fitted niche boundary distance after the boundary tolerance is applied. Cumulative relative exceedance is

$J_i = \sum_{k=1}^{K-1} (t_{k+1}-t_k) \frac{e_{ik}+e_{i,k+1}}{2}.$

Mean relative exceedance is $J_i/(t_K-t_1)$ . The Time Weighted Niche Boundary Exceedance Fraction applies the same trapezoidal calculation to the binary exceedance indicator. Numeric, Date and POSIXct times may be irregularly spaced. Cumulative values use the reported time unit; mean values are dimensionless.

Persistent Niche Boundary Exceedance is a run of at least persistence sampled projections above the selected boundary tolerance. Its onset is the first sampled projection in that run, not an estimated crossing time between projections.

Value

A data frame with one row per cell, model and scenario. Primary temporal fields give the first sampled Niche Boundary Exceedance (first_boundary_exceedance) and the fraction of supplied projections beyond the boundary (boundary_exceedance_projection_fraction). Persistent onset and interval-weighted summaries are also returned.

Examples

sim <- simulate_climniche(n = 160, p = 6, seed = 2)
future <- lapply(c(0.2, 0.5, 0.8, 1), function(fraction) {
  sim$current + fraction * (sim$future_away - sim$current)
})
series <- fit_climniche_series(
  sim$current,
  future,
  time = c(2030, 2050, 2070, 2090),
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
head(climniche_departure(series))
sim <- simulate_climniche(n = 160, p = 6, seed = 2)
future <- lapply(c(0.2, 0.5, 0.8, 1), function(fraction) {
  sim$current + fraction * (sim$future_away - sim$current)
})
series <- fit_climniche_series(
  sim$current,
  future,
  time = c(2030, 2050, 2070, 2090),
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
head(climniche_departure(series))

Summarise dominant climatic contributions by cell

Description

Identifies the climate variable with the largest absolute contribution to future minus current squared niche distance at each evaluated cell.

Usage

climniche_dominant_contribution(x, scope = c("current", "all"))

## S3 method for class 'climniche_contribution'
summary(object, ...)
climniche_dominant_contribution(x, scope = c("current", "all"))

## S3 method for class 'climniche_contribution'
summary(object, ...)

Arguments

x

A fitted climniche_fit object.

scope

"current" retains cells with positive current reference weight; "all" retains every evaluated cell.

object

A climniche_contribution object.

...

Additional arguments passed to methods.

Details

Let $V_{ij}$ be the contribution returned by variable_contribution() for cell $i$ and variable $j$ . The dominant variable has the largest $|V_{ij}|$ . Its dominance share is

$H_i = \frac{\max_j |V_{ij}|}{\sum_j |V_{ij}|}.$

The share is undefined when every contribution is zero. Equal largest absolute contributions are reported as "Tied" rather than being assigned according to column order.

Contributions sum exactly to future minus current squared niche distance. This total is also $(r_{1i} - r_{0i})(r_{1i} + r_{0i})$ . The terms therefore attribute the squared-distance change underlying Niche Distance Shift. For a non-diagonal metric matrix, each variable term includes its part of the cross-variable terms in the chosen climatic basis. They are not SDM variable importance or causal effects. Current-scope summaries use the fitted reference weights; all-scope summaries give each evaluated cell equal weight.

Value

A climniche_contribution object. table contains the dominant variable, signed contribution and dominance share for each cell. summary contains mean contribution shares and signed contributions by variable, together with the fraction of non-zero analysis weight for which each variable is uniquely dominant. squared_niche_distance_change is the row sum of the signed variable contributions. The legacy field niche_potential_change is retained as an exact alias. Spatial fits also return raster layers.

Examples

sim <- simulate_climniche(n = 300, p = 6, seed = 31)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
contribution <- climniche_dominant_contribution(fit)
summary(contribution)
head(contribution[["table"]])
sim <- simulate_climniche(n = 300, p = 6, seed = 31)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
contribution <- climniche_dominant_contribution(fit)
summary(contribution)
head(contribution[["table"]])

Summarise agreement among projected climate models

Description

Summarise agreement among projected climate models

Usage

climniche_model_agreement(
  x,
  scope = c("current", "all"),
  boundary_exceedance_tolerance = NULL,
  interval = 0.8
)
climniche_model_agreement(
  x,
  scope = c("current", "all"),
  boundary_exceedance_tolerance = NULL,
  interval = 0.8
)

Arguments

x

A climniche_series object.

scope

"current" or "all".

boundary_exceedance_tolerance

Optional non-negative boundary tolerance.

interval

Central interval reported for Niche Boundary Exceedance across models.

Details

model_agreement is the proportion of supplied climate models with positive Niche Boundary Exceedance. It is an ensemble agreement measure, not an occurrence probability. Agreement is NA when fewer than two finite model projections are available for a cell, time and scenario. For $M$ available models,

$G_{it} = \frac{1}{M}\sum_{m=1}^{M} I(E_{imt} > \tau),$

where $\tau$ is boundary_exceedance_tolerance.

Value

A data frame with one row per cell, time and scenario.

Screen ecological criteria against climate exposure

Description

Screen ecological criteria against climate exposure

Usage

climniche_priority(
  x,
  exposure = c("niche_distance_change", "niche_boundary_exceedance",
    "climate_reconfiguration", "climate_change_amount", "outside_niche_exceedance",
    "composition_change"),
  criterion = NULL,
  criterion_name = NULL,
  criterion_direction = c("maximize", "minimize"),
  scope = c("current", "all"),
  positive_only = NULL,
  exposure_direction = c("maximize", "minimize")
)

## S3 method for class 'climniche_priority'
summary(object, ...)
climniche_priority(
  x,
  exposure = c("niche_distance_change", "niche_boundary_exceedance",
    "climate_reconfiguration", "climate_change_amount", "outside_niche_exceedance",
    "composition_change"),
  criterion = NULL,
  criterion_name = NULL,
  criterion_direction = c("maximize", "minimize"),
  scope = c("current", "all"),
  positive_only = NULL,
  exposure_direction = c("maximize", "minimize")
)

## S3 method for class 'climniche_priority'
summary(object, ...)

Arguments

x

A fitted climniche_fit object.

exposure

Climatic quantity used as the exposure objective. Available choices are "niche_distance_change", "niche_boundary_exceedance", "climate_reconfiguration", and "climate_change_amount". Legacy metric aliases are accepted.

criterion

Optional second decision criterion. A numeric vector may contain one value per evaluated row or, for a spatial fit, one value per raster cell. A matching one-layer RasterLayer or SpatRaster is also accepted. When omitted, current reference weights are used.

criterion_name

Display name for criterion.

criterion_direction

Whether larger or smaller criterion values are preferred.

scope

"current" ranks cells with positive current reference weight; "all" ranks every evaluated cell with finite criteria.

positive_only

If TRUE, only cells with a positive value of the selected exposure quantity are ranked. The default, NULL, uses TRUE when exposure is maximised and FALSE when it is minimised.

exposure_direction

Whether larger or smaller exposure values are preferred in the Pareto comparison. Use "maximize" to screen for greater exposure and "minimize" to screen for lower exposure.

object

A climniche_priority object.

...

Unused.

Details

The function ranks cells on two objectives: the selected climatic exposure quantity and one reference or decision criterion. Cell $i$ dominates cell $k$ when it is at least as preferred on both objectives and strictly preferred on one. Non-dominated cells form Pareto rank 1. Removing that front and repeating the comparison produces ranks 2, 3, and subsequent fronts.

If an analysis contains $K$ Pareto fronts, pareto_depth_score is $(K-r_i)/(K-1)$ for the rank $r_i$ of cell $i$ ; it is 1 when all cells occupy one front. The score does not order cells within a front and is not comparable among separate analyses. Pareto dominance is invariant to monotonic rescaling, so the two criteria are not combined with fitted weights.

When current reference weights are constant, the default second criterion does not distinguish cells and ranking is determined by exposure alone. When the weights vary, the default compares exposure with the current distribution weights. Supply criterion to use another ecological quantity.

Only one exposure quantity is used at a time. This avoids counting Climatic Displacement, Niche Distance Shift and Climatic Reconfiguration as independent objectives even though their values satisfy the fitted geometric identity. With current habitat suitability as the second criterion, preferring higher suitability and larger positive Niche Distance Shift targets potential exposure hotspots. Preferring higher suitability and lower Climatic Displacement guides the search for potential climatic refugia. Locations on the same front can trade a better value of one criterion for a poorer value of the other.

summary() reports the first-front fraction and the Spearman correlation between the preference-oriented forms of the two objectives. These describe how strongly the objectives separate the ranked cells; they are not inferential tests.

Value

A climniche_priority object containing the two decision criteria, Pareto ranks, Pareto depth score (pareto_depth_score) and, for spatial fits, map layers. relative_priority is retained as a compatibility alias for pareto_depth_score.

summary() returns a summary.climniche_priority object with the fitted settings and Pareto diagnostics.

References

Tracey JA, Rochester CJ, Hathaway SA, et al. (2018). Prioritizing conserved areas threatened by wildfire and fragmentation for monitoring and management. PLOS ONE, 13, e0200203. doi:10.1371/journal.pone.0200203

Sacre E, Bode M, Weeks R, Pressey RL (2019). The context dependence of frontier versus wilderness conservation priorities. Conservation Letters, 12, e12632. doi:10.1111/conl.12632

Examples

sim <- simulate_climniche(n = 500, p = 6, seed = 18)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
priority <- climniche_priority(fit)
priority
priority_table <- priority[["table"]]
head(priority_table[priority_table[["included"]], ])
summary(priority)
sim <- simulate_climniche(n = 500, p = 6, seed = 18)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
priority <- climniche_priority(fit)
priority
priority_table <- priority[["table"]]
head(priority_table[priority_table[["included"]], ])
summary(priority)

Summarise Niche Boundary Exceedance across a study domain

Description

Summarise Niche Boundary Exceedance across a study domain

Usage

climniche_range_summary(
  x,
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL
)
climniche_range_summary(
  x,
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL
)

Arguments

x

A climniche_fit or climniche_series object.

scope

"current" restricts the summary to positive reference weights. "all" uses every evaluated cell.

aggregation_weight

Optional non-negative cell weights used only for the range summary. Numeric vectors and, for spatial fits, matching RasterLayer or SpatRaster objects are accepted. These weights multiply the reference weights when scope = "current".

area_weight

If TRUE, multiply the summary weights by raster cell area. This option requires a spatial fit.

boundary_exceedance_tolerance

Optional non-negative tolerance used to identify positive Niche Boundary Exceedance. By default, the fitted descriptor tolerance is used.

Details

Let a_i be the range summary weight, let $\tau$ be the boundary tolerance, and define

$\widetilde{E}_i = E_i I(E_i > \tau), \qquad e_i = \widetilde{E}_i / B_q.$

The Weighted Niche Boundary Exceedance Fraction is

$F = \frac{\sum_i a_i I(e_i > 0)}{\sum_i a_i}.$

Conditional Relative Niche Boundary Exceedance is

$S = \frac{\sum_i a_i e_i I(e_i > 0)} {\sum_i a_i I(e_i > 0)}.$

Range Mean Relative Niche Boundary Exceedance is

$X = \frac{\sum_i a_i e_i I(e_i > 0)}{\sum_i a_i} = F S.$

Here, $I(\cdot)$ is the indicator function. For scope = "current", a_i contains the reference weight. Optional aggregation and cell area weights multiply it. For scope = "all", the reference weight is omitted. These quantities summarise Niche Boundary Exceedance and do not add further cell-level exposure metrics.

Value

A data frame containing Weighted Niche Boundary Exceedance Fraction (exposed_fraction), Conditional Relative Niche Boundary Exceedance (conditional_relative_exceedance) and Range Mean Relative Niche Boundary Exceedance (range_wide_relative_exceedance). For a climniche_series, one row is returned for each time, model and scenario combination.

Examples

sim <- simulate_climniche(n = 250, p = 6, seed = 8)
fit <- fit_climniche(
  sim$current,
  sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_range_summary(fit)
sim <- simulate_climniche(n = 250, p = 6, seed = 8)
fit <- fit_climniche(
  sim$current,
  sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_range_summary(fit)

Build a climniche report

Description

Build a climniche report

Usage

climniche_report(
  x,
  species = NULL,
  scope = c("current", "all"),
  top_variables = 5
)
climniche_report(
  x,
  species = NULL,
  scope = c("current", "all"),
  top_variables = 5
)

Arguments

x

A fitted climniche_fit object.

species

Optional species name used in printed reports.

scope

"current" for current reference cells or "all" for all evaluated cells. Current-scope summaries use reference weights.

top_variables

Number of variable contributions to show.

Value

An object of class climniche_report.

Build a report for a climniche time series

Description

Build a report for a climniche time series

Usage

climniche_series_report(
  x,
  species = NULL,
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL,
  persistence = 1L,
  agreement_interval = 0.8
)
climniche_series_report(
  x,
  species = NULL,
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL,
  persistence = 1L,
  agreement_interval = 0.8
)

Arguments

x

A climniche_series object.

species

Optional species or study label.

scope, aggregation_weight, area_weight, boundary_exceedance_tolerance

Range-summary settings.

persistence

Consecutive projection count used to identify persistent Niche Boundary Exceedance.

agreement_interval

Central interval used for model agreement.

Value

A climniche_series_report object.

Extract a long table from a climniche series

Description

Extract a long table from a climniche series

Usage

climniche_series_table(x, scope = c("current", "all"))
climniche_series_table(x, scope = c("current", "all"))

Arguments

x

A climniche_series object.

scope

"current" for positive reference weights or "all" for all evaluated cells.

Value

A data frame with one row per cell and projection.

Summarise climniche results

Description

Summarise climniche results

Usage

climniche_summary(x, scope = c("current", "all"))
climniche_summary(x, scope = c("current", "all"))

Arguments

x

A fitted climniche_fit object.

scope

"current" for current reference cells or "all" for all evaluated cells. Current-scope summaries use reference weights.

Value

A one-row data frame with summaries of the four continuous reported quantities, descriptor proportions and fitted descriptor thresholds.

Build data for the climniche summary figure

Description

Build data for the climniche summary figure

Usage

climniche_summary_figure_data(
  x,
  scope = c("current", "all"),
  max_points = 6000L,
  seed = 1L,
  plane_bins = 35L,
  boundary_probs = seq(0.5, 0.99, 0.01),
  top_variables = 6L
)
climniche_summary_figure_data(
  x,
  scope = c("current", "all"),
  max_points = 6000L,
  seed = 1L,
  plane_bins = 35L,
  boundary_probs = seq(0.5, 0.99, 0.01),
  top_variables = 6L
)

Arguments

x

A fitted climniche object.

scope

"current" for current reference cells; "all" for all evaluated cells.

max_points

Maximum number of rows retained in the returned plane table. Figure bins are calculated from all cells in the selected scope.

seed

Random seed used when subsampling the returned plane table.

plane_bins

Number of fixed bins used to summarize the exposure plane.

boundary_probs

Boundary quantiles retained in the returned boundary table for downstream inspection.

top_variables

Number of variables to show.

Value

A list of data frames used by plot_climniche_summary_figure().

Extract a tidy climniche table

Description

Extract a tidy climniche table

Usage

climniche_table(x, scope = c("current", "all"))
climniche_table(x, scope = c("current", "all"))

Arguments

x

A fitted climniche_fit object.

scope

"current" for current reference cells or "all" for all evaluated cells.

Value

A data frame with one row per evaluated cell, including occupied_weight, the four reported quantities and the old field aliases.

Fit climate exposure relative to a climatic niche from matrices

Description

Compares the amount of climatic change at each location with movement towards or away from the current reference centre and distance beyond its estimated climatic range.

Usage

fit_climniche(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)
fit_climniche(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

current

Numeric matrix or data frame of current climate values. Rows are cells, sites, or samples. Columns are climate variables.

future

Numeric matrix or data frame of future climate values with the same rows and variables as current. Complete row and variable names are matched before fitting.

occupied

Location weights used to estimate the empirical climatic niche reference. Use NULL to give every row weight 1, a logical vector to mark reference rows, a numeric vector of length nrow(current) for continuous reference weights, or positive integer row indices for 0/1 reference cells. Complete names are matched to the row names of current. With NULL, the reference is the climatic distribution of all current analysis rows.

occupied_threshold

Optional cutoff for numeric reference weights. Values at or below the cutoff are set to 0. Values above it keep their original continuous value.

cnfa

Optional compatible CENFA object. Its mf and sf components can supply the niche centre and diagonal metric weights; metric = "factor" requires co and eig. The object and climatic inputs must use the same variables and standardisation.

center

Optional current niche centre on the scale used for distance calculations. With scale = TRUE, supply a centre in the standardised climatic space. If omitted, the centre is the weighted mean of current reference rows.

sensitivity

Optional non-negative climatic variable weights defining relative contributions to distance. Retained variables receive equal weights by default. These are separate from the location weights in occupied.

A

Optional square metric matrix defined for the fitted climatic space. When supplied, it overrides sensitivity, cnfa, and metric for distance calculations.

metric

Method used to build A when A is missing. "diag" uses variable-level climatic metric weights. "factor" constructs a weighted metric from the co and eig components of a compatible CENFA object.

boundary

Weighted quantile used to define the empirical radial boundary of the empirical climatic niche reference. Must be between 0 and 1.

scale

Logical. If TRUE, current and future values are centred and scaled with the current-layer mean and standard deviation before distances are calculated.

global_mean

Optional means used for centering when scale = TRUE. If omitted, column means of current are used.

global_sd

Optional standard deviations used for scaling. If scale = TRUE and this argument is omitted, column standard deviations of current are used.

preprocess

Logical. If TRUE, remove near-zero variance variables and highly correlated variables before metric fitting.

preprocess_correlation

Maximum absolute pairwise correlation retained among current climate variables during preprocessing.

preprocess_min_sd

Minimum current-climate standard deviation as a fraction of the largest finite current standard deviation. Variables at or below this value are removed during preprocessing.

tolerance

Optional tolerance around zero for Niche Distance Shift. If NULL, the fitted object uses tolerance_quantile.

tolerance_quantile

Quantile of absolute Niche Distance Shift used to set tolerance when tolerance = NULL.

boundary_exceedance_tolerance

Tolerance used to label Niche Boundary Exceedance in descriptor summaries.

Details

The empirical climatic niche reference summarises the current distribution of climatic conditions by a weighted centre and radial boundary. It is a proxy for the species' current climatic niche. With occupied = NULL, it instead describes the study region.

Let $c_i$ and $f_i$ be current and future climatic conditions at location $i$ in the fitted climatic space, $\mu$ the reference centre, and $d_A(x, y)$ the distance under climatic weighting matrix $A$ . The four quantities are:

Climatic Displacement, the amount of local climatic change:

$D_i = d_A(f_i, c_i)$

Niche Distance Shift, the signed change in distance from the centre:

$R_i = d_A(f_i, \mu) - d_A(c_i, \mu)$

Climatic Reconfiguration, the displacement not expressed as a distance shift:

$C_i = \sqrt{\max(0, D_i^2 - R_i^2)}$

Niche Boundary Exceedance, the distance beyond the fitted boundary:

$E_i = \max(0, d_A(f_i, \mu) - B_q)$

Here $B_q$ is the $q$ -th location-weighted quantile of current distances from the centre. Negative Niche Distance Shift indicates movement towards the centre; positive values indicate movement away. When current and future distances are equal, Niche Distance Shift is zero and Climatic Reconfiguration equals Climatic Displacement. Niche Boundary Exceedance is zero at or within the boundary and positive beyond it.

Value

A climniche_fit object containing the reported quantities, reference weights, fitted niche centre, metric matrix and effective settings.

Reported fields

Fitted fields are climate_change_amount, niche_distance_change, climate_reconfiguration, and niche_boundary_exceedance. The legacy names composition_change and outside_niche_exceedance are retained as aliases for old code.

User-settable thresholds

boundary controls the empirical radial boundary. tolerance controls the zero band for Niche Distance Shift. boundary_exceedance_tolerance controls the boundary descriptor. The fitted values are stored in descriptor_settings.

Boundary scale

boundary_distance and boundary_radius store the fitted boundary in distance units. boundary_potential stores its squared value and is the quantity accepted by boundary_exceedance(). boundary_value is retained as a legacy alias of boundary_distance.

Scaling and preprocessing

preprocess selects retained variables. scale then converts those variables to z scores using current-climate means and standard deviations. Both are enabled by default. When fitted CENFA components are used, preprocessing must be disabled because the component dimensions are fixed. Inputs must either already use the CENFA standardisation with scale = FALSE or provide its exact means and standard deviations through global_mean and global_sd. climniche reads the required components from the supplied object and does not call CENFA package functions.

Choosing a fit function

Use fit_climniche() for matrices or data frames, fit_climniche_raster() for RasterLayer, RasterStack or RasterBrick objects, and fit_climniche_terra() for SpatRaster objects. All three functions calculate the same quantities. The spatial functions add domain masking and return map layers in x$rasters. Use fit_climniche_series() for ordered projections.

Examples

sim <- simulate_climniche(n = 250, p = 6, seed = 7)
fit <- fit_climniche(
  current = sim$current,
  future = sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_summary(fit)
sim <- simulate_climniche(n = 250, p = 6, seed = 7)
fit <- fit_climniche(
  current = sim$current,
  future = sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_summary(fit)

Fit climniche to raster data

Description

Fit climniche to raster data

Usage

fit_climniche_raster(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)
fit_climniche_raster(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

current

RasterLayer, RasterStack or RasterBrick object of current climate layers.

future

Matching RasterLayer, RasterStack or RasterBrick object of future climate layers with the same geometry and variables as current. Named layers are matched before fitting.

occupied

Optional RasterLayer with binary or continuous occurrence, range, or SDM suitability values. Continuous values are retained on their supplied numerical scale.

occupied_threshold

Values at or below this threshold receive zero reference weight. Values above it keep their original value.

domain

Optional RasterLayer limiting cells where exposure is analysed.

domain_threshold

Values greater than this threshold define the domain.

cnfa

center

sensitivity

A

Optional square metric matrix defined for the fitted climatic space. When supplied, it overrides sensitivity, cnfa, and metric for distance calculations.

metric

boundary

Weighted quantile used to define the empirical radial boundary of the empirical climatic niche reference. Must be between 0 and 1.

scale

Logical. If TRUE, current and future values are centred and scaled with the current-layer mean and standard deviation before distances are calculated.

global_mean

Optional means used for centering when scale = TRUE. If omitted, column means of current are used.

global_sd

Optional standard deviations used for scaling. If scale = TRUE and this argument is omitted, column standard deviations of current are used.

preprocess

Logical. If TRUE, remove near-zero variance variables and highly correlated variables before metric fitting.

preprocess_correlation

Maximum absolute pairwise correlation retained among current climate variables during preprocessing.

preprocess_min_sd

Minimum current-climate standard deviation as a fraction of the largest finite current standard deviation. Variables at or below this value are removed during preprocessing.

tolerance

Optional tolerance around zero for Niche Distance Shift. If NULL, the fitted object uses tolerance_quantile.

tolerance_quantile

Quantile of absolute Niche Distance Shift used to set tolerance when tolerance = NULL.

boundary_exceedance_tolerance

Tolerance used to label Niche Boundary Exceedance in descriptor summaries.

Details

fit_climniche_raster() is the spatial workflow for users working with the raster package. It fits the current reference from finite current cells within domain, then evaluates cells with finite current and future values. Future missing values therefore do not alter the fitted current reference. Reported quantities are written back to RasterLayer outputs.

Value

An object of class climniche_fit with RasterLayer outputs stored in x$rasters.

Fit a current climatic niche reference

Description

Estimates the preprocessing, standardisation, reference centre, climatic weighting matrix and empirical radial boundary once. The resulting object can be reused with project_climniche() for several future periods or climate models.

Usage

fit_climniche_reference(
  current,
  occupied = NULL,
  occupied_threshold = NULL,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  global_mean = NULL,
  global_sd = NULL
)
fit_climniche_reference(
  current,
  occupied = NULL,
  occupied_threshold = NULL,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  global_mean = NULL,
  global_sd = NULL
)

Arguments

current

Numeric matrix or data frame of current climatic conditions. Rows are cells or sites and columns are climatic variables.

occupied

Reference cells or weights, following the rules used by fit_climniche().

occupied_threshold

Optional cutoff for numeric reference weights.

cnfa

Optional compatible CENFA object.

center

Optional current niche centre in the fitted climatic space.

sensitivity

Optional non-negative climatic metric weights.

A

Optional climatic weighting matrix.

metric

Method used to build A when it is not supplied.

boundary

Weighted quantile defining the empirical radial boundary.

scale

If TRUE, standardise retained variables using current-climate means and standard deviations.

preprocess

If TRUE, remove near-zero variance and highly correlated variables before fitting.

preprocess_correlation

Maximum absolute correlation retained during preprocessing.

preprocess_min_sd

Minimum current-climate standard deviation as a fraction of the largest finite current standard deviation.

global_mean, global_sd

Optional centring and scaling values.

Details

The empirical climatic niche reference summarises current climatic conditions by a location-weighted centre and radial boundary. It is a proxy for the species' current climatic niche. The weights in occupied determine the contribution of locations; sensitivity or A determines the contribution of climatic variables to distance.

The reference object fixes the climatic space used for all subsequent projections. Future conditions do not alter the centre, weighting matrix, standardisation or empirical radial boundary.

Value

A climniche_reference object.

Examples

sim <- simulate_climniche(n = 200, p = 6, seed = 4)
reference <- fit_climniche_reference(
  sim$current,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
reference
sim <- simulate_climniche(n = 200, p = 6, seed = 4)
reference <- fit_climniche_reference(
  sim$current,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
reference

Fit climate exposure through time relative to a fixed climatic niche

Description

Fits one current climatic niche reference and evaluates an ordered set of future projections. Projections may represent time periods, climate models, scenarios, or their combinations.

Usage

fit_climniche_series(
  current,
  future,
  time,
  model = NULL,
  scenario = NULL,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  global_mean = NULL,
  global_sd = NULL,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)
fit_climniche_series(
  current,
  future,
  time,
  model = NULL,
  scenario = NULL,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  global_mean = NULL,
  global_sd = NULL,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

current

Current climatic conditions supplied as a numeric matrix, data frame, RasterLayer, RasterStack, RasterBrick or SpatRaster.

future

A list of future objects matching current. A three-dimensional numeric array may also be supplied, with cells, variables and projections in its three dimensions.

time

Numeric, Date or POSIXct projection times, one per future object.

model

Optional climate model identifiers, one per future object or a single value recycled across projections.

scenario

Optional scenario identifiers, one per future object or a single value recycled across projections.

occupied

Current reference rows, weights or a matching one-layer raster.

occupied_threshold

Optional cutoff for continuous reference weights.

domain

Optional one-layer raster limiting a spatial analysis.

domain_threshold

Threshold used when domain is supplied.

cnfa

Optional compatible CENFA object.

center

Optional current niche centre in the fitted climatic space.

sensitivity

Optional non-negative climatic metric weights.

A

Optional climatic weighting matrix.

metric

Method used to build A when it is not supplied.

boundary

Weighted quantile defining the empirical radial boundary.

scale

If TRUE, standardise retained variables using current climate.

preprocess

If TRUE, screen near-zero variance and highly correlated current-climate variables.

preprocess_correlation

Maximum absolute correlation retained during preprocessing.

preprocess_min_sd

Minimum current-climate standard deviation as a fraction of the largest finite current standard deviation.

global_mean, global_sd

Optional centring and scaling values.

tolerance

Optional tolerance around zero for Niche Distance Shift.

tolerance_quantile

Quantile used when tolerance = NULL.

boundary_exceedance_tolerance

Tolerance used by the empirical boundary descriptor and dynamic summaries.

Details

The current niche centre, climatic weighting matrix, standardisation and empirical radial boundary are held fixed. For spatial inputs, this reference is estimated from finite current cells within domain, independently of missing values in future projections. Future comparisons use the common set of finite cells across all projections. All projections also use one Niche Distance Shift tolerance. When tolerance = NULL, it is the requested quantile of pooled absolute Niche Distance Shift values across the fitted series.

Value

A climniche_series object containing one compatible climniche_fit per projection.

Examples

sim <- simulate_climniche(n = 180, p = 6, seed = 12)
future <- lapply(c(0.25, 0.50, 0.75, 1), function(fraction) {
  sim$current + fraction * (sim$future_away - sim$current)
})
series <- fit_climniche_series(
  current = sim$current,
  future = future,
  time = c(2030, 2050, 2070, 2090),
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_range_summary(series)
sim <- simulate_climniche(n = 180, p = 6, seed = 12)
future <- lapply(c(0.25, 0.50, 0.75, 1), function(fraction) {
  sim$current + fraction * (sim$future_away - sim$current)
})
series <- fit_climniche_series(
  current = sim$current,
  future = future,
  time = c(2030, 2050, 2070, 2090),
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_range_summary(series)

Fit climniche to terra raster data

Description

Fit climniche to terra raster data

Usage

fit_climniche_terra(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)
fit_climniche_terra(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

current

terra SpatRaster of current climate layers.

future

terra SpatRaster of future climate layers with the same geometry and variables as current. Named layers are matched before fitting.

occupied

Optional one layer SpatRaster with binary or continuous occurrence, range, or SDM suitability values. Continuous values are retained on their supplied numerical scale.

occupied_threshold

Values at or below this threshold receive zero reference weight. Values above it keep their original value.

domain

Optional one layer SpatRaster limiting cells where exposure is analysed.

domain_threshold

Values greater than this threshold define the domain.

cnfa

center

sensitivity

A

Optional square metric matrix defined for the fitted climatic space. When supplied, it overrides sensitivity, cnfa, and metric for distance calculations.

metric

boundary

Weighted quantile used to define the empirical radial boundary of the empirical climatic niche reference. Must be between 0 and 1.

scale

Logical. If TRUE, current and future values are centred and scaled with the current-layer mean and standard deviation before distances are calculated.

global_mean

Optional means used for centering when scale = TRUE. If omitted, column means of current are used.

global_sd

Optional standard deviations used for scaling. If scale = TRUE and this argument is omitted, column standard deviations of current are used.

preprocess

Logical. If TRUE, remove near-zero variance variables and highly correlated variables before metric fitting.

preprocess_correlation

Maximum absolute pairwise correlation retained among current climate variables during preprocessing.

preprocess_min_sd

Minimum current-climate standard deviation as a fraction of the largest finite current standard deviation. Variables at or below this value are removed during preprocessing.

tolerance

Optional tolerance around zero for Niche Distance Shift. If NULL, the fitted object uses tolerance_quantile.

tolerance_quantile

Quantile of absolute Niche Distance Shift used to set tolerance when tolerance = NULL.

boundary_exceedance_tolerance

Tolerance used to label Niche Boundary Exceedance in descriptor summaries.

Details

fit_climniche_terra() is the SpatRaster workflow for users working with terra. It fits the current reference from finite current cells within domain, then evaluates cells with finite current and future values. Future missing values therefore do not alter the fitted current reference. Reported quantities are written back to SpatRaster outputs.

Value

An object of class climniche_fit with SpatRaster outputs stored in x$rasters.

Build a climatic weighting metric

Description

Build a climatic weighting metric

Usage

niche_metric(sensitivity = NULL, cnfa = NULL, type = c("diag", "factor"))
niche_metric(sensitivity = NULL, cnfa = NULL, type = c("diag", "factor"))

Arguments

sensitivity

Numeric vector of climatic metric weights used by the diagonal metric. For a factor metric, complete names can be used to order the CENFA loading rows.

cnfa

Optional CENFA cnfa object or compatible list. A diagonal metric can use sf; a factor metric requires co and eig.

type

Metric type. "diag" uses variable-level climatic weights. "factor" uses a factor metric when CENFA factor coordinates are available.

Details

For climatic weights $s_j$ , the diagonal metric is

$A = \mathrm{diag}(s / \bar{s}).$

For a CENFA loading matrix $U$ and factor eigenvalues $\rho$ , the factor metric is

$A = U\,\mathrm{diag}(\rho / \bar{\rho})\,U^{\mathsf{T}}.$

The factor metric is constructed from co and eig; a separate sensitivity vector is not combined with it. This quadratic metric is a climniche construction from CENFA components, not a metric returned by CENFA itself.

The argument name sensitivity is retained for API compatibility. Its values define the relative scale of climatic distance; they are not physiological sensitivity estimates unless supplied from an independent analysis.

Value

A positive semi-definite matrix.

Examples

niche_metric(c(temperature = 2, salinity = 1, oxygen = 0.5))
niche_metric(c(temperature = 2, salinity = 1, oxygen = 0.5))

Niche percentile shift

Description

Niche percentile shift

Usage

niche_percentile(psi_current, psi_future, occupied)
niche_percentile(psi_current, psi_future, occupied)

Arguments

psi_current

Current squared niche distance for all cells.

psi_future

Future squared niche distance for all cells.

occupied

Current reference weights or indices used to define the reference CDF.

Value

Data frame with current, future, and delta percentiles.

Squared niche distance

Description

Squared niche distance

Usage

niche_potential(x, center, A)
niche_potential(x, center, A)

Arguments

x

Climate matrix in the fitted climate space.

center

Current niche reference centre.

A

Niche metric matrix.

Value

Numeric vector of squared distances from the current niche centre in the fitted climatic space.

Niche radius

Description

Niche radius

Usage

niche_radius(psi)
niche_radius(psi)

Arguments

psi

Numeric squared niche distance values.

Value

Numeric vector in the distance units of the fitted climatic metric.

Map Niche Boundary Exceedance through time

Description

Map Niche Boundary Exceedance through time

Usage

plot_climniche_departure_map(
  x,
  metric = c("first_boundary_exceedance", "boundary_exceedance_projection_fraction",
    "first_persistent_departure", "boundary_exceedance_time_fraction",
    "departure_time_fraction", "mean_relative_exceedance", "maximum_relative_exceedance",
    "model_agreement"),
  model = NULL,
  scenario = NULL,
  time = NULL,
  scope = c("current", "all"),
  persistence = 1L,
  boundary_exceedance_tolerance = NULL,
  title = NULL,
  legend_title = FALSE,
  limits = NULL,
  colours = NULL,
  ...
)
plot_climniche_departure_map(
  x,
  metric = c("first_boundary_exceedance", "boundary_exceedance_projection_fraction",
    "first_persistent_departure", "boundary_exceedance_time_fraction",
    "departure_time_fraction", "mean_relative_exceedance", "maximum_relative_exceedance",
    "model_agreement"),
  model = NULL,
  scenario = NULL,
  time = NULL,
  scope = c("current", "all"),
  persistence = 1L,
  boundary_exceedance_tolerance = NULL,
  title = NULL,
  legend_title = FALSE,
  limits = NULL,
  colours = NULL,
  ...
)

Arguments

x

A spatial climniche_series object.

metric

Temporal result field to map. Available fields include first sampled boundary exceedance (first_boundary_exceedance), the fraction of projections beyond the boundary (boundary_exceedance_projection_fraction), persistent exceedance onset, interval-weighted exceedance, relative exceedance and climate model agreement.

model, scenario, time

Optional projection selectors. A selector is required when more than one relevant value is present.

scope, persistence, boundary_exceedance_tolerance

Arguments passed to climniche_departure() or climniche_model_agreement().

title

Optional map title. Use FALSE to suppress it.

legend_title

Optional legend title. The default suppresses a title that would repeat the map title.

limits, colours

Optional colour-scale limits and colours.

...

Additional arguments passed to plot_climniche_map().

Value

A ggplot object.

Plot a climniche reported quantity distribution

Description

Plot a climniche reported quantity distribution

Usage

plot_climniche_distribution(
  x,
  metric = c("niche_distance_change", "climate_change_amount",
    "niche_boundary_exceedance", "climate_reconfiguration", "outside_niche_exceedance",
    "composition_change"),
  scope = c("current", "all"),
  title = NULL
)
plot_climniche_distribution(
  x,
  metric = c("niche_distance_change", "climate_change_amount",
    "niche_boundary_exceedance", "climate_reconfiguration", "outside_niche_exceedance",
    "composition_change"),
  scope = c("current", "all"),
  title = NULL
)

Arguments

x

A fitted climniche object.

metric

Quantity to plot. Accepted values are "climate_change_amount", "niche_distance_change", "climate_reconfiguration", and "niche_boundary_exceedance". Legacy aliases "composition_change" and "outside_niche_exceedance" still work.

scope

"current" for a reference-weighted distribution or "all" for an unweighted distribution across evaluated cells.

title

Optional plot title.

Value

A ggplot object.

Map dominant climatic contributions

Description

Map dominant climatic contributions

Usage

plot_climniche_dominant_contribution(
  x,
  type = c("variable", "share", "both"),
  scope = c("current", "all"),
  variable_labels = NULL,
  colours = NULL,
  title = NULL,
  extent = NULL,
  degree_labels = c("auto", "none", "hemisphere"),
  study_region = NULL,
  legend_position = "bottom",
  legend_variables = NULL
)

## S3 method for class 'climniche_contribution'
plot(x, ...)
plot_climniche_dominant_contribution(
  x,
  type = c("variable", "share", "both"),
  scope = c("current", "all"),
  variable_labels = NULL,
  colours = NULL,
  title = NULL,
  extent = NULL,
  degree_labels = c("auto", "none", "hemisphere"),
  study_region = NULL,
  legend_position = "bottom",
  legend_variables = NULL
)

## S3 method for class 'climniche_contribution'
plot(x, ...)

Arguments

x

A climniche_contribution object or fitted climniche_fit object.

type

Plot the dominant "variable", its "share", or "both".

scope

Scope used when x is a fitted object.

variable_labels

Optional named vector replacing climate variable names.

colours

Optional colours for the climate variables. A final colour may be supplied for tied contributions; otherwise ties are grey.

title

Optional overall title for a combined figure.

extent

Optional c(xmin, xmax, ymin, ymax) map extent.

degree_labels

Longitude-latitude label style.

study_region

Optional study-region boundary accepted by plot_climniche_map().

legend_position

Legend position.

legend_variables

Optional character vector of fitted variable names to retain in the legend, including variables that are not dominant in any mapped cell. The default shows only observed categories.

...

Additional arguments passed to plot_climniche_dominant_contribution() by the S3 plot() method.

Value

A ggplot object, a patchwork object, or a named list when patchwork is unavailable.

Examples

sim <- simulate_climniche(n = 300, p = 6, seed = 32)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
contribution <- climniche_dominant_contribution(fit)
sim <- simulate_climniche(n = 300, p = 6, seed = 32)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
contribution <- climniche_dominant_contribution(fit)

Plot the climniche exposure plane

Description

Plot the climniche exposure plane

Usage

plot_climniche_exposure(
  x,
  scope = c("current", "all"),
  max_points = 6000,
  seed = 1,
  title = NULL,
  colour_by = "niche_boundary_exceedance"
)
plot_climniche_exposure(
  x,
  scope = c("current", "all"),
  max_points = 6000,
  seed = 1,
  title = NULL,
  colour_by = "niche_boundary_exceedance"
)

Arguments

x

A fitted climniche object.

scope

"current" for current reference cells or "all" for all evaluated cells.

max_points

Maximum number of points to draw.

seed

Random seed used when subsampling.

title

Optional plot title.

colour_by

Quantity used for point colour. The current plotting method uses "niche_boundary_exceedance".

Value

A ggplot object.

Plot a climniche map

Description

Plot a climniche map

Usage

plot_climniche_map(
  x,
  metric = c("niche_distance_change", "niche_boundary_exceedance",
    "climate_change_amount", "climate_reconfiguration", "change_alignment",
    "outside_niche_exceedance", "composition_change"),
  occupied = NULL,
  occupied_only = FALSE,
  occupied_threshold = NULL,
  title = NULL,
  midpoint = 0,
  limits = NULL,
  breaks = NULL,
  colours = NULL,
  legend_title = FALSE,
  legend_position = "right",
  show_legend = TRUE,
  symmetric = NULL,
  extent = NULL,
  degree_labels = c("auto", "none", "hemisphere"),
  study_region = NULL,
  region_colour = "black",
  region_linewidth = 0.35,
  region_linetype = 1,
  colour_values = NULL,
  colour_transform = "identity"
)
plot_climniche_map(
  x,
  metric = c("niche_distance_change", "niche_boundary_exceedance",
    "climate_change_amount", "climate_reconfiguration", "change_alignment",
    "outside_niche_exceedance", "composition_change"),
  occupied = NULL,
  occupied_only = FALSE,
  occupied_threshold = NULL,
  title = NULL,
  midpoint = 0,
  limits = NULL,
  breaks = NULL,
  colours = NULL,
  legend_title = FALSE,
  legend_position = "right",
  show_legend = TRUE,
  symmetric = NULL,
  extent = NULL,
  degree_labels = c("auto", "none", "hemisphere"),
  study_region = NULL,
  region_colour = "black",
  region_linewidth = 0.35,
  region_linetype = 1,
  colour_values = NULL,
  colour_transform = "identity"
)

Arguments

x

A fitted climniche object with raster outputs, a RasterLayer, or a terra SpatRaster.

metric

Quantity to plot. Accepted values are "climate_change_amount" for Climatic Displacement, "niche_distance_change" for Niche Distance Shift, "climate_reconfiguration" for Climatic Reconfiguration, "niche_boundary_exceedance" for Niche Boundary Exceedance, and "change_alignment" for the signed ratio used internally. Legacy aliases "composition_change" and "outside_niche_exceedance" still work.

occupied

Optional current reference RasterLayer or terra SpatRaster used for masking or overlaying the current reference distribution.

occupied_only

If TRUE, mask the plotted raster to current occurrence or suitability cells with positive reference weight.

occupied_threshold

Threshold used when occupied contains binary or continuous values. Values above the threshold keep their original value when used as an overlay or mask.

title

Optional plot title. Use FALSE to suppress it.

midpoint

Midpoint for the Niche Distance Shift colour scale.

limits

Optional two-element colour scale limits.

breaks

Optional colour scale breaks.

colours

Optional colour vector replacing the metric palette.

legend_title

Optional colour legend title. The default, FALSE, suppresses a title that would repeat the panel title.

legend_position

Position passed to the ggplot theme. Common values are "right", "bottom", and "none".

show_legend

If FALSE, suppress the colour legend.

symmetric

If TRUE, use limits symmetric around midpoint. If FALSE, the negative and positive colour gradients span their respective limits.

extent

Optional c(xmin, xmax, ymin, ymax) plotting extent.

degree_labels

"auto" uses hemisphere degree labels for longitude-latitude rasters, "hemisphere" always uses them, and "none" uses the default ggplot labels.

study_region

Optional study-region boundary supplied as an sf, sfc, Spatial, SpatVector, or data frame with x and y columns.

region_colour, region_linewidth, region_linetype

Appearance of the optional study-region boundary.

colour_values

Optional positions between zero and one for the colours on the transformed scale.

colour_transform

Colour transformation passed to ggplot2. The default is "identity"; "log1p" can be used for non-negative quantities. Legend labels remain in the original units.

Value

A ggplot object.

Plot the four reported climniche quantities as maps

Description

Plot the four reported climniche quantities as maps

Usage

plot_climniche_maps(
  x,
  metrics = c("climate_change_amount", "niche_distance_change",
    "climate_reconfiguration", "niche_boundary_exceedance"),
  ncol = 2L,
  legend_title = FALSE,
  metric_options = NULL,
  ...
)
plot_climniche_maps(
  x,
  metrics = c("climate_change_amount", "niche_distance_change",
    "climate_reconfiguration", "niche_boundary_exceedance"),
  ncol = 2L,
  legend_title = FALSE,
  metric_options = NULL,
  ...
)

Arguments

x

A fitted climniche_fit object with raster outputs.

metrics

Character vector of reported quantity field names.

ncol

Number of map columns when patchwork is available.

legend_title

Shared legend title. The default suppresses repeated quantity names because each panel is titled.

metric_options

Named list of per-metric options passed to plot_climniche_map(). Entries use metric field names and override shared options in ....

...

Map options passed to plot_climniche_map(). Commonly used arguments are occupied, occupied_only, occupied_threshold, extent, degree_labels, study_region, legend_position, limits, breaks, colours, and show_legend.

Value

A patchwork object when patchwork is installed, otherwise a named list of ggplot objects.

Plot ecological screening of climate exposure

Description

Plot ecological screening of climate exposure

Usage

plot_climniche_priority(
  x,
  type = c("plane", "map", "both"),
  map_value = c("pareto_depth_score", "pareto_rank", "relative_priority"),
  max_points = 6000L,
  seed = 1L,
  title = NULL,
  extent = NULL,
  degree_labels = c("auto", "none", "hemisphere"),
  study_region = NULL,
  legend_position = "bottom"
)

## S3 method for class 'climniche_priority'
plot(x, ...)
plot_climniche_priority(
  x,
  type = c("plane", "map", "both"),
  map_value = c("pareto_depth_score", "pareto_rank", "relative_priority"),
  max_points = 6000L,
  seed = 1L,
  title = NULL,
  extent = NULL,
  degree_labels = c("auto", "none", "hemisphere"),
  study_region = NULL,
  legend_position = "bottom"
)

## S3 method for class 'climniche_priority'
plot(x, ...)

Arguments

x

A climniche_priority object.

type

"plane", "map", or "both".

map_value

Map "pareto_depth_score", the original "pareto_rank", or the legacy alias "relative_priority".

max_points

Target maximum number of cells drawn in the decision plane. Pareto rank 1 is always retained.

seed

Random seed used when the decision plane is subsampled.

title

Optional overall title for a combined figure.

extent

Optional c(xmin, xmax, ymin, ymax) map extent.

degree_labels

Longitude-latitude label style.

study_region

Optional study-region boundary accepted by plot_climniche_map().

legend_position

Legend position for the map.

...

Additional arguments passed to plot_climniche_priority() by the S3 plot() method.

Value

A ggplot object, a patchwork object, or a named list of plots when patchwork is unavailable.

Examples

sim <- simulate_climniche(n = 400, p = 6, seed = 21)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
priority <- climniche_priority(fit)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_climniche_priority(priority, type = "plane")
}
sim <- simulate_climniche(n = 400, p = 6, seed = 21)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
priority <- climniche_priority(fit)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_climniche_priority(priority, type = "plane")
}

Plot a climniche report figure

Description

Plot a climniche report figure

Usage

plot_climniche_report(x, scope = c("current", "all"))
plot_climniche_report(x, scope = c("current", "all"))

Arguments

x

A fitted climniche object.

scope

"current" for current reference cells or "all" for all evaluated cells.

Value

A patchwork object when patchwork is installed, otherwise a named list of ggplot objects.

Plot the climniche summary figure

Description

Plot the climniche summary figure

Usage

plot_climniche_summary_figure(
  x,
  scope = c("current", "all"),
  max_points = 6000L,
  seed = 1L,
  plane_bins = 35L,
  boundary_probs = seq(0.5, 0.99, 0.01),
  top_variables = 6L,
  variable_labels = NULL,
  title = NULL,
  include_contributions = FALSE
)
plot_climniche_summary_figure(
  x,
  scope = c("current", "all"),
  max_points = 6000L,
  seed = 1L,
  plane_bins = 35L,
  boundary_probs = seq(0.5, 0.99, 0.01),
  top_variables = 6L,
  variable_labels = NULL,
  title = NULL,
  include_contributions = FALSE
)

Arguments

x

A fitted climniche object or data returned by climniche_summary_figure_data().

scope

"current" for current reference cells; "all" for all evaluated cells.

max_points

Maximum number of rows retained in the auxiliary plane table. Figure bins use all cells in the selected scope.

seed

Random seed used when subsampling the auxiliary plane table.

plane_bins

Number of fixed bins used to summarize the exposure plane.

boundary_probs

Boundary quantiles retained in the auxiliary figure data.

top_variables

Number of variables to show.

variable_labels

Optional named vector replacing variable labels.

title

Optional overall title when patchwork is installed.

include_contributions

If TRUE, add the variable-contribution panel and use the four-panel layout. The default groups the two joint metric plots with their four metric distributions.

Value

A patchwork object when patchwork is installed, otherwise a named list of ggplot objects.

Plot range summaries of Niche Boundary Exceedance through time

Description

Plot range summaries of Niche Boundary Exceedance through time

Usage

plot_climniche_time(
  x,
  metric = c("range_wide_relative_exceedance", "exposed_fraction",
    "conditional_relative_exceedance", "mean_niche_boundary_exceedance"),
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL,
  interval = 0.8,
  show_models = TRUE,
  title = NULL,
  base_size = 9
)
plot_climniche_time(
  x,
  metric = c("range_wide_relative_exceedance", "exposed_fraction",
    "conditional_relative_exceedance", "mean_niche_boundary_exceedance"),
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL,
  interval = 0.8,
  show_models = TRUE,
  title = NULL,
  base_size = 9
)

Arguments

x

A climniche_series object.

metric

Range summary field to display: exposed_fraction, conditional_relative_exceedance, range_wide_relative_exceedance or mean_niche_boundary_exceedance.

scope, aggregation_weight, area_weight, boundary_exceedance_tolerance

Arguments passed to climniche_range_summary().

interval

Central interval drawn across climate models.

show_models

If TRUE, draw individual climate model lines behind the ensemble median.

title

Optional plot title.

base_size

Base font size.

Value

A ggplot object.

Plot mean climatic variable contribution

Description

Plot mean climatic variable contribution

Usage

plot_climniche_variable_contribution(
  x,
  occupied_only = TRUE,
  variable_labels = NULL,
  title = NULL
)
plot_climniche_variable_contribution(
  x,
  occupied_only = TRUE,
  variable_labels = NULL,
  title = NULL
)

Arguments

x

A climniche_fit object.

occupied_only

If TRUE, summarize occupied cells only.

variable_labels

Optional named vector replacing variable labels.

title

Optional plot title. Use FALSE to suppress it.

Value

A ggplot object.

Plot a fitted climniche quantity

Description

Plot a fitted climniche quantity

Usage

## S3 method for class 'climniche_fit'
plot(
  x,
  type = c("distance", "boundary", "amount", "reconfiguration"),
  scope = c("current", "all"),
  breaks = "Sturges",
  ...
)
## S3 method for class 'climniche_fit'
plot(
  x,
  type = c("distance", "boundary", "amount", "reconfiguration"),
  scope = c("current", "all"),
  breaks = "Sturges",
  ...
)

Arguments

x

A fitted climniche_fit object.

type

Quantity to draw.

scope

"current" for a reference-weighted histogram or "all" for an unweighted histogram across evaluated rows.

breaks

Histogram breaks passed to graphics::hist().

...

Additional arguments passed to the histogram plot.

Value

Invisibly returns x.

Print a climniche summary

Description

Prints the four continuous reported quantities.

Usage

## S3 method for class 'climniche_summary'
print(x, ...)
## S3 method for class 'climniche_summary'
print(x, ...)

Arguments

x

An object returned by climniche_summary().

...

Additional arguments passed to the data-frame print method.

Value

Invisibly returns x.

Project climatic conditions onto a fitted niche reference

Description

Project climatic conditions onto a fitted niche reference

Usage

project_climniche(
  reference,
  future,
  current = NULL,
  occupied = NULL,
  occupied_threshold = NULL,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)
project_climniche(
  reference,
  future,
  current = NULL,
  occupied = NULL,
  occupied_threshold = NULL,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

reference

A climniche_reference object.

future

Numeric matrix or data frame of projected climatic conditions.

current

Optional current climatic conditions for the projected rows. If omitted, the current rows stored in reference are used.

occupied

Optional reference weights for summaries of the projected rows. When current is omitted, the fitted reference weights are reused. With a supplied current, named rows are matched to the reference; otherwise projected rows receive equal weight.

occupied_threshold

Optional cutoff for numeric occupied weights.

tolerance

Optional tolerance around zero for Niche Distance Shift.

tolerance_quantile

Quantile of absolute Niche Distance Shift used when tolerance = NULL.

boundary_exceedance_tolerance

Non-negative tolerance used by the boundary status descriptor.

Details

Let $A$ be the climatic weighting matrix and $\mu$ the fitted reference centre. In the transformed climatic space, write the current and future centred vectors as $z_0$ and $z_1$ , with lengths $r_0$ and $r_1$ . When both lengths are positive, let $\theta$ be the angle between those vectors. Climatic Reconfiguration satisfies

$C_i^2 = 2 r_{0i} r_{1i} (1 - \cos(\theta_i)).$

Different climatic combinations can have the same distance from the centre. In that case Niche Distance Shift is zero and Climatic Reconfiguration equals Climatic Displacement.

Value

A climniche_fit object using the fixed reference.

Examples

sim <- simulate_climniche(n = 200, p = 6, seed = 4)
reference <- fit_climniche_reference(
  sim$current,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
fit <- project_climniche(reference, sim$future_away)
climniche_summary(fit)
sim <- simulate_climniche(n = 200, p = 6, seed = 4)
reference <- fit_climniche_reference(
  sim$current,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
fit <- project_climniche(reference, sim$future_away)
climniche_summary(fit)

Simulate a minimal climatic niche exposure example

Description

Simulate a minimal climatic niche exposure example

Usage

simulate_climniche(
  n = 2000,
  p = 6,
  seed = 1,
  rho = 0,
  prevalence = 0.3,
  shift = 0.4
)
simulate_climniche(
  n = 2000,
  p = 6,
  seed = 1,
  rho = 0,
  prevalence = 0.3,
  shift = 0.4
)

Arguments

n

Number of climate cells.

p

Number of climate variables.

seed

Random seed.

rho

Pairwise correlation among simulated climate variables.

prevalence

Proportion of background cells treated as true current occurrence locations under the virtual niche.

shift

Climatic Displacement imposed in the closer to niche and farther from niche scenarios.

Value

A list with current, future_toward, future_away, occupied, center, sensitivity and A.

Examples

sim <- simulate_climniche(n = 200, p = 6, seed = 7)
dim(sim$current)
mean(sim$occupied)
sim <- simulate_climniche(n = 200, p = 6, seed = 7)
dim(sim$current)
mean(sim$occupied)

Summarise a climniche fit

Description

Summarise a climniche fit

Usage

## S3 method for class 'climniche_fit'
summary(object, scope = c("current", "all"), ...)
## S3 method for class 'climniche_fit'
summary(object, scope = c("current", "all"), ...)

Arguments

object

A fitted climniche_fit object.

scope

"current" for a reference-weighted summary or "all" for an unweighted summary across all evaluated rows.

...

Unused.

Value

A summary.climniche_fit object.

Examples

sim <- simulate_climniche(n = 200, p = 6, seed = 5)
fit <- fit_climniche(
  sim$current,
  sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
summary(fit)
sim <- simulate_climniche(n = 200, p = 6, seed = 5)
fit <- fit_climniche(
  sim$current,
  sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
summary(fit)

Climatic variable contribution to squared niche distance change

Description

Climatic variable contribution to squared niche distance change

Usage

variable_contribution(current, future, center, A)
variable_contribution(current, future, center, A)

Arguments

current

Current climate matrix in the fitted climate space.

future

Future climate matrix in the fitted climate space.

center

Current niche reference centre.

A

Niche metric matrix.

Details

For centred current and future climatic vectors $z_{0i}$ and $z_{1i}$ , the contribution of variable $j$ is

$V_{ij} = z_{1ij}(A z_{1i})_j - z_{0ij}(A z_{0i})_j.$

Consequently,

$\sum_j V_{ij} = \psi_{1i} - \psi_{0i} = (r_{1i} - r_{0i})(r_{1i} + r_{0i}),$

where $r_{0i}$ and $r_{1i}$ are current and future niche distances. These values therefore decompose the squared-distance change underlying Niche Distance Shift. They are not SDM variable importance or causal effects.

Value

Matrix whose rows sum to future minus current squared niche distance.

Write a climniche report to Markdown

Description

Write a climniche report to Markdown

Usage

write_climniche_report(report, file)
write_climniche_report(report, file)

Arguments

report

An object returned by climniche_report().

file

Output Markdown file.

Value

Invisibly returns file.

Write a climniche time series report

Description

Write a climniche time series report

Usage

write_climniche_series_report(report, file)
write_climniche_series_report(report, file)

Arguments

report

A climniche_series_report object.

file

Output Markdown file.

Value

The file path, invisibly.

Package 'climniche'

Help Index

Niche Boundary Exceedance

Description

Usage

Arguments

Value

Examples

Summarise interval changes in range summaries of Niche Boundary Exceedance

Description

Usage

Arguments

Details

Value

Summarise Niche Boundary Exceedance through time

Description

Usage

Arguments

Details

Value

Examples

Summarise dominant climatic contributions by cell

Description

Usage

Arguments

Details

Value

Examples

Summarise agreement among projected climate models

Description

Usage

Arguments

Details

Value

Screen ecological criteria against climate exposure

Description

Usage

Arguments

Details

Value

References

Examples

Summarise Niche Boundary Exceedance across a study domain

Description

Usage

Arguments

Details

Value

Examples

Build a climniche report

Description

Usage

Arguments

Value

Build a report for a climniche time series

Description

Usage

Arguments

Value

Extract a long table from a climniche series

Description

Usage

Arguments

Value

Summarise climniche results

Description

Usage

Arguments

Value

Build data for the climniche summary figure

Description

Usage

Arguments

Value

Extract a tidy climniche table

Description

Usage

Arguments

Value

Fit climate exposure relative to a climatic niche from matrices