sigma-omics 0.1.0a1__tar.gz

sigma_omics-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sigma_omics-0.1.0a1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.ipynb_checkpoints/
+.venv/
+env/
+dist/
+build/
+*.egg-info/
+.DS_Store

sigma_omics-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bingxue Du
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sigma_omics-0.1.0a1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: sigma-omics
+Version: 0.1.0a1
+Summary: Spatial interface analysis for spatial metabolomics and transcriptomics
+Project-URL: Homepage, https://github.com/Elsa-bingxue/SIGMA
+Project-URL: Repository, https://github.com/Elsa-bingxue/SIGMA
+Project-URL: Issues, https://github.com/Elsa-bingxue/SIGMA/issues
+Author-email: Bingxue Du <dubingxue73@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: graph neural network,mass spectrometry imaging,spatial metabolomics,spatial omics,tumor boundary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: anndata>=0.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scanpy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Requires-Dist: torch-geometric>=2.5
+Requires-Dist: torch>=2.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# SIGMA (`sigma-omics`)
+
+SIGMA is a Python toolkit for spatial interface analysis integrating mass-spectrometry imaging (MSI) and spatial transcriptomic representations.
+
+> This package is currently an alpha release. Its scientific definitions are
+> preserved from the HBC515 reference implementation while the API and
+> multi-dataset validation are being completed.
+
+## Install
+
+After the first PyPI release:
+
+```bash
+pip install sigma-omics
+```
+
+The distribution name is `sigma-omics`; the Python import remains
+`sigma_spatial`.
+
+## Install from source
+
+```bash
+pip install -e .
+```
+
+## Minimal usage
+
+```python
+import scanpy as sc
+from sigma_spatial import SIGMA
+
+adata = sc.read_h5ad("sample.h5ad")
+SIGMA(seed=0).fit(
+    adata,
+    annotation_key="annotation",
+    tumor_label="Tumor",
+    stroma_label="Stroma",
+    rna_key="X_harmony",
+)
+
+# Main outputs
+adata.obs[["sigma_region_probability", "sigma_boundary", "sigma_d_signed"]]
+```
+
+## Scope
+
+The package should contain reusable SIGMA computation only. Manuscript-specific simulation, benchmarking, GO enrichment, plotting, and sample-specific analyses should live under `examples/` or a separate analysis repository.

sigma_omics-0.1.0a1/README.md

@@ -0,0 +1,47 @@
+# SIGMA (`sigma-omics`)
+
+SIGMA is a Python toolkit for spatial interface analysis integrating mass-spectrometry imaging (MSI) and spatial transcriptomic representations.
+
+> This package is currently an alpha release. Its scientific definitions are
+> preserved from the HBC515 reference implementation while the API and
+> multi-dataset validation are being completed.
+
+## Install
+
+After the first PyPI release:
+
+```bash
+pip install sigma-omics
+```
+
+The distribution name is `sigma-omics`; the Python import remains
+`sigma_spatial`.
+
+## Install from source
+
+```bash
+pip install -e .
+```
+
+## Minimal usage
+
+```python
+import scanpy as sc
+from sigma_spatial import SIGMA
+
+adata = sc.read_h5ad("sample.h5ad")
+SIGMA(seed=0).fit(
+    adata,
+    annotation_key="annotation",
+    tumor_label="Tumor",
+    stroma_label="Stroma",
+    rna_key="X_harmony",
+)
+
+# Main outputs
+adata.obs[["sigma_region_probability", "sigma_boundary", "sigma_d_signed"]]
+```
+
+## Scope
+
+The package should contain reusable SIGMA computation only. Manuscript-specific simulation, benchmarking, GO enrichment, plotting, and sample-specific analyses should live under `examples/` or a separate analysis repository.

sigma_omics-0.1.0a1/environment.yml

@@ -0,0 +1,21 @@
+name: sigma
+channels:
+  - pytorch
+  - pyg
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.10
+  - numpy
+  - pandas
+  - scipy
+  - scikit-learn
+  - matplotlib
+  - scanpy
+  - anndata
+  - pytorch
+  - pytorch-geometric
+  - pip
+  - pip:
+      - build
+      - twine

sigma_omics-0.1.0a1/examples/basic_usage.py

@@ -0,0 +1,7 @@
+import scanpy as sc
+from sigma_spatial import SIGMA
+
+adata = sc.read_h5ad("BC_515_Section_1.h5ad")
+model = SIGMA(n_components=64, k=15, seed=0)
+model.fit(adata, annotation_key="annotation", rna_key="X_harmony", epochs=1000)
+adata.write_h5ad("BC_515_SIGMA.h5ad")

