CoNiche: Community Niche Position and Width Estimation Tools

Description

CoNiche provides tools to estimate niche position and niche width using (i) CCA/partial-CCA workflows, (ii) GAM fits along single gradients, and (iii) Levins niche breadth metrics, with functions for species- and site-level summaries.

Author(s)

Maintainer: Shuotao Zhou zhoushuotao@stu.hunau.edu.cn

Authors:

• Kai Feng kaifeng@rcees.ac.cn

• Ye Deng yedeng@rcees.ac.cn

See Also

Useful links:

• https://github.com/yedeng-lab/EcoNiche

• Report bugs at https://github.com/yedeng-lab/EcoNiche/issues

Plot Site Niche Position vs Environmental Gradient (Step 4)

Description

Evaluates the relationship between the environmental gradient and the aggregated niche position of sites.

Usage

cca_calc_gradient(env, site_pos, var, make_plot = TRUE, galaxy_colnum = TRUE)

Arguments

Value

A list containing:

data

Data frame used for plotting (ENV, NichePosition).

plot

The ggplot object.

Calculate Niche Width Summary by Group (Step 5)

Description

Computes aggregated niche width statistics at the sample level and group level. Supports two calculation modes via choice: "all" (global context) or group-specific context.

Usage

cca_calc_group(otu, site_width, group, choice = "all")

Arguments

Value

A list containing:

sample_summary

Data frame of sample-level statistics (ID, AverageValue, StandardDeviation/Error).

group_summary

Data frame of group-level statistics.

Calculate Species Niche Width and Position (Step 3)

Description

Computes the niche width and niche position for each species using the site scores from Step 2. Generates a plot of Niche Width vs. Niche Position.

Usage

cca_calc_species(
  otu,
  site_width,
  site_pos,
  method = c("lm", "loess"),
  make_plot = TRUE,
  top_node = 10000
)

Arguments

Value

A list containing:

species

Data frame of species traits (NichePosition, NicheWidth).

plot

The ggplot object (if make_plot = TRUE).

Fit CCA and Partial-CCA Ordination (Step 2)

Description

Performs Constrained Correspondence Analysis (CCA) and Partial CCA to obtain site scores for niche position and niche width calculations.

Usage

cca_fit_ordination(
  otu,
  env,
  sel,
  covariates,
  standardize = TRUE,
  galaxy_colnum = TRUE
)

Arguments

Value

A list containing:

site_width

Matrix of site scores from the partial CCA (width axes).

site_pos

Named vector of site scores from the first axis of the CCA (position axis).

site_pos_mat

Matrix of all site scores from the CCA.

cca

The CCA model object.

pcca

The Partial CCA model object.

Plot Sample/Group Niche Width vs Environmental Gradient (Step 6)

Description

Visualizes the relationship between environmental gradients and niche width at the sample or group level.

Usage

cca_plot_group_env(
  env,
  sample_summary,
  var,
  group = NULL,
  plot_type = c("sample", "group", "both"),
  method = c("lm", "loess"),
  make_plot = TRUE,
  galaxy_colnum = TRUE,
  show_ci = TRUE,
  annotate_stats = TRUE
)

Arguments

Value

A list containing data frames and ggplot objects for samples and/or groups.

Prepare Environmental Data for CCA (Step 1)

Description

Performs standardization and Principal Component Analysis (PCA) on environmental variables. This step assists in selecting constrained variables and covariates for downstream CCA or partial-CCA.

Usage

cca_prep_env(
  env,
  sel,
  constrain = NULL,
  standardize = TRUE,
  galaxy_colnum = TRUE
)

Arguments

Value

A list containing:

env_sd

The standardized environmental data frame.

sel_idx

Indices of selected variables.

con_idx

Indices of constrained covariates.

pca

The PCA result object (from prcomp).

combined

A data frame combining SampleID, PCA axes, and constrained variables.

cor_res

A matrix/table of correlations between PCA axes and original variables, including significance levels.

CCA-Based Niche Analysis Workflow Controller

Description

A controller function that orchestrates the CCA-based niche analysis workflow. It dispatches the execution to either the gradient workflow (Steps 1-4) or the group workflow (Steps 1-2, 5-6) based on the specified mode.

Usage

cca_workflow(mode = c("gradient", "group"), ...)

Arguments

Value

A list containing the results of the executed workflow steps. See cca_workflow_gradient or cca_workflow_group for structure details.

Examples

