Package {climniche}

Niche Boundary Exceedance

Description

Niche Boundary Exceedance

Usage

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

Arguments

Value

Numeric vector.

Examples

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
)

Arguments

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
)

Arguments

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))

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, ...)

Arguments

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"]])

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
)

Arguments

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, ...)

Arguments

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 is a within-reference screening rather than a comparison with independent ecological evidence. Supply criterion for the latter use.

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. When the second criterion represents ecological value, maximising a positive Niche Distance Shift identifies cells where high ecological value coincides with movement away from the current niche centre. Minimising Climatic Displacement identifies cells where high ecological value coincides with less local climatic change. The two directions answer different screening questions; neither is a complete conservation ranking.

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)

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
)

Arguments

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)

Build a climniche report

Description

Build a climniche report

Usage

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

Arguments

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
)

Arguments

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"))

Arguments

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"))

Arguments

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
)

Arguments

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"))

Arguments

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

Estimates projected climatic change at each site relative to a fitted current niche reference.

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
)

Arguments

Details

Let current and future climatic conditions at cell i be c_i and f_i. Let \mu be the centre of the current climatic niche reference, and let d_A(x, y) be the climatic distance under weighting matrix A. Climatic Displacement and Niche Distance Shift form the primary geometric pair:

Climatic Displacement:

D_i = d_A(f_i, c_i)

Niche Distance Shift:

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

Climatic Reconfiguration:

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

Niche Boundary Exceedance:

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

where B_q is the q-th weighted quantile of current reference cell distances from the reference centre. Climatic Reconfiguration is derived from Climatic Displacement and Niche Distance Shift. Niche Boundary Exceedance is a separate comparison with the fitted radial boundary.

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)

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
)

Arguments

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, current niche 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
)

Arguments

Details

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

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
)

Arguments

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)

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
)

Arguments

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"))

Arguments

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 percentile shift

Description

Niche percentile shift

Usage

niche_percentile(psi_current, psi_future, occupied)

Arguments

Value

Data frame with current, future, and delta percentiles.

Squared niche distance

Description

Squared niche distance

Usage

niche_potential(x, center, A)

Arguments

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)

Arguments

Value

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

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",
  ...
)

Arguments

Value

Invisibly returns x.

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,
  ...
)

Arguments

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
)

Arguments

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, ...)

Arguments

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)

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"
)

Arguments

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
)

Arguments

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,
  ...
)

Arguments

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, ...)

Arguments

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")
}

Plot a climniche report figure

Description

Plot a climniche report figure

Usage

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

Arguments

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
)

Arguments

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
)

Arguments

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
)

Arguments

Value

A ggplot object.

Print a climniche summary

Description

Prints the four continuous reported quantities.

Usage

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

Arguments

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
)

Arguments

Details

Let A be the fitted weighting matrix and let \mu be the realised niche 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)).

It therefore depends on angular change and current and future niche distances. It is derived from Climatic Displacement and Niche Distance Shift, not fitted as an independent process.

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)

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
)

Arguments

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)

Summarise a climniche fit

Description

Summarise a climniche fit

Usage

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

Arguments

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)

Climatic variable contribution to squared niche distance change

Description

Climatic variable contribution to squared niche distance change

Usage

variable_contribution(current, future, center, A)

Arguments

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)

Arguments

Value

Invisibly returns file.

Write a climniche time series report

Description

Write a climniche time series report

Usage

write_climniche_series_report(report, file)

Arguments

Value

The file path, invisibly.