community-ecology-ordination

name	community-ecology-ordination
description	Performs multivariate community ecology analyses including ordination, diversity metrics, and assemblage comparisons. Use this skill when the user mentions species composition, NMDS, PCA ordination, PERMANOVA, beta diversity, alpha diversity, species richness, Bray-Curtis dissimilarity, indicator species analysis, cluster analysis, species-by-site matrices, diversity indices, or assemblage structure comparisons.
skill_version	1.0.0

Skill: community-ecology-ordination

Domain: NMDS · PCA · PCoA · Diversity · Clustering · Composition
Phase: 3 — Specialist
Used by: analyze-community-structure

---

Purpose

Guides the agent through multivariate analysis of ecological communities: ordination of species assemblages, diversity metric computation, beta diversity partitioning, cluster analysis, and hypothesis testing on community composition.

---

When to Invoke

• Analysing species composition across multiple sites
• Comparing community structure between treatments, habitats, or time periods
• Computing alpha and beta diversity metrics
• Identifying species groups or site clusters

---

Inputs

Input	Format	Required
Species × site abundance or presence matrix	CSV	Yes
Environmental metadata per site	CSV	Recommended
Treatment or grouping variable	Factor column	Recommended

---

Outputs

Output	Description
ordination_plot.png	NMDS/PCA biplot
diversity_metrics.csv	Alpha diversity per site
beta_diversity_matrix.csv	Pairwise dissimilarity matrix
permanova_results.txt	PERMANOVA output
cluster_dendrogram.png	Hierarchical clustering dendrogram
community_report.md	Full analysis narrative

---

Steps

1. Data Preparation

• Check for sites with zero species (remove or flag)
• Check for species observed at only one site (rare species handling: keep or remove)
• Standardise if needed (Hellinger, Wisconsin, presence/absence)
• Choose dissimilarity metric: Bray-Curtis (abundance), Jaccard (presence/absence), UniFrac (phylogenetic)

2. Alpha Diversity

• Species richness (S)
• Shannon index (H')
• Simpson index (1−D)
• Rarefaction curves to assess sampling adequacy
• Report metric ± SE per group

3. Ordination

NMDS:

• Run with k=2 (default) and k=3; choose lowest stress with acceptable fit
• Stress < 0.1 = excellent, < 0.2 = acceptable, > 0.2 = poor
• Run with ≥ 20 random starts; confirm convergence

PCA (for environmental gradients or species scores):

• Use Hellinger-transformed data or correlation matrix
• Report eigenvalues and % variance per axis

PCoA / MDS:

• For non-Euclidean dissimilarity matrices

4. Beta Diversity Partitioning

• Partition total beta diversity into nestedness and turnover components (betapart)
• Report contribution of each component per group comparison

5. Hypothesis Testing

• PERMANOVA (adonis2): test if group centroids differ
• PERMDISP: test if group dispersions (variances) differ (required before interpreting PERMANOVA)
• ANOSIM: alternative non-parametric test
• Report F/R statistic, R², p-value (permutation-based)

6. Species Contributions

• SIMPER: identify species driving dissimilarity between groups
• IndVal: identify indicator species per group
• Report top N contributing species per axis or group

7. Cluster Analysis

• Hierarchical clustering: Ward.D2 linkage preferred
• Cophenetic correlation to assess cluster quality
• k-means as alternative for large datasets
• Determine optimal k using silhouette or elbow method

---

Decision Points

Condition	Diagnosis	Recommended Action
n_sites < 5 per group	Insufficient replication for PERMANOVA	Report descriptive statistics only; do not run hypothesis tests
NMDS stress > 0.2	Ordination distorting community distances	Increase NMDS dimensions to 3; or reduce species set by removing very rare species
NMDS stress > 0.3	Ordination is unreliable	Do not use NMDS; switch to PCoA or PCA on transformed data
Species occurring in < 5% of sites	Rare species inflating beta diversity	Apply rarity filter or downweight with Hellinger/Wisconsin transformation
PERMANOVA significant but PERMDISP also significant	Group dispersion differs (not only composition)	Report both results; interpret composition difference cautiously

---

Key Decisions to Document

• Dissimilarity metric and rationale
• Rare species handling
• Data transformation applied
• Number of NMDS dimensions
• Permutation count for PERMANOVA

---

Tools and Libraries

R: vegan, betapart, indicspecies, ape, dendextend, ggplot2
Python: skbio, scipy.cluster, sklearn.manifold

---

Resources

• resources/dissimilarity-metric-guide.md — which metric for which data type
• resources/nmds-interpretation-guide.md — how to read and report NMDS plots
• examples/ — worked NMDS and PERMANOVA example

---

Notes

• Always run PERMDISP before interpreting PERMANOVA; significant dispersion differences can inflate PERMANOVA results
• Stress value must be reported alongside all NMDS plots
• Rarefaction is mandatory when sites have very different sampling intensities