Chara Survival: Thermodynamic OOD Survival Analysis Toolkit

Chara Survival is a production-grade, open-source computational toolkit engineered to solve out-of-distribution (OOD) generalization failure in clinical survival analysis. By grounding gene expression features in thermodynamic graph Laplacians derived from MARTINI 3 molecular dynamics (MD) exponential heat kernels, Chara bridges the notorious domain shift between RNA-seq (TCGA) and microarray platforms (GEO) without retraining model weights.

Executive Performance Summary

Standard machine learning and deep learning survival models collapse when transferred across sequencing platforms due to uncorrected variance and platform noise. Chara overcomes this structural barrier by encoding physical molecular interactions directly into the topological regularization path.

What Data Can Be Used? (Scope & Input Requirements)

Chara is specifically optimized for human Lung Adenocarcinoma (LUAD) transcriptomic profiling but can accommodate any bulk expression matrix that maps cleanly to the required feature space.

Supported Data Types & Platforms

• RNA-Seq Count Matrices: TPM or FPKM, preferably log2 transformed to match TCGA-LUAD scaling distributions.
• Microarray Expression Data: Affymetrix (including Human Genome U133 Plus 2.0 / GSE31210) and Illumina profiles normalized via standard scaling.
• Single-Cell / Pseudo-Bulk: Aggregated cell-type expression matrices mapped to HGNC gene symbols.

Strict Input Specifications

• Format: CSV or tab-separated files where rows are patients/samples and columns are HGNC gene symbols.
• Feature Intersection: Input matrices are aligned to the frozen 4,337-gene thermodynamic intersection signature in chara_model_4337.pkl. Missing genes are imputed to zero and extra features are dropped.
• Clinical Covariates (Optional): Tables containing patient age, gender, and AJCC tumor stage for multivariate survival validation.

How Anyone Can Use It

Installation

git clone https://github.com/your-username/chara-survival.git
cd chara-survival
pip install -r requirements.txt
pip install -e .

Programmatic Python API

import pandas as pd
from chara import CharaModel

model = CharaModel.load("chara_model_4337.pkl")
expression_matrix = pd.read_csv("patient_expression.csv", index_col=0)

risk_scores, scaled_matrix, aligned_df, scaler, alpha_index = model.predict(
    expression_matrix
)

print(f"Successfully processed {len(expression_matrix)} patients.")
print(f"Assigned Chara Risk Scores: {risk_scores[:5]}")

Gradio Application

Place chara_model_4337.pkl beside app.py, then launch:

python app.py

The interface accepts patient-by-gene CSV files and returns risk scores, survival curves, and a downloadable report.

Repository Architecture

chara-survival/
├── chara/
│   ├── __init__.py
│   ├── model.py               # Chara Coxnet wrapper and alignment engine
│   ├── graph.py               # Thermodynamic Laplacian and heat-kernel utilities
│   └── preprocessing.py       # Cross-platform StandardScaler pipeline
├── scripts/
│   ├── 01_to_11_pipeline.py   # Research execution scripts
│   └── benchmark_frontiers.py # DeepSurv/RSF/frontier comparison
├── requirements.txt           # Pinned production dependencies
├── setup.py                   # Package installation configuration
└── README.md                  # Technical documentation

Acknowledgments

This research and software architecture was developed by Sharon Melhi, under the guidance and mentorship of Dr. Kharerin Hungyo, who leads the Computational and Physical Genomics Lab at the Indian Institute of Technology Mandi.

Special thanks to Khushi Mhamane for continuous support and invaluable assistance in numerous ways that helped make the completion of this project possible.