The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

EcoNiche

EcoNiche is an R package for quantifying niche position and niche breadth under continuous, multidimensional environmental gradients.

Traditional niche breadth indices often treat sampling units as discrete states. However, real ecological gradients are continuous, multidimensional, and frequently confounded by covariates (e.g., climate, spatial structure, background environmental effects). EcoNiche provides a standardized workflow to estimate niche parameters within a constrained ordination framework while explicitly controlling for covariates.

The package is built around one central idea:

Estimate niche position and conditional niche breadth in a continuous environmental space, rather than across arbitrary discrete states.

To achieve this, EcoNiche implements three analytical modules with distinct roles:

1️⃣ CCA / partial-CCA (core framework)

This is the primary method of EcoNiche.

This workflow is based on canonical correspondence analysis (CCA) and partial CCA (pCCA) following Okie et al. (2015) and Feng et al. (2020).

It allows users to:

Conceptually:

This framework is specifically designed for:

2️⃣ GAM (nonlinear single-gradient modeling and species response curves)

The GAM module serves both as a validation tool and as a biologically interpretable response modeling framework.

It fits species-specific response curves along the composite environmental axis (typically CCA1), allowing:

This module serves three complementary purposes:

  1. Cross-validation of ordination-based niche position
    GAM-derived optima can be compared directly with CCA-based abundance-weighted means to evaluate positional consistency.

  2. Quantification of one-dimensional tolerance along the dominant composite gradient
    Breadth50 provides a practical measure of effective response range along the main constrained axis.

  3. Visualization of individual species response curves
    GAM explicitly models the abundance–environment relationship, allowing users to:

Importantly, the GAM analysis is conducted within the same gradient coordinate system defined by CCA, ensuring conceptual consistency between ordination-based and response-curve-based niche estimation.

3️⃣ Levins’ niche breadth (discrete-state benchmark)

Levins’ index is implemented for comparison, not as the primary estimator.

EcoNiche provides two Levins implementations:

These serve as sensitivity benchmarks to evaluate:

In continuous-gradient contexts, Levins’ breadth may reflect occupancy or prevalence more than environmental tolerance. Therefore, it is included primarily for methodological comparison.

Conceptual structure of EcoNiche

github计算框架

EcoNiche is designed as a modular analytical framework rather than a fixed analytical pipeline.

At its core, the framework is built on constrained ordination:

CCA / partial-CCA define the composite environmental gradient and estimate niche parameters in continuous multivariate space.

From this core framework, users may choose different complementary modules depending on their research question:

Core module: CCA / pCCA

Used to estimate:

This module is recommended when: - Environmental predictors are multidimensional - Covariate control is required - Continuous-gradient niche estimation is the primary objective

Optional module A: GAM

Used when users wish to:

GAM operates along the composite gradient defined by CCA, ensuring consistency in coordinate space.

Optional module B: Levins’ breadth

Used when users wish to:

Levins’ index is included primarily as a comparative benchmark rather than the primary estimator under continuous gradients.

In practice, users typically:

  1. Define focal environmental predictors and covariates.
  2. Estimate niche position and conditional niche breadth using CCA/pCCA.
  3. Optionally apply GAM for species-level response modeling.
  4. Optionally compute Levins’ breadth for methodological comparison.

This flexible structure allows researchers to tailor analyses to their ecological question while maintaining a coherent gradient-based coordinate system.

Package version: 0.9.0

Installation

Install the development version from GitHub

# install.packages("remotes")
remotes::install_github("zhoushuotao/EcoNiche")

Dependencies

EcoNiche imports:

Suggested:

Data format (important)

Most functions assume the following:

1) otu: taxon-by-sample abundance table

otu[1:3, 1:3]
#        S1 S2 S3
# OTU1   10  0  2
# OTU2    3  1  0
# OTU3    0  0  5

2) env: sample-by-environment table

env[1:3, ]
#      Temp   pH   SOC
# S1   15.2  6.7  2.31
# S2   18.1  6.3  1.90
# S3   12.4  6.8  3.05

3) group (only for group workflow)

Quick start (toy example)

library(EcoNiche)

set.seed(1)

# OTU table: 50 taxa x 30 samples
otu <- matrix(rpois(50 * 30, lambda = 10), nrow = 50, ncol = 30)
rownames(otu) <- paste0("OTU", 1:50)
colnames(otu) <- paste0("S", 1:30)

# Environment table: 30 samples x 3 variables
env <- data.frame(
  Temp = rnorm(30, 15, 3),
  pH   = rnorm(30, 6.5, 0.4),
  SOC  = rlnorm(30, 2, 0.3)
)
rownames(env) <- colnames(otu)

Workflow A: CCA / partial-CCA (multi-dimensional niche)

EcoNiche provides a controller function cca_workflow() and two explicit workflows:

A1) Gradient workflow

Use when you want:

res <- cca_workflow(
  mode = "gradient",
  otu = otu,
  env = env,
  sel = "Temp",                 # constrained variable(s) for the width axis (partial-CCA)
  covariates = c("pH", "SOC")    # variables for position axis (CCA) and as covariates in partial-CCA
)

# Species-level niche traits (position/width)
head(res$species$species)

# Plot: niche width vs niche position
res$species$plot

# Site niche position vs a gradient variable
res$gradient$plot

Choosing sel and covariates in CCA/pCCA

EcoNiche separates environmental predictors into:

