shailja0103/ac-tcr-identification-rf

AC-TCR: CD8+ T-cell Reactivity Identification Model

A Random Forest classifier that identifies tumor-reactive vs bystander CD8+ T cells from single-cell RNA-seq expression plus a TCR clonal-expansion feature. Trained with patient-level leave-one-group-out cross-validation across 9 patients (4,399 cells).

Full pipeline, usage instructions, and companion activation-scoring script: https://github.com/ShailjaDhanuka/AC-TCR

Model details

• Algorithm: sklearn.ensemble.RandomForestClassifier (n_estimators=300, max_depth=3, class_weight='balanced', min_samples_leaf=20, max_features='sqrt')
• Features (12): 11 log-normalized genes — GAPDH, CD74, NKG7, DUSP4, GZMH, GZMK, CD27, IL7R, CXCL13, ITGAE, LAYN — plus clone_size_norm, a within-patient z-score of log1p(TCR clonotype size). See the GitHub README's "How TCR information is used" section for exactly how to derive this feature from a raw per-cell clonotype_id column.
• Label: Reactive vs Bystander (binary)
• In-sample AUC: 0.911, in-sample accuracy: 0.833 (production model, fit on all labeled data — see the GitHub repo's training.py/logo_cv_metrics.csv for the actual held-out, patient-level cross-validated performance, which is the number that matters for judging generalization)
• Training data: 9 patients, 4,399 CD8+ T cells

File

random_forest_production.joblib — a joblib-pickled Python dict with keys:

{
    "model": RandomForestClassifier(...),
    "feature_cols": [...],       # exact column order the model expects
    "gene_panel": [...],
    "label_col": str,
    "patient_col": str,
    "clonal_feature_col": "clone_size_norm",
    "best_params": {...},
    "in_sample_auc": float,
    "in_sample_acc": float,
    "train_patients": [...],
    "n_train_cells": int,
    "trained_on": "<ISO timestamp>",
}

Usage

Use with inference.py from the AC-TCR GitHub repo:

pip install huggingface_hub
python -c "from huggingface_hub import hf_hub_download; \
    print(hf_hub_download('shailja0103/ac-tcr-identification-rf', 'random_forest_production.joblib'))"

python inference.py \
    --input your_data.h5ad \
    --model-path <downloaded_path> \
    --patient-col orig.ident \
    --output scored.h5ad

Or load it directly:

import joblib
bundle = joblib.load("random_forest_production.joblib")
model, feature_cols = bundle["model"], bundle["feature_cols"]
p_reactive = model.predict_proba(X[feature_cols])[:, 1]

X must contain log-normalized expression for the 11 genes above, plus clone_size_norm (or 0.0 per cell if you have no TCR data — see repo README for the caveat on this fallback).

Limitations

• Trained on 9 patients from a single cohort/tissue context — validate on your own data before treating outputs as ground truth for a different tumor type or sequencing platform.
• Requires log-normalized expression (normalize_total + log1p); other normalizations are not equivalent.
• clone_size_norm is the single most important feature in this model (per SHAP analysis) — omitting real TCR data (imputing to 0.0) is a real degradation, not a free substitution.

License

MIT — see the GitHub repo for full license text.