amitpande74's picture
Update app.py
a8445f9 verified
Raw History Blame Contribute Delete
15.8 kB
#!/usr/bin/env python3
"""
Tissue VAE — Hugging Face Streamlit Space
Tissue-of-origin predictions from bulk RNA-seq expression using the
118,263-sample tissue-curated model (42 UBERON classes).
Two input routes use the same prediction function:
1. One-click demonstration with test_10samples.csv.
2. User-uploaded expression CSV/TSV.
The deployed INT8 TorchScript bundle returns classification logits.
The app therefore exports tissue predictions and probabilities, not
121-dimensional embeddings.
"""
import json
from pathlib import Path
import joblib
import numpy as np
import pandas as pd
import streamlit as st
import torch
APP_DIR = Path(__file__).resolve().parent
EXAMPLE_FILE = APP_DIR / "test_10samples.csv"
MODEL_FILE = APP_DIR / "vae_tissue_int8.torchscript.pt"
ARTIFACTS_FILE = APP_DIR / "vae_tissue.artifacts.joblib"
LABELS_FILE = APP_DIR / "label_mapping.json"
st.set_page_config(
page_title="Tissue VAE",
page_icon="🧬",
layout="wide",
)
@st.cache_resource(show_spinner="Loading the tissue model...")
def load_model():
"""Load the quantized classifier and the exact trained feature list."""
model = torch.jit.load(str(MODEL_FILE), map_location="cpu")
model.eval()
artifacts = joblib.load(ARTIFACTS_FILE)
gene_list = [str(g) for g in artifacts["feature_lists"]["gex"]]
scaler = artifacts["transforms"]["gex"]
label_mapping = {
int(k): v for k, v in json.loads(LABELS_FILE.read_text()).items()
}
return model, gene_list, scaler, label_mapping
def clear_previous_results():
"""Do not show predictions from a previous upload as if they were new."""
for key in ("prediction_results", "prediction_source", "prediction_overlap",
"prediction_n_genes", "prediction_warning",
"prediction_range", "prediction_filename"):
st.session_state.pop(key, None)
def read_expression_matrix(file_or_path, filename):
"""Read a comma- or tab-separated expression matrix."""
suffix = Path(filename).suffix.lower()
separator = "\t" if suffix in {".tsv", ".txt"} else ","
df = pd.read_csv(file_or_path, index_col=0, sep=separator)
if df.empty:
raise ValueError("The expression matrix is empty.")
df.columns = df.columns.map(str)
df.index = df.index.map(str)
return df
def orient_matrix(df, gene_list):
"""Return samples x genes, regardless of input orientation."""
known_genes = set(gene_list)
genes_in_columns = len(set(df.columns) & known_genes)
genes_in_rows = len(set(df.index) & known_genes)
if genes_in_rows > genes_in_columns:
return df.T
return df
def classify_expression(df, model, gene_list, scaler, label_mapping):
"""Run the same inference path for the example and uploaded data."""
df = orient_matrix(df, gene_list)
# Keep one column per gene if the uploaded expression matrix has duplicates.
if not df.columns.is_unique:
df = df.loc[:, ~df.columns.duplicated(keep="first")]
common = [gene for gene in gene_list if gene in df.columns]
overlap = len(common)
if overlap == 0:
raise ValueError(
"No model genes were found. Use HGNC gene symbols and check "
"the downloaded model gene list."
)
# Only expression values for matching model genes are used.
observed = df.loc[:, common].apply(pd.to_numeric, errors="coerce")
observed = observed.replace([np.inf, -np.inf], np.nan)
n_invalid = int(observed.isna().sum().sum())
if n_invalid:
observed = observed.fillna(0.0)
data_values = observed.to_numpy(dtype=np.float32)
p99 = float(np.percentile(data_values, 99))
vmax = float(np.max(data_values))
# Preserve the original Space's preprocessing convention:
# zero-fill missing model genes BEFORE applying the deposited scaler.
aligned = pd.DataFrame(
0.0, index=df.index, columns=gene_list, dtype=np.float32
)
aligned.loc[:, common] = data_values
x_scaled = scaler.transform(aligned.to_numpy(dtype=np.float32))
if not np.isfinite(x_scaled).all():
raise ValueError("Non-finite values remain after preprocessing.")
x = torch.from_numpy(np.asarray(x_scaled, dtype=np.float32))
with torch.inference_mode():
logits = model(x)
missing_class_index = {
label: idx for idx, label in label_mapping.items()
}.get("nan")
if missing_class_index is not None:
logits[:, missing_class_index] = -1e9
probabilities = torch.softmax(logits, dim=1)
indices = torch.argmax(probabilities, dim=1).cpu().numpy()
confidence = torch.max(probabilities, dim=1).values.cpu().numpy()
predictions = pd.DataFrame({
"Sample": df.index.tolist(),
"Tissue": [label_mapping[int(idx)] for idx in indices],
"Confidence": [f"{v:.1%}" for v in confidence],
})
warnings = []
if overlap < 1000:
warnings.append(
"Only a small number of model genes were detected. "
"Predictions may be unreliable."
)
if n_invalid:
warnings.append(
f"{n_invalid:,} missing/non-numeric expression values were "
"replaced with zeros."
)
if vmax > 30 or p99 > 25:
warnings.append(
"Values look larger than expected for log2-transformed expression. "
"Please verify that TPM/RPKM values have been log2-transformed."
)
return predictions, overlap, warnings, (p99, vmax)
st.title("🧬 Tissue VAE")
st.markdown(
"Predict tissue of origin from bulk RNA-seq using a supervised VAE "
"trained on **118,263 tissue-curated samples** (TCGA, GTEx, ARCHS4). "
"The model covers **42 UBERON tissue categories** and achieved "
"**94.9% balanced accuracy** on its held-out benchmark."
)
try:
model, gene_list, scaler, label_mapping = load_model()
except Exception as exc:
st.error(f"Cannot load model or artifacts: {exc}")
st.info(
"Check that the TorchScript model, .joblib artifacts, and "
"label_mapping.json are present in the Space repository root."
)
st.stop()
st.success(
f"Model ready · {len(gene_list):,} accepted genes · "
f"{len(label_mapping)} tissue classes · quantized VAE inference"
)
# ----------------------------------------------------------------------
# Option 1: One-click example, plus downloadable reference files
# ----------------------------------------------------------------------
st.markdown("---")
st.subheader("🧪 Try the built-in example")
st.write(
"**No upload required.** Run the included `test_10samples.csv` "
"through the model and download the predicted tissues."
)
example_col, download_col, genes_col = st.columns(3)
with example_col:
run_example = st.button(
"▶️ Run example — 10 samples",
key="run_example",
type="primary",
use_container_width=True,
disabled=not EXAMPLE_FILE.exists(),
)
with download_col:
if EXAMPLE_FILE.exists():
st.download_button(
"📥 Download example CSV",
data=EXAMPLE_FILE.read_bytes(),
file_name=EXAMPLE_FILE.name,
mime="text/csv",
key="download_example",
use_container_width=True,
)
else:
st.error("The example file is missing: test_10samples.csv")
with genes_col:
genes_csv = pd.DataFrame(
{"HGNC_gene_symbol": gene_list}
).to_csv(index=False).encode("utf-8")
st.download_button(
f"📥 Download model gene list ({len(gene_list):,})",
data=genes_csv,
file_name="flexynesis_model_genes.csv",
mime="text/csv",
key="download_gene_list",
use_container_width=True,
)
# ----------------------------------------------------------------------
# Option 2: Upload a new expression matrix
# ----------------------------------------------------------------------
st.markdown("---")
st.subheader("📁 Or upload your own expression data")
left, right = st.columns([2, 1])
with left:
uploaded = st.file_uploader(
"Upload expression matrix (CSV/TSV; genes × samples or samples × genes)",
type=["csv", "tsv", "txt"],
help="Use HGNC gene symbols and log2-transformed normalized expression.",
key="expression_file",
on_change=clear_previous_results,
)
run_uploaded = st.button(
"🚀 Classify uploaded data",
key="run_uploaded",
disabled=uploaded is None,
use_container_width=True,
)
with right:
st.markdown(
"**Expected input:**\n\n"
"- HGNC gene symbols\n"
"- Samples in rows **or** columns\n"
"- Log2-transformed normalized expression, e.g. `log2(TPM + 1)`\n"
"- Gene IDs must match the downloadable model gene list"
)
if uploaded is not None:
st.caption(f"Selected file: {uploaded.name}")
try:
uploaded.seek(0)
preview = read_expression_matrix(uploaded, uploaded.name)
st.dataframe(preview.iloc[:5, :5], use_container_width=True)
except Exception as exc:
st.error(f"Could not preview the uploaded file: {exc}")
# ----------------------------------------------------------------------
# Unified execution path and persistent results/download link
# ----------------------------------------------------------------------
if run_example or run_uploaded:
try:
if run_example:
raw_df = read_expression_matrix(EXAMPLE_FILE, EXAMPLE_FILE.name)
source_name = "Built-in example (test_10samples.csv)"
output_name = "flexynesis_example_predictions.csv"
else:
uploaded.seek(0)
raw_df = read_expression_matrix(uploaded, uploaded.name)
source_name = f"Uploaded file ({uploaded.name})"
output_name = "flexynesis_predictions.csv"
with st.spinner("Classifying tissues with the trained VAE..."):
predictions, overlap, warnings, value_range = classify_expression(
raw_df, model, gene_list, scaler, label_mapping
)
st.session_state["prediction_results"] = predictions
st.session_state["prediction_source"] = source_name
st.session_state["prediction_overlap"] = overlap
st.session_state["prediction_n_genes"] = len(gene_list)
st.session_state["prediction_warning"] = warnings
st.session_state["prediction_range"] = value_range
st.session_state["prediction_filename"] = output_name
except Exception as exc:
clear_previous_results()
st.error(f"Classification could not be completed: {exc}")
if "prediction_results" in st.session_state:
results = st.session_state["prediction_results"]
st.markdown("---")
st.subheader("📊 Tissue predictions")
st.write(
f"**Input:** {st.session_state['prediction_source']} \n"
f"**Samples analyzed:** {len(results):,} \n"
f"**Model gene overlap:** "
f"{st.session_state['prediction_overlap']:,}/"
f"{st.session_state['prediction_n_genes']:,}"
)
p99, vmax = st.session_state["prediction_range"]
st.caption(
f"Input expression values: 99th percentile = {p99:.2f}; "
f"maximum = {vmax:.2f}"
)
for warning in st.session_state["prediction_warning"]:
st.warning(warning)
st.dataframe(results, use_container_width=True, height=400)
st.subheader("Predicted tissue distribution")
n_tissues = int(results["Tissue"].nunique())
st.caption(
f"{len(results):,} samples · {n_tissues} predicted tissue "
f"{'category' if n_tissues == 1 else 'categories'}"
)
# Publication-style horizontal bars: readable names, gentle teal gradient,
# rounded corners, percentages, and interactive hover details.
# Uses Streamlit's built-in Vega-Lite renderer: no new dependencies.
tissue_counts = (
results["Tissue"]
.value_counts()
.rename_axis("Tissue")
.reset_index(name="Count")
)
tissue_counts["Tissue"] = (
tissue_counts["Tissue"].str.replace("_", " ", regex=False).str.title()
)
tissue_counts["Share"] = 100.0 * tissue_counts["Count"] / len(results)
tissue_counts["CountLabel"] = tissue_counts.apply(
lambda row: f"{int(row['Count'])} · {row['Share']:.0f}%",
axis=1,
)
max_count = int(tissue_counts["Count"].max())
chart_spec = {
"height": {"step": 42},
"padding": {"left": 5, "top": 8, "right": 56, "bottom": 8},
"encoding": {
"y": {
"field": "Tissue", "type": "nominal",
"sort": {"field": "Count", "order": "descending"},
"axis": {
"title": None, "labelFontSize": 12,
"labelColor": "#334155", "labelPadding": 12,
"labelLimit": 220, "ticks": False, "domain": False,
},
},
"x": {
"field": "Count", "type": "quantitative",
"scale": {"domain": [0, max_count * 1.38], "nice": False},
"axis": {
"title": "Number of samples", "titleColor": "#64748B",
"labelColor": "#64748B", "labelFontSize": 11,
"grid": True, "gridColor": "#E5EAF0",
"tickMinStep": 1, "domain": False, "tickColor": "#CBD5E1",
},
},
},
"layer": [
{
"mark": {
"type": "bar", "size": 20,
"cornerRadiusEnd": 10,
},
"encoding": {
"color": {
"field": "Count", "type": "quantitative",
"scale": {
"domain": [0, max_count],
"range": ["#87B8C4", "#12647A"],
},
"legend": None,
},
"tooltip": [
{"field": "Tissue", "type": "nominal", "title": "Tissue"},
{"field": "Count", "type": "quantitative", "title": "Samples"},
{"field": "Share", "type": "quantitative",
"title": "Share (%)", "format": ".1f"},
],
},
},
{
"mark": {
"type": "text", "align": "left", "baseline": "middle",
"dx": 11, "fontSize": 12, "fontWeight": "bold",
"color": "#1F394C",
},
"encoding": {
"text": {"field": "CountLabel", "type": "nominal"},
},
},
],
"config": {"view": {"stroke": None}},
}
st.vega_lite_chart(
tissue_counts, chart_spec,
use_container_width=True, theme=None,
)
st.download_button(
"📥 Download predictions (CSV)",
data=results.to_csv(index=False).encode("utf-8"),
file_name=st.session_state["prediction_filename"],
mime="text/csv",
key="download_predictions",
type="primary",
use_container_width=True,
)
st.success(
"Predictions are ready. Click the button above to save the CSV."
)
st.markdown("---")
st.caption(
"Tissue VAE · Akalin Lab / MDC-BIMSB · "
"118,263 training samples · 42 UBERON classes · "
"INT8 TorchScript model (predictions may differ slightly from "
"full-precision inference)."
)
st.markdown(
"📖 [Source code](https://github.com/BIMSBbioinfo/atlas_tissue_representation)"
" · 📦 [Model and artifacts on Zenodo](https://doi.org/10.5281/zenodo.20661013)"
)