erica 0.1.4

ERICA - Evaluating Replicability via Iterative Clustering Assignments

ERICA: Evaluating Replicability via Iterative Clustering Assignments

ERICA is a Python implementation for assessing clustering replicability using Monte Carlo subsampling (MCSS). Because finding clusters is easy—finding clusters that actually exist is the hard part.

The method evaluates whether cluster structures identified in a dataset are stable and reproducible across random subsamples, providing quantitative metrics for clustering validity assessment.

Installation

pip install erica-clustering

# With visualization support
pip install erica-clustering[plots]

# With graphical interface (for those who prefer clicking)
pip install erica-clustering[gui]

Basic Usage

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']}")

Documentation

Document	Description
Documentation Index	Complete documentation
Getting Started	Installation and tutorial
Metrics Guide	CRI, WCRI, TWCRI explained
API Reference	Function documentation
Methodology	The science behind the magic

Example Scripts

#	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.

Data Format

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

Replicability Metrics

ERICA implements two families of replicability metrics:

ERICA Metrics (CLAM-based)

CRI (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
CRI	Core metric	Proportion of iterations where samples are assigned to their primary cluster
WCRI	Derived	CRI weighted by cluster size
TWCRI	Aggregate	Sum of WCRI (used for K* selection)

Parmigiani Metrics (Partition Comparison)

Based on Parmigiani et al. (2023) "Cross-Study Replicability in Cluster Analysis":

Metric	Definition
ARI	Adjusted Rand Index - partition similarity adjusted for chance
AMI	Adjusted Mutual Information - information-theoretic comparison

Interpretation

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.

Sample Datasets

Dataset	Description	Source
VDX	Breast cancer gene expression (22,283 genes × 344 samples)	Parmigiani et al.
VDX_3_SV	Reduced 3-gene subset (344 samples)	Included in examples/data/

Requirements

Core: Python ≥ 3.8, NumPy, Pandas, scikit-learn, PyYAML

Optional: Plotly (visualization), Gradio (GUI)

Citation

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/sorooshyari/ERICA}
}

License

MIT License. See LICENSE for details.

Contact

• Issues: GitHub Issues
• Email: [e-mail], [e-mail]