set.seed(1)
otu <- matrix(rpois(20*25, 5), nrow = 20)
rownames(otu) <- paste0("OTU", 1:20)
colnames(otu) <- paste0("S", 1:25)
env <- data.frame(
  Temp = rnorm(25, 15, 3),
  pH   = rnorm(25, 6.5, 0.4),
  SOC  = rlnorm(25, 2, 0.3)
)
rownames(env) <- colnames(otu)
res <- cca_workflow(
  mode = "gradient",
  otu = otu, env = env,
  sel = c("Temp", "pH"),
  covariates = "SOC",
  make_plot = FALSE,
  top_node = 20
)
str(res, max.level = 1)

Execute Gradient-Based Workflow (Steps 1-4)

Description

Runs the complete environmental gradient analysis pipeline: 1. Prepare env data (PCA) 2. Fit CCA/Partial-CCA 3. Calculate species niche traits 4. Analyze gradient vs niche position

Usage

cca_workflow_gradient(
  otu,
  env,
  sel,
  covariates,
  standardize = TRUE,
  method = c("lm", "loess"),
  var = sel[1],
  galaxy_colnum = TRUE,
  make_plot = TRUE,
  top_node = 10000
)

Arguments

Value

A named list containing outputs of steps 1 through 4.

Execute Group-Based Workflow (Steps 1-2, 5-6)

Description

Runs the complete group-based analysis pipeline: 1. Prepare env data (PCA) 2. Fit CCA/Partial-CCA 5. Calculate group niche widths 6. Plot group/sample niche width vs gradient

Usage

cca_workflow_group(
  otu,
  env,
  sel,
  group,
  covariates,
  standardize = TRUE,
  method = c("lm", "loess"),
  var = sel[1],
  choice = "all",
  galaxy_colnum = TRUE,
  make_plot = TRUE,
  plot_type = c("sample", "group", "both"),
  show_ci = TRUE,
  annotate_stats = TRUE
)

Arguments

Value

A named list containing outputs of steps 1, 2, 5, and 6.

Calculate Sample-Level Niche Width Weighted by Abundance

Description

Computes the abundance-weighted mean niche breadth for each sample, given an OTU-by-sample table and OTU-level niche breadth estimates (e.g., from gam_fit_model). The formula is:

B_j = \sum_i (abundance_{ij} \times breadth50_i) / \sum_i abundance_{ij}

Usage

gam_calc_sitewidth(
  otu,
  niche_df,
  otu_col = "OTU",
  width_col = "breadth50",
  weight_mode = c("auto", "counts", "relative")
)

Arguments

Value

A data frame with columns sample and Bw50_abundance_weighted.

Fit GAM-Based Niche Curves for All OTUs

Description

Fits a Generalized Additive Model (GAM) response curve for each OTU along a single environmental gradient. This function handles both count data (using Negative Binomial or Poisson families) and relative abundance data (using logit-transformed Gaussian models). It estimates the niche optimum and the 50% niche breadth (breadth50) for each taxon.

Usage

gam_fit_model(
  otu,
  env,
  env_var,
  data_type = c("auto", "count", "relative"),
  count_family = c("nb", "poisson"),
  use_offset = TRUE,
  lib_size = NULL,
  min_prev = 0.1,
  min_total = 100,
  min_mean = 1e-05,
  k_spline = 5,
  n_grid = 200,
  verbose = TRUE
)

Arguments

Value

A data frame with one row per OTU and the following columns:

OTU

OTU identifier.

n_nonzero

Number of samples with non-zero abundance.

prevalence

Proportion of samples with non-zero abundance.

total_counts

Total counts (for count data) or NA.

r2

Adjusted R-squared (for relative abundance models) or NA.

dev_expl

Proportion of deviance explained.

edf

Effective degrees of freedom of the smooth term.

F_stat

Test statistic (F or Chi-sq) for the smooth term.

p_value

Approximate p-value for the smooth term.

optimum_env

Environmental value at the peak of the fitted curve.

env50_min

Lower environmental bound where fitted abundance >= 50% of peak.

env50_max

Upper environmental bound where fitted abundance >= 50% of peak.

breadth50

Niche breadth (env50_max - env50_min).

Plot GAM-Based Niche Curve for a Single OTU

Description

Fits a GAM response curve for a specific OTU and plots the results. Includes options for confidence intervals and different color palettes.

Usage

gam_plot_species(
  otu,
  env,
  env_var,
  otu_id,
  data_type = c("auto", "count", "relative"),
  count_family = c("nb", "poisson"),
  use_offset = TRUE,
  lib_size = NULL,
  min_mean = 1e-05,
  min_prev = 0.1,
  k_spline = 5,
  n_grid = 200,
  add_ci = TRUE,
  palette = c("blue", "orange", "green", "purple", "viridis"),
  point_alpha = 0.85
)

