Package {isoniche}

Title:	Calculating Density-Independent Niche Breadth Indices from Abundance Data
Version:	0.1.1
Description:	Deriving isodar-based niche breadth indices from abundance data of two or more habitats, including several methods based on pairwise isodars, multidimensional isodars, and isodar-adjusted inequality.
License:	GPL-3
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	tibble, dplyr, lmodel2
NeedsCompilation:	no
Packaged:	2026-05-10 18:47:39 UTC; shadu
Author:	Shahar Dubiner [aut, cre], Itai Granot [aut], Jonathan Belmaker [aut]
Maintainer:	Shahar Dubiner <dubiner@mail.tau.ac.il>
Repository:	CRAN
Date/Publication:	2026-05-10 19:00:02 UTC

Fit pairwise isodars between two or more habitats

Description

Fits pairwise isodar relationships between all habitat pairs using lmodel2::lmodel2() (Model II regression). Each output row represents the relationship:

habitat\_y = intercept + slope \times habitat\_x

Usage

fit_isodar(
  data,
  hab_cols = NULL,
  n_habitats = ncol(data),
  flip_intercept = TRUE
)

Arguments

Details

It is crucial to either place the columns with abundance for each habitat as the FIRST columns, or to explicitly state the habitat columns in hab\_cols.

If the fitted intercept is negative, the relationship is flipped (axes swapped) to provide a biologically interpretable representation (negative intercepts are meaningless in this context) and model refitted.

The sd column is the residual SD from vertical residuals in the reported equation.

Value

A tibble with one row per habitat pair containing:

• habitat_x, habitat_y

• slope, intercept

• sd: residual SD in the reported equation

• p_slope, p_intercept

• flipped: TRUE if axes were flipped (due to int<0), FALSE otherwise

Examples

set.seed(1)
isod <- simulate_isodars(1, 2, 5, 1, noise = 2, n = 10)
fit_isodar(isod, n_habitats = 3)

Compute the isodar-adjusted inequality index for one or more total abundances

Description

Reconstructs habitat abundances for each requested total abundance by solving a weighted least-squares system defined by the pairwise isodars:

habitat\_y = intercept + slope \times habitat\_x

Usage

isodar_adj_niche(
  isodars,
  abundances = NULL,
  weights = NULL,
  alpha = 0.1,
  sig_weights = c(sig = 1, nonsig = 0),
  method = c("gini"),
  plot = FALSE,
  max_search = 10000
)

Arguments

Details

The reconstruction is constrained to be nonnegative and to sum to the requested total abundance (active-set heuristic). Niche breadth is then computed from the reconstructed habitat vector; currently defined as:

niche breadth = 1 - Gini(x)

of isodar-reconstructed abundances at a given N.

To emphasize the intercept component, use baseline abundances provided by abundances = NULL. To emphasize the slope component, we recommend to set abundances to the highest n in your dataset. To see how niche breadth changes as a function of n, enter a vector of increasing abundances.

Value

A tibble with one row per total abundance containing:

• total_abundance

• niche_breadth

• one column per habitat with reconstructed abundance

Examples

set.seed(1)
isod <- simulate_isodars(1, 2, 5, 1, noise = 2, n = 10)
INB <- fit_isodar(isod, n_habitats = 3)
isodar_adj_niche(INB, max_search = 100) # automatically checks only baseline abundance
isodar_adj_niche(INB, abundances = c(15, 30, 45), max_search = 100) # set specific values

Multidimensional isodar-based niche breadth indices

Description

Computes vector- and orthogonal isodar-based niche breadth components from abundance data across all habitats simultaneously, generalizing the slope (density-dependent) and intercept/baseline (density-independent) components of isodars to n dimensions.

Usage

ndim_isoniche(data, n_habitats = ncol(data), scale = TRUE, weights = TRUE)

Arguments

Details

Both indices return values between 0 and 1, where 1 indicates a perfect generalist and 0 a specialist. Habitat axes can optionally be weighted by inverse residual variance.

Value

A tibble with vector, orthogonal, and n_habitats.

Examples

set.seed(1)
isod <- simulate_isodars(1, 2, 5, 1, noise = 2, n = 10)

Pairwise isodar-based niche breadth indices

Description

Computes niche breadth indices from a set of pairwise isodars (slopes and intercepts) in the format of the output table of fit_isodar(). Two methods are available: a weighted mean of isodar components and a weighted inverse variance of the isodars' divergence from neutrality.

Usage

pairwise_isoniche(
  data,
  method = c("inverse_variance", "mean"),
  weights = NULL,
  alpha = 0.1,
  sig_weights = c(sig = 1, nonsig = 0)
)

Arguments

Value

A one-row tibble with columns intercept, slope, and method.

Examples

set.seed(1)
isod <- simulate_isodars(1, 2, 5, 1, noise = 2, n = 10)
INB <- fit_isodar(isod, n_habitats = 3)
pairwise_isoniche(INB, method = "inverse_variance", weights = "1/var")
pairwise_isoniche(INB, method = "inverse_variance", weights = "sig",
             sig_weights = c(sig = 1, nonsig = 0.25), alpha = 0.1)

Simulate abundances across three habitats

Description

Simulates abundance data for three habitats across n sites using sequential linear relationships (isodars) with Gaussian noise:

• hab2 is generated from hab1 using slope1 and int1

• hab3 is generated from hab2 using slope2 and int2

Usage

simulate_isodars(
  slope1,
  slope2,
  int1,
  int2,
  noise = 1,
  n = 30,
  hab1_max = 100/(slope1^1.2) - int1
)

Arguments

Details

The output includes simple per-site niche metrics (CV and Gini) computed from the three habitat abundances.

Value

A tibble with one row per simulated site containing:

• hab1, hab2, hab3: simulated abundances (nonnegative integers)

• total_abundance: hab1 + hab2 + hab3

• mean_abundance: total_abundance divided by 3

• sd: scaled standard deviation of habitat abundances

• cv: coefficient of variation (NA if mean_abundance == 0)

• gini: Gini coefficient of habitat abundances

Examples

set.seed(1)
simulate_isodars(1, 2, 5, 1, noise = 2, n = 10)