sigma_omics-0.1.0a1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sigma-omics"
+version = "0.1.0a1"
+description = "Spatial interface analysis for spatial metabolomics and transcriptomics"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "Bingxue Du", email = "dubingxue73@gmail.com"}
+]
+keywords = ["spatial omics", "spatial metabolomics", "mass spectrometry imaging", "graph neural network", "tumor boundary"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scipy>=1.10",
+  "scikit-learn>=1.3",
+  "scanpy>=1.10",
+  "anndata>=0.10",
+  "torch>=2.1",
+  "torch-geometric>=2.5",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.8"]
+dev = ["build>=1.2", "twine>=5", "pytest>=8", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/Elsa-bingxue/SIGMA"
+Repository = "https://github.com/Elsa-bingxue/SIGMA"
+Issues = "https://github.com/Elsa-bingxue/SIGMA/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sigma_spatial"]

sigma_omics-0.1.0a1/scripts/build_hbc515_clean_notebooks.py

@@ -0,0 +1,333 @@
+"""Generate the four curated HBC_515 notebooks without touching the original."""
+
+import json
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+ORIGINAL = ROOT / "HBC_515" / "HBC_515_SIGMA.ipynb"
+OUT = ROOT / "HBC_515" / "clean"
+
+
+def md(text):
+    return {"cell_type": "markdown", "metadata": {}, "source": text.splitlines(True)}
+
+
+def code(text):
+    return {"cell_type": "code", "execution_count": None, "metadata": {},
+            "outputs": [], "source": text.splitlines(True)}
+
+
+def notebook(cells):
+    return {"cells": cells, "metadata": {"kernelspec": {"display_name": "Python 3",
+            "language": "python", "name": "python3"},
+            "language_info": {"name": "python", "version": "3.10"}},
+            "nbformat": 4, "nbformat_minor": 5}
+
+
+def write(name, cells):
+    OUT.mkdir(parents=True, exist_ok=True)
+    (OUT / name).write_text(json.dumps(notebook(cells), indent=1) + "\n")
+
+
+def source_cell(original, index):
+    cell = original["cells"][index]
+    return code("".join(cell.get("source", [])))
+
+
+common_setup = '''from pathlib import Path
+import sys
+
+PROJECT_ROOT = Path.cwd().resolve().parents[1]
+PACKAGE_SRC = PROJECT_ROOT / "sigma_spatial_pypi_starter" / "src"
+if str(PACKAGE_SRC) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_SRC))
+
+DATA_DIR = PROJECT_ROOT / "HBC_515"
+RESULT_DIR = DATA_DIR / "clean" / "results"
+FIGURE_DIR = RESULT_DIR / "figures"
+RESULT_DIR.mkdir(parents=True, exist_ok=True)
+FIGURE_DIR.mkdir(parents=True, exist_ok=True)
+'''
+
+
+def build_core():
+    cells = [
+        md("# HBC_515 — SIGMA core\n\nClean reference workflow derived from original cells 0–43. The original notebook is not modified. Mathematical definitions, graph direction, probability normalization, thresholds, architecture, and hyperparameters are preserved."),
+        md("## 1. Environment and paths"), code(common_setup + '''\nimport scanpy as sc
+from sigma_spatial import SIGMA
+from sigma_spatial.plotting import set_publication_style
+
+set_publication_style()
+SEED = 0
+'''),
+        md("## 2. Load HBC_515"), code('''adata = sc.read_h5ad(DATA_DIR / "BC_515_Section_1.h5ad")
+print(adata)
+print("MSI storage:", "uns[msi]" if "msi" in adata.uns else "layers[raw]" if "raw" in adata.layers else "X")
+'''),
+        md("## 3. Fit the preserved SIGMA model\n\nThis calls extracted package functions that match original cells 4–12. Training is intentionally not executed when this notebook is generated."),
+        code('''sigma = SIGMA(n_components=64, k=15, seed=SEED)
+sigma.fit(
+    adata,
+    annotation_key="annotation",
+    tumor_label="Tumor",
+    stroma_label="Stroma",
+    rna_key="X_harmony",
+    z_dim=32,
+    epochs=1000,
+    lr=1e-3,
+    lambda_sup=0.05,
+    beta_rna=0.05,
+    boundary_k=10,
+)
+'''),
+        md("## 4. Essential boundary QC"), code('''import matplotlib.pyplot as plt
+from sigma_spatial.plotting import figure_size, save_figure, shared_colorbar, style_spatial_axis
+
+xy = adata.obsm["spatial"]
+fig, axes = plt.subplots(1, 3, figsize=figure_size("double"), constrained_layout=True)
+items = [
+    ("sigma_region_probability", "Region probability", "viridis"),
+    ("sigma_boundary", "Boundary", "Greys"),
+    ("sigma_d_signed", "Signed distance", "coolwarm"),
+]
+for ax, (key, title, cmap) in zip(axes, items):
+    artist = ax.scatter(xy[:, 0], xy[:, 1], c=adata.obs[key], s=5, cmap=cmap, rasterized=True)
+    ax.set_title(title)
+    style_spatial_axis(ax)
+    fig.colorbar(artist, ax=ax, shrink=0.72)
+save_figure(fig, FIGURE_DIR / "HBC515_SIGMA_core_QC", formats=("pdf", "svg", "png"))
+'''),
+        md("## 5. Persist essential outputs"), code('''output_path = RESULT_DIR / "HBC515_SIGMA_core.h5ad"
+adata.write_h5ad(output_path)
+print(output_path)
+'''),
+        md("## 6. Interface profiles, lambda, and metabolite ranking\n\nThe original lambda/ranking implementations have multiple variants. Until golden numerical tables are frozen, cells 21–43 remain provenance-locked and are not silently replaced by the simplified starter implementation. Run the migration cells below only after the core result exists."),
+    ]
+    return cells
+
+
+def build_simulation(original):
+    cells = [
+        md("# HBC_515 — simulation\n\nDerived from original cells 44–61. Simulation generation is imported from the package; metric and selection definitions below remain verbatim pending their next extraction test."),
+        md("## 1. Environment and core result"), code(common_setup + '''\nimport numpy as np
+import pandas as pd
+import anndata as ad
+import matplotlib.pyplot as plt
+from scipy.stats import mannwhitneyu, spearmanr
+from sklearn.linear_model import LinearRegression
+from sklearn.metrics import average_precision_score, roc_auc_score
+from sklearn.preprocessing import StandardScaler
+from sigma_spatial.simulation import (
+    evaluate_simulation_feature_selection,
+    simulate_interface_features,
+    zscore_vec,
+)
+from sigma_spatial.plotting import add_panel_labels, figure_size, save_figure, set_publication_style, style_spatial_axis
+set_publication_style()
+adata = ad.read_h5ad(RESULT_DIR / "HBC515_SIGMA_core.h5ad")
+coords = np.asarray(adata.obsm["spatial"])
+d_signed = adata.obs["sigma_d_signed"].to_numpy(float)
+d_abs = np.abs(d_signed)
+tumor_mask = adata.obs["sigma_inside"].to_numpy(bool)
+'''),
+        md("## 2. Preserved feature metrics and selection"),
+        source_cell(original, 47), source_cell(original, 48), source_cell(original, 50),
+        md("## 3. Representative simulation example"), code('''X_sim, meta_rows = simulate_interface_features(
+    d_abs=d_abs, d_signed=d_signed, coords=coords, tumor_mask=tumor_mask,
+    n_positive=1, n_negative=1, n_region_only=1, n_spatial_background=0,
+    n_noise=1, effect_size=0.25, noise_sd=0.5, lam=100,
+    random_state=0,
+)
+meta = pd.DataFrame(meta_rows)
+metrics = compute_boundary_feature_metrics(X_sim, d_abs, d_signed=d_signed, tumor_mask=tumor_mask)
+metrics = metrics.merge(meta, on="j", how="left", suffixes=("", "_truth"))
+metrics = add_region_adjusted_distance_metrics(
+    df_metrics=metrics, X=X_sim, d_abs=d_abs, tumor_mask=tumor_mask
+)
+selected = select_positive_negative_interface_features_strict(metrics)
+display(selected[["mz", "sim_type", "true_direction", "pred_direction", "is_selected_boundary", "auc", "decay_r2"]])
+
+examples = [
+    selected[selected["sim_type"] == "positive_boundary"].iloc[0],
+    selected[selected["sim_type"] == "negative_boundary"].iloc[0],
+]
+fig, axes = plt.subplots(2, 3, figsize=(9.2, 6.2), constrained_layout=True)
+column_titles = ["Ground-truth pattern", "Simulated observation (with noise)",
+                 "SIGMA-recovered pattern"]
+for row_index, row in enumerate(examples):
+    j = int(row["j"])
+    true_lambda = float(row["true_lambda"])
+    lambda_hat = float(row["lambda_hat"]) if np.isfinite(row["lambda_hat"]) else true_lambda
+    decay_true = np.exp(-d_abs / (true_lambda + 1e-8))
+    decay_hat = np.exp(-d_abs / (lambda_hat + 1e-8))
+    if row["sim_type"] == "positive_boundary":
+        true_signal, recovered_signal = decay_true, decay_hat
+        auc_display = float(row["auc"])
+        row_label = "Positive"
+    else:
+        true_signal, recovered_signal = 1.0 - decay_true, 1.0 - decay_hat
+        auc_display = float(row["auc_neg"])
+        row_label = "Negative"
+    for col_index, values in enumerate([true_signal, X_sim[:, j], recovered_signal]):
+        ax = axes[row_index, col_index]
+        artist = ax.scatter(coords[:, 0], coords[:, 1], c=values, s=5,
+                            cmap="viridis", rasterized=True)
+        fig.colorbar(artist, ax=ax, shrink=0.72)
+        if row_index == 0:
+            ax.set_title(column_titles[col_index])
+        style_spatial_axis(ax)
+    axes[row_index, 0].set_ylabel(
+        f"{row_label}\\nAUC={auc_display:.3f}; decay R²={row['decay_r2']:.3f}\\n"
+        f"λ true={true_lambda:.1f}; λ estimated={lambda_hat:.1f}",
+        fontsize=8,
+    )
+fig.suptitle("Representative positive and negative interface simulations")
+save_figure(fig, FIGURE_DIR / "HBC515_representative_simulation_positive_negative",
+            formats=("pdf", "svg", "png"))
+'''),
+        md("## 4. Effect-size and sensitivity grid"), source_cell(original, 53),
+        code('''eval_all_strict, detail_all_strict = run_sensitivity_analysis_strict(
+    d_abs=d_abs, d_signed=d_signed, coords=coords, tumor_mask=tumor_mask,
+    effect_sizes=[0.25, 0.5, 1.0, 2.0], noise_sds=[0.5],
+    lambdas=[200], n_repeats=1, n_positive=100,
+    n_negative=100, n_region_only=300, n_spatial_background=300,
+    n_noise=500, random_seed=0, p_cutoff=0.05, decay_r2_cutoff=0.05,
+    auc_pos_cutoff=0.65, auc_neg_cutoff=0.35,
+)
+eval_all_strict.to_csv(RESULT_DIR / "HBC515_simulation_recovery.csv", index=False)
+detail_all_strict.to_pickle(RESULT_DIR / "HBC515_simulation_detail.pkl")
+'''),
+    ]
+    return cells
+
+
+def build_benchmark():
+    return [
+        md("# HBC_515 — benchmark\n\nBenchmark workflow derived from original cells 62–104. It consumes frozen core and simulation outputs and adds an explicit ROC curve that was absent from the original notebook."),
+        md("## 1. Environment and preserved outputs"), code(common_setup + '''\nimport numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn.metrics import auc, average_precision_score, precision_recall_curve, roc_curve
+from sigma_spatial.plotting import add_panel_labels, figure_size, legend_outside, save_figure, set_publication_style
+from sigma_spatial.simulation import recovery_curve_data
+set_publication_style()
+recovery = pd.read_csv(RESULT_DIR / "HBC515_simulation_recovery.csv")
+detail = pd.read_pickle(RESULT_DIR / "HBC515_simulation_detail.pkl")
+'''),
+        md("## 2. Effect-size sensitivity ROC curves\n\nThis is the requested effect-size figure: noise SD, interface width λ, and replicate are fixed, while four effect sizes are compared on the same ROC axes."), code('''from sklearn.metrics import roc_auc_score
+
+NOISE_SD = 0.5
+LAMBDA = 200
+REP = 0
+EFFECT_SIZES = [0.25, 0.5, 1.0, 2.0]
+curve_data = detail[
+    (detail["noise_sd"] == NOISE_SD)
+    & (detail["lambda"] == LAMBDA)
+    & (detail["rep"] == REP)
+].copy()
+
+fig, ax = plt.subplots(figsize=(7.2, 5.4), constrained_layout=True)
+colors = ["#0072B2", "#E69F00", "#009E73", "#D55E00"]
+for effect_size, color in zip(EFFECT_SIZES, colors):
+    subset = curve_data[curve_data["effect_size"] == effect_size]
+    curves = recovery_curve_data(subset)
+    ax.plot(
+        curves["fpr"], curves["tpr"], color=color, lw=2,
+        label=f"Effect={effect_size:g} (AUROC={curves['auroc']:.3f})",
+    )
+ax.plot([0, 1], [0, 1], ls="--", lw=1.2, color="#8A5AC2", label="Random")
+ax.set(
+    xlabel="False Positive Rate", ylabel="True Positive Rate",
+    xlim=(0, 1), ylim=(0, 1.02),
+    title=f"Effect-size sensitivity\\nNoise SD={NOISE_SD:g}, λ={LAMBDA}, Rep={REP}",
+)
+ax.legend(loc="lower right", frameon=True, framealpha=0.95)
+ax.spines["top"].set_visible(False)
+ax.spines["right"].set_visible(False)
+save_figure(fig, FIGURE_DIR / "HBC515_effect_size_sensitivity_ROC", formats=("pdf", "svg", "png"))
+
+auc_summary = recovery[
+    (recovery["noise_sd"] == NOISE_SD)
+    & (recovery["lambda"] == LAMBDA)
+    & (recovery["rep"] == REP)
+].sort_values("effect_size")
+fig, ax = plt.subplots(figsize=(4.8, 3.8), constrained_layout=True)
+bars = ax.bar(
+    auc_summary["effect_size"].astype(str), auc_summary["auroc"],
+    color=colors, width=0.72,
+)
+for bar, value in zip(bars, auc_summary["auroc"]):
+    ax.annotate(f"{value:.3f}",
+                (bar.get_x() + bar.get_width() / 2, bar.get_height()),
+                xytext=(0, 3), textcoords="offset points",
+                ha="center", va="bottom", fontsize=8)
+ax.set(
+    xlabel="Effect size", ylabel="AUROC", ylim=(0, 1.07),
+    title=f"Effect-size sensitivity of AUROC\\nNoise SD={NOISE_SD:g}, λ={LAMBDA}, Rep={REP}",
+)
+ax.spines["top"].set_visible(False)
+ax.spines["right"].set_visible(False)
+save_figure(fig, FIGURE_DIR / "HBC515_effect_size_AUROC", formats=("pdf", "svg", "png"))
+'''),
+        md("## 3. AUROC, ROC curve, and AUPRC/AP\n\nThe scalar definitions are unchanged from original cell 49. The ROC/PR curves are new visualizations of the same truth labels and continuous scores."),
+        code('''example = detail[(detail["effect_size"] == 1.0) & (detail["noise_sd"] == 0.5) & (detail["lambda"] == 200) & (detail["rep"] == 0)].copy()
+curves = recovery_curve_data(example)
+precision, recall, _ = precision_recall_curve(curves["truth"], curves["score"])
+ap = average_precision_score(curves["truth"], curves["score"])
+fig, axes = plt.subplots(1, 2, figsize=figure_size("double"), constrained_layout=True)
+axes[0].plot(curves["fpr"], curves["tpr"], label=f"SIGMA AUROC={curves['auroc']:.3f}")
+axes[0].plot([0, 1], [0, 1], ls="--", color="0.6")
+axes[0].set(xlabel="False-positive rate", ylabel="True-positive rate", title="ROC curve", xlim=(0, 1), ylim=(0, 1))
+axes[1].plot(recall, precision, label=f"SIGMA AP={ap:.3f}")
+axes[1].set(xlabel="Recall", ylabel="Precision", title="Precision–recall curve", xlim=(0, 1), ylim=(0, 1))
+for ax in axes: ax.legend(frameon=False, loc="lower right")
+add_panel_labels(axes)
+save_figure(fig, FIGURE_DIR / "HBC515_ROC_AUPRC", formats=("pdf", "svg", "png"))
+'''),
+        md("## 4. Comparison methods\n\nThe MET-MAP, SpatialDE, Region-DE, top-k, and overlap implementations remain provenance-locked in original cells 63–102. They require optional dependencies and frozen intermediate tables before safe extraction. The existing HBC_515 slide summaries can be inspected without overwriting them."),
+        code('''slide_summary = PROJECT_ROOT / "4 slides" / "BC_515_topk_500_summary.csv"
+if slide_summary.exists():
+    benchmark_summary = pd.read_csv(slide_summary)
+    display(benchmark_summary)
+else:
+    print("Missing slide benchmark summary:", slide_summary)
+'''),
+    ]
+
+
+def build_biology(original):
+    cells = [
+        md("# HBC_515 — biological interpretation and manuscript figures\n\nCurated from original cells 105–156. This notebook consumes a completed core result; it does not retrain SIGMA. Long duplicated plotting implementations are intentionally not copied."),
+        md("## 1. Environment and core result"), code(common_setup + '''\nimport numpy as np
+import pandas as pd
+import anndata as ad
+import matplotlib.pyplot as plt
+from sigma_spatial.plotting import add_panel_labels, figure_size, save_figure, set_publication_style, style_spatial_axis
+set_publication_style()
+adata = ad.read_h5ad(RESULT_DIR / "HBC515_SIGMA_core.h5ad")
+coords = np.asarray(adata.obsm["spatial"])
+d_signed = adata.obs["sigma_d_signed"].to_numpy(float)
+'''),
+        md("## 2. Transition thickness"), source_cell(original, 106), source_cell(original, 107),
+        md("## 3. Region-only versus boundary association"), source_cell(original, 109),
+        md("## 4. Real-data validation"), source_cell(original, 116), source_cell(original, 117),
+        md("## 5. Metabolic clusters and representative profiles"), source_cell(original, 120), source_cell(original, 121), source_cell(original, 122),
+        md("## 6. Near-versus-far and RNA signatures"), source_cell(original, 130), source_cell(original, 134),
+        md("## 7. Heatmaps"), source_cell(original, 136), source_cell(original, 138),
+        md("## 8. GO enrichment"), source_cell(original, 148), source_cell(original, 149), source_cell(original, 150),
+        md("## Migration note\n\nCells 125–129, 131–133, 135, 137, 139–146, and 151–156 contain alternative or duplicated plotting implementations and were not copied. They remain available unchanged in the original notebook pending numerical fixture creation."),
+    ]
+    return cells
+
+
+def main():
+    original = json.loads(ORIGINAL.read_text())
+    write("01_HBC515_SIGMA_core.ipynb", build_core())
+    write("02_HBC515_simulation.ipynb", build_simulation(original))
+    write("03_HBC515_benchmark.ipynb", build_benchmark())
+    write("04_HBC515_biology_figures.ipynb", build_biology(original))
+
+
+if __name__ == "__main__":
+    main()

sigma_omics-0.1.0a1/src/sigma_spatial/__init__.py

@@ -0,0 +1,22 @@
+"""SIGMA: spatial interface analysis for spatial metabolomics and transcriptomics."""
+from .preprocessing import get_msi_matrix, msi_to_embedding
+from .boundary import (
+    build_boundary_from_binary_mask,
+    build_boundary_from_field,
+    signed_distance_from_boundary_points,
+)
+
+__version__ = "0.1.0a1"
+__all__ = [
+    "SIGMA", "get_msi_matrix", "msi_to_embedding",
+    "build_boundary_from_binary_mask", "build_boundary_from_field",
+    "signed_distance_from_boundary_points",
+]
+
+
+def __getattr__(name):
+    """Keep light-weight utilities importable without the optional torch stack."""
+    if name == "SIGMA":
+        from .pipeline import SIGMA
+        return SIGMA
+    raise AttributeError(name)

sigma_omics-0.1.0a1/src/sigma_spatial/boundary.py

@@ -0,0 +1,36 @@
+import numpy as np
+from sklearn.neighbors import NearestNeighbors
+
+
+def build_boundary_from_binary_mask(xy, inside_mask, k_nn=10):
+    """Return the reference notebook's same-and-opposite-neighbour boundary."""
+    xy = np.asarray(xy, dtype=float)
+    inside = np.asarray(inside_mask, dtype=bool)
+    k_nn = min(int(k_nn), xy.shape[0] - 1)
+    nn = NearestNeighbors(n_neighbors=k_nn + 1).fit(xy)
+    idx = nn.kneighbors(xy, return_distance=False)[:, 1:]
+    same = np.any(inside[idx] == inside[:, None], axis=1)
+    opposite = np.any(inside[idx] != inside[:, None], axis=1)
+    return same & opposite
+
+
+def build_boundary_from_field(xy, field, level=0.5, k_nn=10):
+    """Threshold a continuous field and construct the reference boundary."""
+    field = np.asarray(field, dtype=float)
+    if not np.all(np.isfinite(field)):
+        raise ValueError("The boundary-defining field contains non-finite values.")
+    inside = field >= float(level)
+    boundary = build_boundary_from_binary_mask(xy, inside, k_nn=k_nn)
+    return boundary, inside
+
+
+def signed_distance_from_boundary_points(xy, boundary_mask, inside_mask):
+    """Distance to nearest boundary point; tumor/inside side negative, outside positive."""
+    xy = np.asarray(xy, dtype=float)
+    b = np.asarray(boundary_mask, dtype=bool)
+    inside = np.asarray(inside_mask, dtype=bool)
+    if not np.any(b):
+        raise ValueError("No boundary points were detected.")
+    nn = NearestNeighbors(n_neighbors=1).fit(xy[b])
+    dist = nn.kneighbors(xy, return_distance=True)[0][:, 0]
+    return np.where(inside, -dist, dist)

sigma_omics-0.1.0a1/src/sigma_spatial/graph.py

@@ -0,0 +1,76 @@
+import numpy as np
+from sklearn.neighbors import NearestNeighbors
+
+
+def gaussian_knn_graph(xy, k=15, sigma=None, symmetrize=False):
+    """Build the Gaussian-weighted spatial kNN graph used by SIGMA.
+
+    The reference notebooks use directed ``i -> neighbour`` edges.  The
+    ``symmetrize`` option is retained for experiments, but is deliberately
+    disabled by default to preserve the published notebook behaviour.
+    """
+    xy = np.asarray(xy, dtype=np.float32)
+    if xy.ndim != 2 or xy.shape[1] < 2:
+        raise ValueError("xy must have shape (n_spots, >=2).")
+    k = min(int(k), xy.shape[0] - 1)
+    nn = NearestNeighbors(n_neighbors=k + 1).fit(xy)
+    dist, idx = nn.kneighbors(xy)
+    dist, idx = dist[:, 1:], idx[:, 1:]
+    if sigma is None:
+        sigma = float(np.median(dist[dist > 0]))
+    sigma = max(float(sigma), 1e-12)
+    w = np.exp(-(dist ** 2) / (2 * sigma ** 2)).astype(np.float32)
+    src = np.repeat(np.arange(xy.shape[0]), k)
+    dst = idx.reshape(-1)
+    ew = w.reshape(-1)
+    if symmetrize:
+        src0, dst0, ew0 = src, dst, ew
+        src = np.concatenate([src0, dst0])
+        dst = np.concatenate([dst0, src0])
+        ew = np.concatenate([ew0, ew0])
+        # merge duplicate edges by maximum weight
+        key = src.astype(np.int64) * xy.shape[0] + dst.astype(np.int64)
+        order = np.argsort(key)
+        key, src, dst, ew = key[order], src[order], dst[order], ew[order]
+        starts = np.r_[0, np.flatnonzero(np.diff(key)) + 1]
+        src = src[starts]
+        dst = dst[starts]
+        ew = np.maximum.reduceat(ew, starts)
+    return np.vstack([src, dst]).astype(np.int64), ew.astype(np.float32), sigma
+
+
+def gaussian_label_smoothing(edge_index, edge_weight, y, labeled_mask,
+                             n_iter=50, alpha=0.85):
+    """Diffuse binary anchors while clamping labeled nodes each iteration."""
+    y = np.asarray(y)
+    labeled_mask = np.asarray(labeled_mask, dtype=bool)
+    n = y.shape[0]
+    field = np.zeros(n, dtype=np.float32)
+    field[labeled_mask] = y[labeled_mask].astype(np.float32)
+    anchor = field.copy()
+    src, dst = np.asarray(edge_index)
+    degree = np.zeros(n, dtype=np.float32)
+    np.add.at(degree, src, edge_weight)
+    degree = np.maximum(degree, 1e-12)
+    for _ in range(int(n_iter)):
+        message = np.zeros(n, dtype=np.float32)
+        np.add.at(message, src, edge_weight * field[dst])
+        updated = alpha * message / degree + (1.0 - alpha) * anchor
+        updated[labeled_mask] = anchor[labeled_mask]
+        field = updated
+    return field
+
+
+def smooth_embedding(edge_index, edge_weight, e, n_iter=10, alpha=0.9):
+    """Spatial diffusion of an embedding on a weighted graph."""
+    e = np.asarray(e, dtype=np.float32)
+    f = e.copy()
+    src, dst = edge_index
+    deg = np.zeros(e.shape[0], dtype=np.float32)
+    np.add.at(deg, src, edge_weight)
+    deg = np.maximum(deg, 1e-12)
+    for _ in range(int(n_iter)):
+        msg = np.zeros_like(f)
+        np.add.at(msg, src, edge_weight[:, None] * f[dst])
+        f = alpha * msg / deg[:, None] + (1.0 - alpha) * e
+    return f

sigma_omics-0.1.0a1/src/sigma_spatial/metrics.py

@@ -0,0 +1,22 @@
+import numpy as np
+from scipy.stats import spearmanr
+
+
+def boundary_enrichment_score(values, d_signed, width):
+    """Mean interface signal relative to the remaining tissue."""
+    x = np.asarray(values, dtype=float)
+    d = np.asarray(d_signed, dtype=float)
+    near = np.abs(d) <= float(width)
+    valid = np.isfinite(x) & np.isfinite(d)
+    if (near & valid).sum() < 3 or ((~near) & valid).sum() < 3:
+        return np.nan
+    return float(np.nanmean(x[near & valid]) - np.nanmean(x[(~near) & valid]))
+
+
+def distance_association(values, d_signed):
+    x = np.asarray(values, dtype=float)
+    d = np.asarray(d_signed, dtype=float)
+    valid = np.isfinite(x) & np.isfinite(d)
+    if valid.sum() < 3:
+        return np.nan, np.nan
+    return spearmanr(np.abs(d[valid]), x[valid])

sigma_omics-0.1.0a1/src/sigma_spatial/model.py

@@ -0,0 +1,58 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch_geometric.nn import MessagePassing
+from torch_geometric.utils import add_self_loops, degree
+
+
+class GraphLowPass(MessagePassing):
+    def __init__(self):
+        super().__init__(aggr="add")
+
+    def forward(self, x, edge_index, edge_weight=None):
+        n = x.size(0)
+        if edge_weight is None:
+            edge_weight = torch.ones(edge_index.size(1), device=x.device, dtype=x.dtype)
+        edge_index, edge_weight = add_self_loops(edge_index, edge_weight, fill_value=1.0, num_nodes=n)
+        row, col = edge_index
+        # Preserve the normalization used in all reference notebooks.
+        deg = degree(col, n, dtype=x.dtype)
+        deg_inv_sqrt = deg.pow(-0.5)
+        deg_inv_sqrt[torch.isinf(deg_inv_sqrt)] = 0
+        norm = deg_inv_sqrt[row] * edge_weight * deg_inv_sqrt[col]
+        return self.propagate(edge_index, x=x, norm=norm)
+
+    def message(self, x_j, norm):
+        return norm.view(-1, 1) * x_j
+
+
+class SpectralHighPassBlock(nn.Module):
+    def __init__(self, in_dim, out_dim, dropout=0.1):
+        super().__init__()
+        self.lowpass = GraphLowPass()
+        self.lin = nn.Linear(in_dim, out_dim)
+        self.norm = nn.LayerNorm(out_dim)
+        self.dropout = nn.Dropout(dropout)
+
+    def forward(self, x, edge_index, edge_weight=None):
+        hp = x - self.lowpass(x, edge_index, edge_weight)
+        return self.dropout(F.relu(self.norm(self.lin(hp))))
+
+
+class SpectralResidualNet(nn.Module):
+    def __init__(self, in_dim, hidden=128, out_dim=64, r_dim=None, z_dim=32, use_region_head=True):
+        super().__init__()
+        r_dim = in_dim if r_dim is None else r_dim
+        self.hp1 = SpectralHighPassBlock(in_dim, hidden)
+        self.hp2 = SpectralHighPassBlock(hidden, out_dim)
+        self.residual_head = nn.Linear(out_dim, r_dim)
+        self.rna_head = nn.Linear(out_dim, z_dim)
+        self.use_region_head = use_region_head
+        self.region_head = nn.Linear(out_dim, 1) if use_region_head else None
+
+    def forward(self, x, edge_index, edge_weight=None):
+        h = self.hp2(self.hp1(x, edge_index, edge_weight), edge_index, edge_weight)
+        out = {"r": self.residual_head(h), "z_hat": self.rna_head(h), "h": h}
+        if self.region_head is not None:
+            out["logit"] = self.region_head(h).squeeze(-1)
+        return out

sigma_omics-0.1.0a1/src/sigma_spatial/pipeline.py

@@ -0,0 +1,105 @@
+import numpy as np
+import torch
+import torch.nn.functional as F
+from torch_geometric.data import Data
+from .preprocessing import get_msi_matrix, msi_to_embedding
+from .graph import gaussian_knn_graph, gaussian_label_smoothing, smooth_embedding
+from .model import SpectralResidualNet
+from .boundary import build_boundary_from_field, signed_distance_from_boundary_points
+from .utils import set_seed
+
+
+class SIGMA:
+    """Minimal end-to-end SIGMA estimator.
+
+    Core workflow only: MSI embedding -> spatial graph -> Gaussian low-pass prior ->
+    spectral residual learning -> region field -> boundary -> signed distance.
+    """
+    def __init__(self, n_components=64, k=15, seed=0, device=None):
+        self.n_components = n_components
+        self.k = k
+        self.seed = seed
+        self.device = torch.device(device or ("cuda" if torch.cuda.is_available() else "cpu"))
+
+    def fit(self, adata, annotation_key="annotation", tumor_label="Tumor", stroma_label="Stroma",
+            rna_key="X_harmony", z_dim=32, epochs=1000, lr=1e-3,
+            lambda_sup=0.05, beta_rna=0.05, boundary_k=10):
+        set_seed(self.seed)
+        if "spatial" not in adata.obsm:
+            raise KeyError("adata.obsm['spatial'] is required")
+        if annotation_key not in adata.obs:
+            raise KeyError(f"adata.obs[{annotation_key!r}] is required")
+        if rna_key not in adata.obsm:
+            raise KeyError(f"adata.obsm[{rna_key!r}] is required")
+
+        xy = np.asarray(adata.obsm["spatial"], dtype=np.float32)
+        ann = adata.obs[annotation_key].astype(str).to_numpy()
+        x_msi = get_msi_matrix(adata)
+        e = msi_to_embedding(x_msi, self.n_components, self.seed)
+        edge_index, edge_w, sigma = gaussian_knn_graph(xy, self.k, symmetrize=False)
+        e_gauss = smooth_embedding(edge_index, edge_w, e)
+        r_target = e - e_gauss
+
+        y = np.full(adata.n_obs, -1, dtype=np.int64)
+        y[ann == tumor_label] = 1
+        y[ann == stroma_label] = 0
+        mask = y >= 0
+        if not np.any(y[mask] == 1) or not np.any(y[mask] == 0):
+            raise ValueError("Both tumor and stroma anchors are required.")
+        f_gauss = gaussian_label_smoothing(
+            edge_index, edge_w, y, mask, n_iter=50, alpha=0.85
+        )
+
+        z = np.asarray(adata.obsm[rna_key][:, :z_dim], dtype=np.float32)
+        z = (z - z.mean(0)) / (z.std(0) + 1e-6)
+        data = Data(
+            x=torch.tensor(e_gauss, dtype=torch.float32),
+            edge_index=torch.tensor(edge_index, dtype=torch.long),
+            edge_attr=torch.tensor(edge_w, dtype=torch.float32),
+        ).to(self.device)
+        r_t = torch.tensor(r_target, dtype=torch.float32, device=self.device)
+        z_t = torch.tensor(z, dtype=torch.float32, device=self.device)
+        idx = torch.tensor(np.where(mask)[0], dtype=torch.long, device=self.device)
+        y_t = torch.tensor(y[mask], dtype=torch.float32, device=self.device)
+
+        self.model_ = SpectralResidualNet(e.shape[1], hidden=128, out_dim=e.shape[1], r_dim=e.shape[1], z_dim=z.shape[1]).to(self.device)
+        opt = torch.optim.Adam(self.model_.parameters(), lr=lr, weight_decay=1e-4)
+        pos, neg = (y[mask] == 1).sum(), (y[mask] == 0).sum()
+        bce_weight = torch.tensor([neg / max(pos, 1)], dtype=torch.float32, device=self.device)
+
+        self.loss_history_ = []
+        for _ in range(int(epochs)):
+            self.model_.train(); opt.zero_grad()
+            out = self.model_(data.x, data.edge_index, data.edge_attr)
+            loss_rec = F.smooth_l1_loss(out["r"], r_t)
+            loss_sup = F.binary_cross_entropy_with_logits(out["logit"][idx], y_t, pos_weight=bce_weight)
+            loss_rna = F.mse_loss(out["z_hat"], z_t)
+            loss = loss_rec + lambda_sup * loss_sup + beta_rna * loss_rna
+            loss.backward(); opt.step()
+            self.loss_history_.append(float(loss.detach().cpu()))
+
+        self.model_.eval()
+        with torch.no_grad():
+            out = self.model_(data.x, data.edge_index, data.edge_attr)
+            r = out["r"].cpu().numpy()
+            p_raw = torch.sigmoid(out["logit"]).cpu().numpy()
+            p = (p_raw - np.nanmin(p_raw)) / (
+                np.nanmax(p_raw) - np.nanmin(p_raw) + 1e-8
+            )
+
+        boundary, inside = build_boundary_from_field(xy, p, level=0.5, k_nn=boundary_k)
+        d_signed = signed_distance_from_boundary_points(xy, boundary, inside)
+
+        adata.obsm["X_sigma_msi"] = e
+        adata.obsm["X_sigma_gauss"] = e_gauss
+        adata.obsm["X_sigma_residual"] = r
+        adata.obsm["X_sigma_corrected"] = e_gauss + r
+        adata.obs["sigma_gaussian_anchor"] = f_gauss
+        adata.obs["sigma_region_probability_raw"] = p_raw
+        adata.obs["sigma_region_probability"] = p
+        adata.obs["sigma_inside"] = inside
+        adata.obs["sigma_boundary"] = boundary
+        adata.obs["sigma_d_signed"] = d_signed
+        adata.uns["sigma"] = {"sigma": sigma, "k": self.k, "seed": self.seed}
+        self.adata_ = adata
+        return self

sigma_omics-0.1.0a1/src/sigma_spatial/plotting.py

@@ -0,0 +1,100 @@
+"""Shared, layout-safe plotting helpers for SIGMA analyses."""
+
+from pathlib import Path
+import string
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+
+FIGURE_SIZES = {
+    "single": (3.35, 2.7),
+    "single_square": (3.35, 3.35),
+    "double": (7.0, 4.2),
+    "double_square": (7.0, 7.0),
+    "full_page": (7.0, 9.0),
+    "slides_wide": (10.0, 4.8),
+}
+
+
+def set_publication_style(font_family="Arial", base_font_size=9):
+    """Apply a consistent vector-friendly manuscript style."""
+    mpl.rcParams.update({
+        "font.family": font_family,
+        "font.size": base_font_size,
+        "axes.titlesize": base_font_size + 1,
+        "axes.labelsize": base_font_size,
+        "xtick.labelsize": base_font_size - 1,
+        "ytick.labelsize": base_font_size - 1,
+        "legend.fontsize": base_font_size - 1,
+        "figure.titlesize": base_font_size + 2,
+        "axes.linewidth": 0.8,
+        "lines.linewidth": 1.2,
+        "pdf.fonttype": 42,
+        "ps.fonttype": 42,
+        "svg.fonttype": "none",
+        "savefig.dpi": 300,
+        "savefig.bbox": None,
+    })
+
+
+def figure_size(name="double"):
+    """Return a standard manuscript figure size."""
+    try:
+        return FIGURE_SIZES[name]
+    except KeyError as exc:
+        raise ValueError(f"Unknown figure size {name!r}") from exc
+
+
+def add_panel_labels(axes, labels=None, x=-0.12, y=1.06, fontsize=11):
+    """Add consistent panel labels in axes coordinates."""
+    axes = list(axes)
+    labels = list(labels or string.ascii_uppercase[:len(axes)])
+    for ax, label in zip(axes, labels):
+        ax.text(x, y, label, transform=ax.transAxes, ha="left", va="top",
+                fontsize=fontsize, fontweight="bold", clip_on=False)
+
+
+def legend_outside(ax, *, loc="upper left", anchor=(1.02, 1.0), **kwargs):
+    """Place a legend outside the data axes."""
+    return ax.legend(loc=loc, bbox_to_anchor=anchor, borderaxespad=0,
+                     frameon=False, **kwargs)
+
+
+def shared_colorbar(fig, mappable, axes, *, label=None, location="right", **kwargs):
+    """Create one colorbar for a collection of axes."""
+    colorbar = fig.colorbar(mappable, ax=list(axes), location=location, **kwargs)
+    if label:
+        colorbar.set_label(label)
+    return colorbar
+
+
+def style_spatial_axis(ax):
+    """Remove decorations that are not meaningful for tissue coordinates."""
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_xlabel("")
+    ax.set_ylabel("")
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+
+
+def save_figure(fig, path, *, formats=("pdf", "svg"), dpi=300,
+                transparent=False, close=False):
+    """Save a figure in consistent vector and optional raster formats.
+
+    ``path`` is a stem or a filename.  Layout is expected to be solved by
+    constrained layout/GridSpec rather than repaired with ``bbox_inches``.
+    """
+    path = Path(path)
+    stem = path.with_suffix("") if path.suffix else path
+    stem.parent.mkdir(parents=True, exist_ok=True)
+    written = []
+    for fmt in formats:
+        output = stem.with_suffix(f".{fmt.lstrip('.')}")
+        fig.savefig(output, dpi=dpi, transparent=transparent, facecolor=fig.get_facecolor())
+        written.append(output)
+    if close:
+        plt.close(fig)
+    return written

sigma_omics-0.1.0a1/src/sigma_spatial/preprocessing.py

@@ -0,0 +1,39 @@
+import numpy as np
+from scipy.sparse import issparse
+from sklearn.decomposition import TruncatedSVD
+from sklearn.preprocessing import RobustScaler
+
+
+def get_msi_matrix(adata, layer=None):
+    """Return an n_spots x n_features MSI matrix from AnnData."""
+    if layer is not None:
+        if layer not in adata.layers:
+            raise KeyError(f"Layer {layer!r} not found in adata.layers")
+        return adata.layers[layer]
+    if "msi" in adata.uns:
+        x = adata.uns["msi"]
+        if hasattr(x, "shape") and x.shape[0] == adata.n_obs:
+            return x
+    if "raw" in adata.layers:
+        x = adata.layers["raw"]
+        if hasattr(x, "shape") and x.shape[0] == adata.n_obs:
+            return x
+    return adata.X
+
+
+def msi_to_embedding(x, n_components=64, random_state=0):
+    """log1p + robust scaling (dense only) + TruncatedSVD + z-score."""
+    max_components = min(x.shape) - 1
+    k = min(int(n_components), max_components)
+    if k < 1:
+        raise ValueError("MSI matrix is too small for SVD.")
+    if issparse(x):
+        xlog = x.copy()
+        xlog.data = np.log1p(xlog.data)
+        e = TruncatedSVD(n_components=k, random_state=random_state).fit_transform(xlog)
+    else:
+        xlog = np.log1p(np.asarray(x, dtype=np.float32))
+        xs = RobustScaler(quantile_range=(10, 90)).fit_transform(xlog)
+        e = TruncatedSVD(n_components=k, random_state=random_state).fit_transform(xs)
+    e = np.asarray(e, dtype=np.float32)
+    return (e - e.mean(0)) / (e.std(0) + 1e-6)

sigma_omics-0.1.0a1/src/sigma_spatial/simulation.py

@@ -0,0 +1,114 @@
+"""Simulation helpers preserved from HBC_515 cells 46 and 49."""
+
+import numpy as np
+import pandas as pd
+from sklearn.metrics import (
+    average_precision_score, f1_score, precision_score, recall_score,
+    roc_auc_score, roc_curve,
+)
+
+
+def zscore_vec(x):
+    x = np.asarray(x, dtype=float)
+    return (x - np.nanmean(x)) / (np.nanstd(x) + 1e-8)
+
+
+def simulate_interface_features(d_abs, d_signed=None, coords=None, tumor_mask=None,
+                                n_positive=100, n_negative=100,
+                                n_region_only=300, n_spatial_background=300,
+                                n_noise=500, effect_size=1.0, noise_sd=0.5,
+                                lam=200.0, random_state=0):
+    """Generate the five feature classes used in HBC_515 simulation cell 46."""
+    rng = np.random.default_rng(random_state)
+    d_abs = np.asarray(d_abs, dtype=float)
+    n = len(d_abs)
+    if d_signed is None:
+        d_signed = d_abs.copy()
+    if tumor_mask is None:
+        tumor_mask = np.asarray(d_signed) < 0
+    tumor_mask = np.asarray(tumor_mask, dtype=bool)
+    if coords is None:
+        coords = np.column_stack([rng.normal(size=n), rng.normal(size=n)])
+    coords = np.asarray(coords, dtype=float)
+    x_coord, y_coord = zscore_vec(coords[:, 0]), zscore_vec(coords[:, 1])
+    features, rows = [], []
+
+    def add_feature(vec, sim_type, direction, true_lambda=np.nan):
+        j = len(features)
+        vec = np.asarray(vec, dtype=float)
+        vec = vec - np.nanmin(vec)
+        vec = vec / (np.nanstd(vec) + 1e-8)
+        features.append(vec)
+        rows.append({"j": j, "mz": f"sim_mz_{j}", "sim_type": sim_type,
+                     "true_direction": direction, "true_lambda": true_lambda,
+                     "is_boundary_truth": sim_type in ("positive_boundary", "negative_boundary"),
+                     "is_positive_truth": sim_type == "positive_boundary",
+                     "is_negative_truth": sim_type == "negative_boundary"})
+
+    for _ in range(n_positive):
+        local_lam = lam * rng.lognormal(mean=0, sigma=0.25)
+        add_feature(effect_size * np.exp(-d_abs / (local_lam + 1e-8)) +
+                    rng.normal(0, noise_sd, n), "positive_boundary", "positive", local_lam)
+    for _ in range(n_negative):
+        local_lam = lam * rng.lognormal(mean=0, sigma=0.25)
+        add_feature(effect_size * (1 - np.exp(-d_abs / (local_lam + 1e-8))) +
+                    rng.normal(0, noise_sd, n), "negative_boundary", "negative", local_lam)
+    for _ in range(n_region_only):
+        sign = rng.choice([-1, 1])
+        add_feature(effect_size * sign * tumor_mask.astype(float) +
+                    rng.normal(0, noise_sd, n), "region_only", "region")
+    for _ in range(n_spatial_background):
+        angle = rng.uniform(0, 2 * np.pi)
+        signal = zscore_vec(np.cos(angle) * x_coord + np.sin(angle) * y_coord)
+        add_feature(effect_size * signal + rng.normal(0, noise_sd, n),
+                    "spatial_background", "background")
+    for _ in range(n_noise):
+        add_feature(rng.normal(0, noise_sd, n), "noise", "noise")
+    # The original returns a list of records despite documenting a DataFrame.
+    return np.vstack(features).T, rows
+
+
+def recovery_curve_data(df):
+    """Return ROC/AP inputs using the exact continuous score from HBC_515 cell 49."""
+    truth = df["is_boundary_truth"].astype(int).to_numpy()
+    score = np.maximum(df["score_positive"].fillna(-np.inf).to_numpy(),
+                       df["score_negative"].fillna(-np.inf).to_numpy())
+    fpr, tpr, thresholds = roc_curve(truth, score)
+    return {"truth": truth, "score": score, "fpr": fpr, "tpr": tpr,
+            "thresholds": thresholds, "auroc": roc_auc_score(truth, score),
+            "average_precision": average_precision_score(truth, score)}
+
+
+def evaluate_simulation_feature_selection(df):
+    """Preserve the scalar recovery metrics from HBC_515 cell 49."""
+    truth = df["is_boundary_truth"].astype(int).to_numpy()
+    selected = df["is_selected_boundary"].astype(int).to_numpy()
+    curves = recovery_curve_data(df)
+    selected_true = df[df["is_selected_boundary"] & df["is_boundary_truth"]]
+    direction_accuracy = (np.mean(selected_true["pred_direction"].to_numpy() ==
+                                  selected_true["true_direction"].to_numpy())
+                          if len(selected_true) else np.nan)
+    pos_recall = recall_score(df["is_positive_truth"].astype(int),
+                              (df["pred_direction"] == "positive").astype(int), zero_division=0)
+    neg_recall = recall_score(df["is_negative_truth"].astype(int),
+                              (df["pred_direction"] == "negative").astype(int), zero_division=0)
+    lambda_df = df[(df["true_direction"] == "positive") &
+                   np.isfinite(df["true_lambda"]) & np.isfinite(df["lambda_hat"])]
+    if len(lambda_df):
+        error = np.abs(lambda_df["lambda_hat"] - lambda_df["true_lambda"])
+        lambda_mae = error.mean()
+        lambda_relative_error = (error / (lambda_df["true_lambda"] + 1e-8)).mean()
+    else:
+        lambda_mae = lambda_relative_error = np.nan
+    return pd.DataFrame([{
+        "precision": precision_score(truth, selected, zero_division=0),
+        "recall": recall_score(truth, selected, zero_division=0),
+        "f1": f1_score(truth, selected, zero_division=0),
+        "auroc": curves["auroc"], "auprc": curves["average_precision"],
+        "direction_accuracy": direction_accuracy, "positive_recall": pos_recall,
+        "negative_recall": neg_recall, "lambda_mae": lambda_mae,
+        "lambda_relative_error": lambda_relative_error,
+        "n_selected": int(selected.sum()), "n_true_boundary": int(truth.sum()),
+        "n_positive_selected": int((df["pred_direction"] == "positive").sum()),
+        "n_negative_selected": int((df["pred_direction"] == "negative").sum()),
+    }])

sigma_omics-0.1.0a1/src/sigma_spatial/utils.py

@@ -0,0 +1,15 @@
+import os
+import random
+import numpy as np
+import torch
+
+
+def set_seed(seed=0):
+    os.environ["PYTHONHASHSEED"] = str(seed)
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+    torch.backends.cudnn.deterministic = True
+    torch.backends.cudnn.benchmark = False

sigma_omics-0.1.0a1/tests/test_import.py

@@ -0,0 +1,3 @@
+def test_import():
+    import sigma_spatial
+    assert sigma_spatial.__version__ == "0.1.0a1"

sigma_omics-0.1.0a1/tests/test_reference_preservation.py

@@ -0,0 +1,50 @@
+import hashlib
+from pathlib import Path
+
+import numpy as np
+
+from sigma_spatial.boundary import build_boundary_from_binary_mask
+from sigma_spatial.graph import gaussian_knn_graph, gaussian_label_smoothing, smooth_embedding
+
+
+ROOT = Path(__file__).resolve().parents[2]
+ORIGINAL = ROOT / "HBC_515" / "HBC_515_SIGMA.ipynb"
+ORIGINAL_SHA256 = "58cdc1c0d18eddcbeab4718fe9fc5748ae852b3f5ff7dc485d49c2400c4f45d4"
+
+
+def test_original_hbc515_notebook_is_unchanged():
+    assert hashlib.sha256(ORIGINAL.read_bytes()).hexdigest() == ORIGINAL_SHA256
+
+
+def test_reference_directed_gaussian_graph_values():
+    xy = np.array([[0., 0.], [1., 0.], [0., 2.], [3., 0.]], dtype=np.float32)
+    edge_index, weights, sigma = gaussian_knn_graph(xy, k=2, symmetrize=False)
+    expected_edges = np.array([[0, 0, 1, 1, 2, 2, 3, 3],
+                               [1, 2, 0, 3, 0, 1, 1, 0]])
+    expected_dist = np.array([1., 2., 1., 2., 2., np.sqrt(5), 2., 3.])
+    expected_sigma = np.median(expected_dist.reshape(4, 2))
+    np.testing.assert_array_equal(edge_index, expected_edges)
+    np.testing.assert_allclose(sigma, expected_sigma)
+    np.testing.assert_allclose(weights, np.exp(-(expected_dist ** 2) /
+                                                (2 * expected_sigma ** 2)), rtol=1e-6)
+
+
+def test_label_and_embedding_diffusion_match_frozen_values():
+    edges = np.array([[0, 0, 1, 1, 2, 2], [1, 2, 0, 2, 0, 1]])
+    weights = np.ones(6, dtype=np.float32)
+    y = np.array([1, -1, 0])
+    mask = y >= 0
+    field = gaussian_label_smoothing(edges, weights, y, mask, n_iter=2, alpha=0.5)
+    np.testing.assert_allclose(field, [1.0, 0.25, 0.0], rtol=0, atol=1e-7)
+    embedding = np.array([[1., 0.], [0., 1.], [0., 0.]], dtype=np.float32)
+    smoothed = smooth_embedding(edges, weights, embedding, n_iter=1, alpha=0.5)
+    np.testing.assert_allclose(smoothed, [[0.5, 0.25], [0.25, 0.5], [0.25, 0.25]])
+
+
+def test_boundary_requires_same_and_opposite_neighbours():
+    xy = np.array([[0., 0.], [1., 0.], [2., 0.], [3., 0.]])
+    inside = np.array([True, True, False, False])
+    np.testing.assert_array_equal(
+        build_boundary_from_binary_mask(xy, inside, k_nn=2),
+        np.array([True, True, True, True]),
+    )

sigma_omics-0.1.0a1/tests/test_simulation_preservation.py

@@ -0,0 +1,21 @@
+import numpy as np
+
+from sigma_spatial.simulation import simulate_interface_features
+
+
+def test_simulation_is_seeded_and_retains_reference_return_type():
+    distance = np.linspace(0, 10, 12)
+    coords = np.column_stack([distance, np.zeros_like(distance)])
+    kwargs = dict(d_abs=distance, coords=coords, n_positive=2, n_negative=1,
+                  n_region_only=1, n_spatial_background=1, n_noise=1,
+                  effect_size=0.5, noise_sd=0.2, lam=100, random_state=7)
+    x1, meta1 = simulate_interface_features(**kwargs)
+    x2, meta2 = simulate_interface_features(**kwargs)
+    np.testing.assert_array_equal(x1, x2)
+    assert meta1 == meta2
+    assert isinstance(meta1, list)  # Preserve HBC_515 cell 46 behaviour.
+    assert x1.shape == (12, 6)
+    assert [row["sim_type"] for row in meta1] == [
+        "positive_boundary", "positive_boundary", "negative_boundary",
+        "region_only", "spatial_background", "noise",
+    ]