Package 'climniche'

Title: Niche Climate Exposure
Description: Assesses niche climate exposure by interpreting projected climate change relative to the climate conditions a species currently occupies. Using occurrence records, range data, continuous species distribution model suitability maps, current environmental rasters and future projections, the package separates Climatic Displacement, Niche Distance Shift, Climatic Reconfiguration and Niche Boundary Exceedance.
Authors: Bohao He [aut, cre]
Maintainer: Bohao He <[email protected]>
License: GPL (>= 3)
Version: 0.2.0
Built: 2026-06-02 10:22:11 UTC
Source: https://github.com/bohao0813/climniche

Help Index

Niche Boundary Exceedance

Description

Niche Boundary Exceedance

Usage

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

Arguments

psi_future

Future niche potential.
boundary_value

Empirical boundary of the current realised niche in potential units.
scale

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

Value

Numeric vector.

Build data for a niche climate exposure diagram

Description

Build data for a niche climate exposure diagram

Usage

climniche_diagram_data(
  x,
  scope = c("current", "all"),
  max_arrows = 350L,
  seed = 1L
)

Arguments

x

A fitted climniche object.
scope

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

Maximum number of current to future arrows to keep.
seed

Random seed used when subsampling arrows.

Value

A list of data frames used by plot_climniche_diagram().

Build a climniche report

Description

Build a climniche report

Usage

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 data for the climniche summary figure

Description

Build data for the climniche summary figure

Usage

climniche_showcase_data(
  x,
  scope = c("current", "all"),
  max_points = 6000L,
  seed = 1L,
  plane_bins = 45L,
  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 cells to keep for the exposure plane.
seed

Random seed used when subsampling cells.
plane_bins

Number of fixed bins used to summarize the exposure plane.
boundary_probs

Boundary quantiles used for the sensitivity curve.
top_variables

Number of variables to show.

Value

A list of data frames used by plot_climniche_showcase().

Summarise climniche results

Description

Summarise climniche results

Usage

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 metric summaries and the effective classification settings.

Extract a tidy climniche table

Description

Extract a tidy climniche table

Usage

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 primary metrics and the old metric aliases.

Fit niche climate exposure

Description

Fit niche climate exposure

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,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  stable_climate_change = NULL,
  stable_quantile = 0.25,
  stable_reconfiguration = NULL,
  stable_reconfiguration_quantile = 0.25,
  boundary_exceedance_tolerance = 0,
  conflict_ratio = 0.25
)

Arguments

current

Numeric matrix or data frame of current environmental values.
future

Numeric matrix or data frame of future environmental values.
occupied

NULL, logical vector, row indices, or a numeric vector with one value per row identifying current occurrence, range, or continuous SDM suitability weights.
occupied_threshold

Threshold used when occupied contains binary or continuous values. Values at or below the threshold receive zero reference weight; values above it keep their original value.
cnfa

Optional CENFA model object.
center

Optional realised niche centre in standardised climate space.
sensitivity

Optional environmental sensitivity weights.
A

Optional niche metric matrix.
metric

Metric construction when A is not supplied.
boundary

User-set quantile defining the empirical realised niche boundary. The default is 0.95.
scale

Logical. If TRUE, standardise current and future values.
global_mean

Optional means used for standardisation.
global_sd

Optional standard deviations used for standardisation.
tolerance

Optional user-set Niche Distance Shift tolerance. If NULL, the value is calculated from tolerance_quantile.
tolerance_quantile

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

Optional user-set threshold for limited Climatic Displacement. If NULL, the value is calculated from stable_quantile.
stable_quantile

Quantile of Climatic Displacement used when stable_climate_change = NULL.
stable_reconfiguration

Optional user-set threshold for low Climatic Reconfiguration. If NULL, the value is calculated from stable_reconfiguration_quantile.
stable_reconfiguration_quantile

Quantile of Climatic Reconfiguration used when stable_reconfiguration = NULL.
boundary_exceedance_tolerance

User-set tolerance for deciding whether future climate exceeds the empirical niche boundary.
conflict_ratio

Minimum minority sign contribution share used to mark mixed variable responses. Set to NULL to disable this flag.

Details

The fitted object stores four primary metrics as snake_case fields: Climatic Displacement (climate_change_amount), Niche Distance Shift (niche_distance_change), Climatic Reconfiguration (climate_reconfiguration) and Niche Boundary Exceedance (niche_boundary_exceedance).