The appropriate choice depends on study design and ecological hypothesis.

Scenario 1: Sampling along a known focal gradient (hypothesis-driven design)

If samples were collected explicitly along a known environmental gradient (e.g., temperature, pH, elevation), that gradient should typically be treated as the focal predictor.

Example:

Recommended setup:

sel = "Temperature"
covariates = c("pH", "NDVI")

Interpretation:

This setup is appropriate when the research question is:

How do species’ niches vary along temperature after accounting for other environmental structure?

Scenario 2: No predefined focal gradient (exploratory design)

If the dominant environmental structure is unclear, or multiple predictors are strongly correlated, a data-driven approach is recommended.

In this case:

  1. Perform PCA on environmental variables.

  2. Inspect loadings of PC1 and PC2.

  3. Identify the dominant composite environmental structure.

  4. Use this information to guide CCA/pCCA specification.

Example:

You may then:

This approach avoids arbitrarily selecting a single variable when gradients are inherently multivariate.

A2) Group workflow

Use when samples belong to groups (e.g., habitat types, treatments, regions) and you want group summaries.

group <- rep(c("A", "B", "C"), length.out = ncol(otu))
names(group) <- colnames(otu)

res_g <- cca_workflow(
  mode = "group",
  otu = otu,
  env = env,
  sel = "Temp",
  covariates = c("pH", "SOC"),
  group = group,
  plot_type = "both"  # "sample" / "group" / "both"
)

head(res_g$group$group_summary)
res_g$plot

Workflow B: GAM response curves along a single gradient

Use when your main question is:

For each taxon, what is the optimum along gradient X, and how wide is its response?

EcoNiche fits one GAM per taxon and reports (among others):

B1) Fit all taxa

gam_df <- gam_fit_model(
  otu = otu,
  env = env,
  env_var = "Temp",
  data_type = "count",      # "auto" / "count" / "relative"
  count_family = "nb",      # "nb" / "poisson"
  use_offset = TRUE,        # offset = log(library size) for count mode
  min_prev = 0.10,
  min_total = 100,
  k_spline = 5,
  n_grid = 200,
  verbose = TRUE
)

head(gam_df)

B2) Plot a single taxon

p <- gam_plot_species(
  otu = otu,
  env = env,
  env_var = "Temp",
  otu_id = "OTU1",
  data_type = "count",
  count_family = "nb",
  add_ci = TRUE
)

p$plot
p$optimum_env
p$breadth50

B3) Sample-level summary (abundance-weighted mean breadth)

site_bw <- gam_calc_sitewidth(
  otu = otu,
  niche_df = gam_df,
  width_col = "breadth50",
  weight_mode = "auto"
)

head(site_bw)

Workflow C: Levins niche breadth

Levins breadth treats environments as discrete states and measures how evenly a taxon occupies these states.

EcoNiche supports:

C1) Samples as states (classic)

lev_samples <- niche_width_calc(
  otu = otu,
  env = env,           # optional; used for aligning samples
  method = "levins",   # "levins" / "shannon" / "both"
  standardize = TRUE,
  min_occ = 3,
  min_abund = 5
)

head(lev_samples)

Discretize a continuous gradient into bins, aggregate abundances within bins, then compute Levins breadth across bins.

lev_binned <- levins_calc_binned(
  otu = otu,
  env = env,
  axis_var = "Temp",
  nbin = 8,
  bin_method = "equal_freq",  # "equal_freq" (quantiles) or "equal_width"
  agg_fun = "mean",           # "mean" recommended; or "sum"
  otu_mode = "auto",
  min_occ = 3,
  min_abund = 5
)

head(lev_binned)

C3) Community-mean Levins width vs gradient

lev_comm <- levins_calc_group(
  otu = otu,
  env = env,
  levins_df = lev_binned,
  grad = "Temp",
  width_col = "levins_Bstd",
  method = "loess",
  make_plot = TRUE
)

head(lev_comm$data)
lev_comm$plot

C4) Position–width relationship (e.g., compare CCA position vs Levins width)

pos_df <- res$species$species
pos_df$OTU <- rownames(pos_df)

pos_width <- levins_plot_pos_width(
  pos_df = pos_df,
  levins_df = lev_binned,
  id_col = "OTU",
  pos_col = "NichePosition",
  width_col = "levins_Bstd",
  method = "lm",
  make_plot = TRUE
)

pos_width$plot

Practical guidance (what to use when)

Common pitfalls

  1. Sample alignment

  2. Rare taxa

  3. Counts vs relative abundance

  4. Numeric column indices

Vignette

A vignette exists under vignettes/ (currently titled “CoNiche workflow” due to legacy naming).

To build vignettes locally:

install.packages(c("knitr", "rmarkdown"))
devtools::build_vignettes()

API overview (exported functions)

CCA / partial-CCA

GAM

Levins

Citation

If you use EcoNiche in a publication, please cite the software (and include the version):

Zhou S, Feng K, Deng Y. EcoNiche: Community Niche Position and Width Estimation Tools (R package), v1.0.1. GitHub: https://github.com/yedeng-lab/EcoNiche

(Replace with a formal paper citation if/when a methods manuscript is published.)

Contributing / Support

Issues and pull requests are welcome.

When reporting bugs, please include:

License

MIT License (see LICENSE / LICENSE.md).

::contentReference[oaicite:0]{index=0}

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.