Metadata-Version: 2.4
Name: chara-survival
Version: 0.1.5
Summary: Thermodynamic graph survival inference
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas==2.2.1
Requires-Dist: scikit-learn==1.4.1
Requires-Dist: scikit-survival==0.22.0
Requires-Dist: lifelines==0.28.0
Requires-Dist: joblib==1.3.2
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

| Model Architecture | OOD C-Index (GSE31210) | 1-Year AUC | 3-Year AUC | 5-Year AUC |
| --- | ---: | ---: | ---: | ---: |
| **Clinical Cox-PH (Age, Gender, Stage)** | 0.5000 | 0.5000 | 0.5000 | 0.5000 |
| **Random Survival Forest (RSF)** | 0.4041 | 0.4175 | 0.3657 | 0.4842 |
| **Elastic Net Coxnet (Raw 5,200 genes)** | 0.5248 | 0.4664 | 0.4081 | 0.2428 |
| **DeepSurv (Deep Neural Network)** | 0.5537 | 0.5465 | 0.3937 | 0.3122 |
| **Chara (Thermodynamic Laplacian)** | **0.7311** | **0.7463** | **0.7826** | **0.8195** |

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

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

### Programmatic Python API

```python
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:

```bash
python app.py
```

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

## Repository Architecture

```text
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.