Let current and future climatic conditions at cell ii be cic_i and fif_i. Let μ\mu be the centre of the current realised climatic niche, and let dA(x,y)d_A(x, y) be the sensitivity weighted distance under weighting matrix AA. The four metrics are

Di=dA(fi,ci)D_i = d_A(f_i, c_i)

Ri=dA(fi,μ)−dA(ci,μ)R_i = d_A(f_i, \mu) - d_A(c_i, \mu)

Ci=max⁡(0,Di2−Ri2)C_i = \sqrt{\max(0, D_i^2 - R_i^2)}

Ei=max⁡(0,dA(fi,μ)−Bq)E_i = \max(0, d_A(f_i, \mu) - B_q)

where BqB_q is the qq-th weighted quantile of current reference cell distances from the realised niche centre. Positive Niche Boundary Exceedance is therefore an excess distance beyond this empirical radial boundary.

All classification-related thresholds are user-settable. If a direct threshold argument is NULL, climniche calculates the effective threshold from the corresponding quantile argument. The fitted object stores the effective values actually used in classification_settings.

Value

An object of class climniche_fit.

User-settable thresholds

  • boundary: quantile used to define the empirical realised niche boundary.

  • tolerance: direct Niche Distance Shift tolerance; otherwise tolerance_quantile.

  • stable_climate_change: direct Climatic Displacement threshold for the limited-change class; otherwise stable_quantile.

  • stable_reconfiguration: direct Climatic Reconfiguration threshold for the limited-change class; otherwise stable_reconfiguration_quantile.

  • boundary_exceedance_tolerance: direct tolerance for Niche Boundary Exceedance.

  • conflict_ratio: minority-sign contribution share used by the mixed variable-response diagnostic.

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

Arguments

current

Raster* object of current environmental layers.
future

Raster* object of future environmental layers.
occupied

Optional RasterLayer with binary or continuous occurrence, range, or SDM suitability values.
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.
...

Additional arguments passed to fit_climniche(), including boundary, tolerance, tolerance_quantile, stable_climate_change, stable_quantile, stable_reconfiguration, stable_reconfiguration_quantile, boundary_exceedance_tolerance and conflict_ratio.

Value

An object of class climniche_fit with raster outputs.

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

Arguments

current

terra SpatRaster of current environmental layers.
future

terra SpatRaster of future environmental layers.
occupied

Optional one layer SpatRaster with binary or continuous occurrence, range, or SDM suitability values.
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.
...

Additional arguments passed to fit_climniche(), including boundary, tolerance, tolerance_quantile, stable_climate_change, stable_quantile, stable_reconfiguration, stable_reconfiguration_quantile, boundary_exceedance_tolerance and conflict_ratio.

Value

An object of class climniche_fit with raster outputs.

Build a sensitivity weighted niche metric

Description

Build a sensitivity weighted niche metric

Usage

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

Arguments

sensitivity

Numeric vector of climate variable sensitivity weights.
cnfa

Optional CENFA cnfa object or list with sf, co, and eig.
type

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

Value

A positive semi-definite matrix.

Niche percentile shift

Description

Niche percentile shift

Usage

niche_percentile(psi_current, psi_future, occupied)

Arguments

psi_current

Current niche potential for all cells.
psi_future

Future niche potential for all cells.
occupied

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

Value

Data frame with current, future, and delta percentiles.

Niche potential

Description

Niche potential

Usage

niche_potential(x, center, A)

Arguments

x

Standardised climate matrix.
center

Realised niche centre.
A

Niche metric matrix.

Value

Numeric vector of quadratic niche displacement values.

Niche radius

Description

Niche radius

Usage

niche_radius(psi)

Arguments

psi

Numeric niche-potential values.

Value

Numeric vector in sensitivity weighted climate distance units.

Plot climniche class proportions

Description

Plot climniche class proportions

Usage

plot_climniche_class_summary(x, scope = c("current", "all"), title = NULL)

Arguments

x

A fitted climniche object.
scope

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

Optional plot title.

Value

A ggplot object.

Plot climniche classes

Description

Plot climniche classes

Usage

plot_climniche_classes(
  x,
  occupied = NULL,
  occupied_only = FALSE,
  occupied_threshold = NULL,
  title = NULL
)

