Consensus Classifier for MCL

XGBoost-based consensus classifier for MCL transcriptomics-like tabular data. Ships with curated training assets bundled inside the package (under cclf/data/) and a CLI for quick use.

Data privacy

Bundled training rows use pseudonymized labels (sample_001 through sample_224). Raw patient/sample identifiers, experimental cohorts, notebooks, and generated results are kept locally and are not part of the public package.

Requirements

• Python 3.10–3.12
• OS: Linux/macOS/Windows
• Dependencies are declared in pyproject.toml (Poetry) and resolved on install.

Install

Clone the repo and install in editable mode (inside a virtualenv):

git clone https://github.com/MLO-lab/mcl-classifier.git
cd mcl-classifier
pip install -e .

Quick start (CLI)

Run the classifier on a CSV test data (rows=samples, columns=features):

python cclf/clf.py path/to/test_data.csv -m 10 -f 200 --out results

That will create results.csv in the current directory.

Options

• -m / --models — number of models in the consensus (default: 100)
• -f / --features_per_model — features per model (int or fraction in code; CLI uses int)
• --zscore / --no-zscore — apply z-score transformation (default: --zscore); based on our experience, we recommend z-scores for normalized counts. --no-zscore uses ranks instead.
• --out — output file name (”.csv” added if missing)

See full help:

python cclf/clf.py --help

Python API

Use the ConsensusClassifier class directly:

import pandas as pd
from cclf import DATA_DIR
from cclf.clf import ConsensusClassifier

# 1) Load test data
Y_test = pd.read_csv("path/to/data.csv", index_col=0)  # test set

# 2) Create and fit the consensus classifier
clf = ConsensusClassifier(
    n_models=10,
    n_features_per_model=200,
    use_ranks=False,
    use_z_scores=True,
)

# Add the test data before fitting.
clf.add_test_data(Y_test)
clf.fit(seed=1301)

# 3) Get results
probs = clf.predict_proba()     # DataFrame [n_samples x n_classes]
preds = clf.predict()           # Series of predicted labels
votes = clf.votes               # Series of vote counts
clf.export_results("results.csv")  # also returns the combined DataFrame

Input format

Test CSV (the file you pass as the positional data argument):

• Rows = samples, columns = features
• First column should be an index (the CLI reads with index_col=0)
• Feature columns must be numeric

Example snippet:

sample_id,FEAT1,FEAT2,FEAT3
S1,0.23,1.5,4.2
S2,0.10,1.7,3.8

The classifier automatically intersects the test features with the training signature and logs how many are used.

Output

results.csv contains:

• MCL_PG1, MCL_PG2, ..., MCL_PG8 — aggregated class probabilities
• Cluster — consensus label
• Votes — number of base learners voting for the predicted class