ERICA: Evaluating Replicability via Iterative Clustering Assignments

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.

Installation

pip install erica

# With visualization support
pip install erica[plots]

# With graphical interface (for those who prefer clicking)
pip install erica[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

Example Scripts

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

Replicability Metrics

ERICA implements two families of replicability metrics:

ERICA Metrics (CLAM-based)

ERICA Statistic (Clustering Replicability Index) is the core metric. It measures how consistently samples are assigned to their primary cluster across Monte Carlo iterations.

Parmigiani Metrics (Partition Comparison)

Based on Masoero et al. (2023) "Cross-Study Replicability in Cluster Analysis" (Parmigiani is a senior author, hence use of his name):

Interpretation

See the Metrics Guide for detailed explanations.

Sample Datasets

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

License

MIT License. See LICENSE for details.

Contact

• Issues: GitHub Issues
• Email: s.shirazi@berkeley.edu, siamak_sorooshyari@yahoo.com