Arguments

x

A fitted climniche object with raster outputs.
occupied

Optional current reference RasterLayer to overlay.
occupied_only

If TRUE, mask the plotted classes to current occurrence cells.
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.

Value

A ggplot object.

Plot a niche climate exposure diagram

Description

Plot a niche climate exposure diagram

Usage

plot_climniche_diagram(
  x,
  scope = c("current", "all"),
  type = c("summary", "sample"),
  summary_layout = c("metrics", "ordination"),
  max_arrows = 350L,
  seed = 1L,
  show_reference = FALSE,
  show_hulls = TRUE,
  boundary_shape = c("hull", "circle", "none"),
  show_boundary_label = TRUE,
  show_points = NULL,
  show_startpoints = FALSE,
  show_endpoints = FALSE,
  show_center = TRUE,
  show_variables = FALSE,
  variable_labels = NULL,
  title = NULL
)

Arguments

x

A fitted climniche object or data returned by climniche_diagram_data().
scope

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

"summary" draws mean current-to-future displacements for exposure classes; "sample" draws sampled cell displacements and future points.
summary_layout

Layout used when type = "summary". "metrics" draws the climate-space projection and two metric planes; "ordination" draws class mean arrows on the climate-space projection.
max_arrows

Maximum number of current to future arrows to draw when type = "sample".
seed

Random seed used when subsampling arrows.
show_reference

Logical; draw the full analysed climate-space domain.
show_hulls

Logical; draw current and future climate-space envelopes.
boundary_shape

Boundary display. "hull" draws the current reference climate envelope, "circle" draws a constant niche-distance boundary, and "none" suppresses the boundary.
show_boundary_label

Logical; add envelope explanations below the exposure-class legend.
show_points

Logical; draw future points when type = "sample".
show_startpoints

Logical; draw class mean current positions when type = "summary".
show_endpoints

Logical; draw class mean future positions when type = "summary".
show_center

Logical; mark the realised niche centre.
show_variables

Logical; draw environmental variable directions.
variable_labels

Optional named vector replacing variable labels.
title

Optional plot title.

Value

A ggplot object.

Plot a climniche metric distribution

Description

Plot a climniche metric 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

x

A fitted climniche object.
metric

Metric to plot.
scope

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

Optional plot title.

Value

A ggplot object.

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
)

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.

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
)

Arguments

x

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

Metric to plot.
occupied

Optional current reference RasterLayer to overlay.
occupied_only

If TRUE, mask the plotted raster to current occurrence cells.
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.

Value

A ggplot object.

Plot a climniche report figure

Description

Plot a climniche report figure

Usage

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_showcase(
  x,
  scope = c("current", "all"),
  max_points = 6000L,
  seed = 1L,
  plane_bins = 45L,
  boundary_probs = seq(0.5, 0.99, 0.01),
  top_variables = 6L,
  variable_labels = NULL,
  title = NULL
)

Arguments

x

A fitted climniche object or data returned by climniche_showcase_data().
scope

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

Maximum number of cells to draw in the exposure plane.
seed

Random seed used when subsampling cells.
plane_bins

Number of fixed bins used to summarize the exposure plane.
boundary_probs

Boundary quantiles used for the sensitivity curve.
top_variables

Number of variables to show.
variable_labels

Optional named vector replacing variable labels.
title

Optional overall title when patchwork is installed.

Value

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

Plot mean variable contribution

Description

Plot mean variable contribution

Usage

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 mean variable contribution

Description

Plot mean variable contribution

Usage

plot_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.

Simulate a minimal climate niche change experiment

Description

Simulate a minimal climate niche change experiment

Usage

simulate_climniche(
  n = 2000,
  p = 2,
  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.

Variable contribution to change in niche potential

Description

Variable contribution to change in niche potential

Usage

variable_contribution(current, future, center, A)

Arguments

current

Current standardized climate matrix.
future

Future standardized climate matrix.
center

Realised niche centre.
A

Niche metric matrix.

Value

Matrix whose rows sum to the change in niche potential.

Write a climniche report to Markdown

Description

Write a climniche report to Markdown

Usage

write_climniche_report(report, file)

Arguments

report

An object returned by climniche_report().
file

Output Markdown file.

Value

Invisibly returns file.