ERICA is a Python implementation for assessing clustering replicability using Monte Carlo subsampling (MCSS). Declaring clusters is not difficult, but finding clusters that can be quantitatively shown to exist in a replicable manner is difficult.
The method evaluates whether cluster structures identified in a dataset are stable and reproducible across random subsamples, providing quantitative metrics for clustering validity assessment.
pip install erica
# With visualization support
pip install erica[plots]
# With graphical interface (for those who prefer clicking)
pip install erica[gui]from erica import ERICA
from erica.data import load_data
# Load data (samples × features format)
data = load_data('expression_data.csv')
# Initialize and run analysis
# method='both' runs K-Means, Agglomerative (Single), and Agglomerative (Ward)
erica = ERICA(
data=data,
k_range=[2, 3, 4, 5, 6, 7, 8],
n_iterations=200,
method='both' # K-Means + Agglomerative (Single & Ward)
)
results = erica.run()
# Retrieve recommended cluster number
k_star = erica.get_k_star('TWCRI')
print(f"Recommended K: {k_star['kmeans']}")| Document | Description |
|---|---|
| Documentation Index | Complete documentation |
| Getting Started | Installation and tutorial |
| Metrics Guide | ERICA Statistic, WCRI, TWCRI explained |
| API Reference | Function documentation |
| Methodology | The science behind the magic |
| # | Script | Description |
|---|---|---|
| 1 | 01_basic_usage.py | Synthetic data analysis |
| 2 | 02_vdx_analysis.py | Breast cancer gene expression (VDX dataset) |
| 3 | 03_k_star_selection.py | K* selection via Algorithm 2 |
| 4 | 04_advanced_usage.py | Component-level workflows |
| 5 | 05_parmigiani_metrics.py | ARI/AMI partition comparison metrics |
See examples/README.md for details and data acquisition instructions.
ERICA operates on data in samples × features format. (Yes, the orientation matters. We've all learned this the hard way.)
| Data Type | Input Format | Parameter |
|---|---|---|
| Genomics (genes × samples) | Features in rows | transpose=True (default) |
| Standard (samples × features) | Samples in rows | transpose=False |
ERICA implements two families of replicability metrics:
ERICA Statistic (Clustering Replicability Index) is the core metric. It measures how consistently samples are assigned to their primary cluster across Monte Carlo iterations.
| Metric | Role | Definition |
|---|---|---|
| ERICA Statistic | Core metric | Proportion of iterations where samples are assigned to their primary cluster |
| WCRI | Derived | CRI (i.e. ERICA statistic) weighted by cluster size |
| TWCRI | Aggregate | Sum of WCRI (used for K* selection) |
Based on Masoero et al. (2023) "Cross-Study Replicability in Cluster Analysis" (Parmigiani is a senior author, hence use of his name):
| Metric | Definition |
|---|---|
| ARI | Adjusted Rand Index - partition similarity adjusted for chance |
| AMI | Adjusted Mutual Information - information-theoretic comparison |
| Value Range | Interpretation |
|---|---|
| > 0.8 | High replicability (publishable with confidence) |
| 0.6–0.8 | Moderate replicability (proceed with caution) |
| < 0.6 | Low replicability (perhaps try a different K) |
See the Metrics Guide for detailed explanations.
| Dataset | Description | Source |
|---|---|---|
| VDX | Breast cancer gene expression (22,283 genes × 344 samples) | Masoero et al. |
| VDX_3_SV | Reduced 3-gene subset (344 samples) | Included in examples/data/ |
Core: Python ≥ 3.8, NumPy, Pandas, scikit-learn, PyYAML
Optional: Plotly (visualization), Gradio (GUI)
If you use ERICA in your research, please cite:
@software{erica2025,
title = {ERICA: Evaluating Replicability via Iterative Clustering Assignments},
author = {Sorooshyari, Siamak and Shirazi, Shawn},
year = {2025},
url = {https://github.com/PhenomML/ERICA}
}MIT License. See LICENSE for details.
- Issues: GitHub Issues
- Email: s.shirazi@berkeley.edu, siamak_sorooshyari@yahoo.com