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 or thresholded SDM suitability maps, current environmental rasters and future projections, the package separates climate change amount, change in distance to the current niche centre, composition change and exceedance beyond an empirical niche boundary.
Authors: Bohao He [aut, cre]
Maintainer: Bohao He <[email protected]>
License: GPL (>= 3)
Version: 0.0.1
Built: 2026-05-29 19:42:45 UTC
Source: https://github.com/cran/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 occupied-niche boundary 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 occurrence, range or thresholded SDM 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 occurrence/range cells or "all" for all evaluated cells.
top_variables

Number of variable contributions to show.

Value

An object of class climniche_report.

Build data for the climniche showcase figure

Description

Build data for the climniche showcase 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 occurrence, range or thresholded SDM 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 occurrence/range cells or "all" for all evaluated cells.

Value

A one-row data frame with key report metrics.

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 occurrence/range cells or "all" for all evaluated cells.

Value

A data frame with one row per evaluated cell.

Fit niche climate exposure

Description

Fit niche climate exposure

Usage

fit_climniche(
  current,
  future,
  occupied = NULL,
  occupied_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,
  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 thresholded SDM cells.
occupied_threshold

Threshold used when occupied contains binary or continuous values.
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

Quantile defining the empirical realised niche boundary.
scale

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

Optional means used for standardisation.
global_sd

Optional standard deviations used for standardisation.
conflict_ratio

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

Value

An object of class climniche_fit.

Fit climniche to raster data

Description

Fit climniche to raster data

Usage

fit_climniche_raster(
  current,
  future,
  occupied = NULL,
  occupied_threshold = 0,
  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 greater than this threshold are treated as current occurrence cells.
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().

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 = 0,
  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 greater than this threshold are treated as current occurrence cells.
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().

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

Standardized climate matrix.
center

Realized niche center.
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 occurrence/range 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 = 0,
  title = NULL
)

Arguments

x

A fitted climniche object with raster outputs.
occupied

Optional current occurrence/range 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.
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"),
  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_endpoints = FALSE,
  show_center = FALSE,
  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 occurrence, range or thresholded SDM cells; "all" for all evaluated cells.
type

"summary" draws class mean arrows; "sample" draws sampled cell arrows and future points.
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 environmental domain.
show_hulls

Logical; draw current and future niche hulls.
boundary_shape

Boundary display. "hull" draws the empirical occupied niche polygon, "circle" draws a constant niche distance boundary, and "none" suppresses the boundary.
show_boundary_label

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

Logical; draw future points when type = "sample".
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",
    "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 occurrence/range 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 occurrence/range 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", "outside_niche_exceedance",
    "climate_change_amount", "composition_change", "change_alignment"),
  occupied = NULL,
  occupied_only = FALSE,
  occupied_threshold = 0,
  title = NULL,
  midpoint = 0
)

Arguments

x

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

Metric to plot.
occupied

Optional current occurrence/range 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.
title

Optional plot title. Use FALSE to suppress it.
midpoint

Midpoint for the niche distance change 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 occurrence/range 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 showcase figure

Description

Plot the climniche showcase 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 occurrence, range or thresholded SDM 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

Climate change amount 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.