Arguments

Value

A list containing:

data

Data frame of observed values (env, y).

grid

Data frame of fitted values along the gradient.

fit

The GAM model object.

optimum_env

Estimated niche optimum.

env50_min

Lower bound of 50% niche breadth.

env50_max

Upper bound of 50% niche breadth.

breadth50

Niche breadth.

plot

The ggplot object.

Calculate Levins Niche Width Along a Gradient (Binned States)

Description

Computes OTU-level Levins niche breadth along a continuous composite axis (e.g., CCA1) by discretizing the axis into bins (states). Abundance is first aggregated within bins (mean or sum), converted to within-bin proportions p_{ij}, and then used to compute:

B_i = 1 / \sum_j p_{ij}^2

A standardized breadth is also reported:

B_i' = (B_i - 1)/(K - 1)

where K is the number of bins.

Usage

levins_calc_binned(
  otu,
  env,
  axis_var,
  nbin = 8L,
  bin_method = c("equal_freq", "equal_width"),
  agg_fun = c("mean", "sum"),
  otu_mode = c("auto", "count", "relative"),
  min_occ = 3L,
  min_abund = 5
)

Arguments

Value

A data frame with one row per OTU and the following columns:

OTU

OTU identifier.

axis

Name of the gradient axis used.

n_states

Number of bins (K).

levins_B

Raw Levins niche breadth.

levins_Bstd

Standardized Levins niche breadth.

n_samples

Number of samples where the OTU is present.

total_abund

Total abundance of the OTU.

Calculate Community-Mean Levins Niche Width Along a Gradient

Description

Computes the abundance-weighted mean Levins width for each sample, using OTU-level Levins widths and sample-level OTU abundances. Optionally plots the relationship between this community metric and an environmental gradient.

Usage

levins_calc_group(
  otu,
  env,
  levins_df,
  grad,
  width_col = "levins_Bstd",
  method = c("lm", "loess"),
  make_plot = TRUE
)

Arguments

Details

The community-mean width for sample s is:

B_s = \sum_i Q_{is} B_i'

where Q_{is} is the relative abundance of OTU i in sample s and B_i' is the standardized Levins width (levins_Bstd).

Value

A list containing:

data

Data frame with columns Sample, ENV, and CommLevinsWidth.

plot

The ggplot object (if make_plot=TRUE).

Plot Species Niche Position vs Levins Width

Description

Merges species niche optima (from any method such as CCA, GAM, or weighted average) with standardized Levins niche width, and plots the position-width relationship showing the correlation (R-squared) and P-value.

Usage

levins_plot_pos_width(
  pos_df,
  levins_df,
  id_col,
  pos_col = "NichePosition",
  width_col = "levins_Bstd",
  method = c("lm", "loess"),
  make_plot = TRUE
)

Arguments

Value

A list containing:

data

Merged data frame used for plotting.

plot

The ggplot object (if make_plot=TRUE).

Calculate Niche Width (Samples as States)

Description

Computes OTU-level niche breadth by treating each sample as a discrete state. For OTU i, let p_{is} be the proportional abundance of OTU i in sample s (i.e., abundance of OTU i normalized to sum to 1 across all samples).

Usage

niche_width_calc(
  otu,
  env = NULL,
  min_occ = 3L,
  min_abund = 5,
  standardize = TRUE,
  method = c("levins", "shannon", "both")
)

Arguments

Details

Two niche-width indices are supported via method:

• Levins breadth (Levins):

  B_i = 1 / \sum_s p_{is}^2

  Optionally, a standardized breadth ranging from 0 to 1 is returned:

  B_i' = (B_i - 1)/(K - 1)

  where K is the total number of samples (states).

• Shannon breadth (Shannon):

  H_i = - \sum_s p_{is}\log(p_{is})

  Terms with p_{is}=0 are excluded from the sum to avoid \log(0).

Value

A data frame with one row per OTU. Columns include:

OTU

OTU identifier.

n_states

Number of states (samples) used in calculation.

n_samples

Number of samples where the OTU is present.

total_abund

Total abundance of the OTU across samples.

levins_B

Raw Levins niche breadth. Present if method is "levins" or "both".

levins_Bstd

Standardized Levins niche breadth (if standardize=TRUE). Present if method is "levins" or "both".

shannon_H

Shannon niche breadth (entropy). Present if method is "shannon" or "both".