#!/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)" )