sc-mantis 0.51__tar.gz

sc_mantis-0.51/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yuhaotuo
+
+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.

sc_mantis-0.51/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sc-mantis
+Version: 0.51
+Summary: SCOUBI
+Author-email: Yu Hao <yhao306@gatech.edu>, Bhavay Aggarwal <baggarwal9@gatech.edu>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MANTIS

sc_mantis-0.51/README.md

@@ -0,0 +1 @@
+# MANTIS

sc_mantis-0.51/mantis/__init__.py

@@ -0,0 +1,5 @@
+from . import io
+# from . import preprocess as pp
+# from . import model as md
+from . import tools as tl
+# from . import plotting as pl

sc_mantis-0.51/mantis/io/__init__.py

@@ -0,0 +1 @@
+from ._io import load_data

sc_mantis-0.51/mantis/io/_io.py

@@ -0,0 +1,125 @@
+import pandas as pd
+import numpy as np
+import anndata as ad
+from mudata import MuData
+from mudata import set_options
+import mudata as mu
+import os
+import types
+
+def _summarize(self):
+    """Structured summary of MuData with grouped .uns fields."""
+    print(f"MuData object with n_obs × n_vars = {self.n_obs} × {self.n_vars}")
+    print("obs:", ", ".join(self.obs_keys()))
+    print("obsm:", ", ".join(self.obsm_keys()))
+    print("uns:")
+
+    # --- Predefined grouping map ---
+    group_map = {
+        'cell_type': ['celltype_metabolite', 'celltype_metabolite_per_ct'],
+        'region': ['regional_metabolite', 'regional_metabolite_fit'],
+        'spatvar': ['spatvar_metabolite', 'spatvar_metabolite_celltype', 
+                    'spatvar_metabolite_celltype_coef', 'spatvar_metabolite_celltype_summary', 
+                    'spatvar_metabolite_combined', 'spatvar_metabolite_region'],
+        'genemet': ['genemet_sci', 'genemet_sci_summary'],
+        'misc': [],
+    }
+
+    # flatten group map for lookup
+    assigned = set(k for keys in group_map.values() for k in keys)
+    uns_keys = set(self.uns.keys())
+    ungrouped = sorted(uns_keys - assigned)
+
+    # print present keys per group
+    for group, keys in group_map.items():
+        present = [k for k in keys if k in self.uns]
+        if present:
+            print(f"  {group:<22}: {', '.join(present)}")
+
+    if ungrouped:
+        print(f"  {'other':<22}: {', '.join(ungrouped)}")
+
+
+def _attach_summarize(mdata):
+    """Attach summarize() method to a single MuData object in memory."""
+    mdata.summarize = types.MethodType(_summarize, mdata)
+    return mdata
+
+def load_data(
+    g_file=None,          # CSV of gene expression (cells × genes)
+    m_file=None,          # CSV of metabolite abundances (cells × metabolites)
+    coords=None,          # CSV of spatial coordinates
+    cell_type=None,       # CSV of cell type labels
+    region=None,          # CSV of region labels
+    mdata=None            # existing .h5mu file path
+):
+    set_options(pull_on_update=False)
+    """
+    Load or build a MuData object containing multi-omic and spatial data.
+
+    If `mdata` is provided, loads it directly and ignores all other inputs.
+    Otherwise, builds a MuData object from the provided CSV files.
+    """
+
+    if mdata is not None:
+        if not os.path.exists(mdata):
+            raise FileNotFoundError(f"File not found: {mdata}")
+        mdata_obj = mu.read_h5mu(mdata)
+        mdata_obj = _attach_summarize(mdata_obj)
+        # mu.MuData.summarize = _summarize
+        return mdata_obj
+
+    if coords is None:
+        raise ValueError("Spatial coordinate file (coords) must be provided.")
+    coords_df = pd.read_csv(coords, index_col=0)
+
+    gene_df = pd.read_csv(g_file, index_col=0) if g_file else None
+    met_df = pd.read_csv(m_file, index_col=0) if m_file else None
+
+    common_idx = coords_df.index
+    if gene_df is not None:
+        common_idx = common_idx.intersection(gene_df.index)
+    if met_df is not None:
+        common_idx = common_idx.intersection(met_df.index)
+
+    if len(common_idx) == 0:
+        raise ValueError("No common cell indices found among provided datasets.")
+
+    coords_df = coords_df.loc[common_idx]
+    if gene_df is not None:
+        gene_df = gene_df.loc[common_idx]
+    if met_df is not None:
+        met_df = met_df.loc[common_idx]
+
+    adatas = {}
+    if gene_df is not None:
+        adatas["gene"] = ad.AnnData(
+            X=gene_df.to_numpy(dtype=float),
+            obs=pd.DataFrame(index=common_idx),
+            var=pd.DataFrame(index=gene_df.columns)
+        )
+    if met_df is not None:
+        adatas["metabolite"] = ad.AnnData(
+            X=met_df.to_numpy(dtype=float),
+            obs=pd.DataFrame(index=common_idx),
+            var=pd.DataFrame(index=met_df.columns)
+        )
+
+    if not adatas:
+        raise ValueError("No omic data provided. Must provide at least one of g_file or m_file.")
+
+    mdata_obj = MuData(adatas)
+
+    obs_meta = pd.DataFrame(index=common_idx)
+    if cell_type is not None:
+        celltype_df = pd.read_csv(cell_type, index_col=0)
+        obs_meta["cell_type"] = celltype_df.loc[common_idx]
+    if region is not None:
+        region_df = pd.read_csv(region, index_col=0)
+        obs_meta["region"] = region_df.loc[common_idx]
+    mdata_obj.obsm = obs_meta
+
+    mdata_obj.obsm["spatial"] = coords_df
+    mdata_obj = _attach_summarize(mdata_obj)
+    mu.MuData.summarize = _summarize
+    return mdata_obj

sc_mantis-0.51/mantis/tools/__init__.py

@@ -0,0 +1,6 @@
+from ._sampler import sample
+from ._region import compute_regional_metabolite
+from ._celltype import celltype_met
+from ._space import spatvar_metabolite
+from ._genemet import compute_genemet_sci
+from ._spc import compute_spc_ct, compute_spc_sd

sc_mantis-0.51/mantis/tools/_celltype.py

@@ -0,0 +1,129 @@
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from scipy.spatial.distance import pdist, squareform
+
+def _bh_fdr_rowwise(p_mat: np.ndarray):
+    p = np.asarray(p_mat, dtype=float)
+    K, M = p.shape
+    q = np.empty_like(p)
+    for i in range(K):
+        pi = p[i].copy()
+        order = np.argsort(pi, kind="mergesort")
+        ranks = np.arange(1, M + 1, dtype=float)
+        qi = pi[order] * M / ranks
+        qi = np.minimum.accumulate(qi[::-1])[::-1]
+        out = np.empty_like(qi)
+        out[order] = qi
+        q[i] = np.clip(out, 0, 1)
+    return q
+
+def _significant_by_ct_single_null(
+    SCI_real: pd.DataFrame,
+    SCI_null: pd.DataFrame,
+    alpha: float = 0.05,
+    two_sided: bool = True,
+):
+
+    rows = SCI_real.index.intersection(SCI_null.index)
+    cols = SCI_real.columns.intersection(SCI_null.columns)
+    R = SCI_real.loc[rows, cols].astype(float)
+    N = SCI_null.loc[rows, cols].astype(float)
+
+    K, M = R.shape
+    real_vals = R.to_numpy()   # K×M
+    null_vals = N.to_numpy()   # K×M
+
+    if two_sided:
+        real_use = np.abs(real_vals)
+        null_use = np.abs(null_vals)
+    else:
+        real_use = real_vals
+        null_use = null_vals
+
+    p_emp = np.empty_like(real_vals, dtype=float)
+    for i in range(K):
+        base = null_use[i]
+        for j in range(M):
+            p_emp[i, j] = (np.sum(base >= real_use[i, j]) + 1.0) / (M + 1.0)
+
+    q_bh = _bh_fdr_rowwise(p_emp)
+
+
+    long = []
+    for i, ct in enumerate(rows):
+        for j, met in enumerate(cols):
+            long.append({
+                "cell_type":  ct,
+                "metabolite": met,
+                "sci":        float(real_vals[i, j]),
+                "p_emp":      float(p_emp[i, j]),
+                "q_bh":       float(q_bh[i, j]),
+            })
+    long_df = pd.DataFrame(long)
+    long_df["significant"] = long_df["q_bh"] < alpha
+
+    per_ct = {}
+    sig_rows = []
+    for ct, sub in long_df.groupby("cell_type"):
+        sig = sub[sub["significant"]].sort_values(["q_bh", "p_emp", "sci"])
+        per_ct[ct] = sig
+        if not sig.empty:
+            sig_rows.append(sig)
+    return long_df, per_ct
+
+def _zscore_cols(A):
+    mu = A.mean(axis=0, keepdims=True)
+    sd = A.std(axis=0, ddof=0, keepdims=True)
+    sd = np.where(sd == 0, 1.0, sd)
+    return (A - mu) / sd
+
+def _build_W(xy, l="dmin", norm="row"):
+    D = squareform(pdist(xy, metric="euclidean"))
+    d_nonzero = D[D > 0]
+    if isinstance(l, str) and l == "dmin":
+        if d_nonzero.size == 0:
+            raise ValueError("there is no dmin.")
+        lval = float(np.min(d_nonzero))
+    else:
+        lval = float(l)
+    W = np.exp(-(D**2) / (2.0 * lval * lval))
+    np.fill_diagonal(W, 1.0)
+    if norm == "row":
+        W = W / W.sum(axis=1, keepdims=True)
+    elif norm == "global":
+        W = W / W.sum()
+    return W
+
+def _compute_sci(Ydf, Cdf, xy, normalized=True, l="dmin", w_norm="row"):
+    W  = _build_W(xy, l=l, norm=w_norm)
+    Cz = _zscore_cols(Cdf.to_numpy())
+    Yz = _zscore_cols(Ydf.to_numpy())
+
+    WY      = W @ Yz 
+    SCI_raw = Cz.T @ WY 
+
+    if not normalized:
+        return pd.DataFrame(SCI_raw, index=Cdf.columns, columns=Ydf.columns)
+
+    xvar = np.sum(Cz**2, axis=0)        # K
+    yvar = np.sum(Yz**2, axis=0)        # M
+    den  = np.sqrt(xvar[:, None] * yvar[None, :])
+    den  = np.where(den == 0, 1.0, den)
+    SCI_corr = SCI_raw / den
+
+    return pd.DataFrame(SCI_corr, index=Cdf.columns, columns=Ydf.columns)
+
+def celltype_met(mdata, alpha = 0.05, two_sided = True):
+    sci = _compute_sci(mdata.mod['metabolite'].to_df(), mdata.obsm['cell_type'], mdata.obsm['spatial'].values, normalized=True)
+    sci_null = _compute_sci(mdata.uns['metabolite_null'].to_df(), mdata.obsm['cell_type'], mdata.obsm['spatial'].values, normalized=True)
+    long_df, per_ct = _significant_by_ct_single_null(
+        sci, sci_null,
+        alpha=alpha,
+        two_sided=two_sided
+    )
+    mdata.uns['celltype_met'] = long_df
+    mdata.uns['celltype_met_per_ct'] = per_ct
+    return mdata

sc_mantis-0.51/mantis/tools/_genemet.py

@@ -0,0 +1,226 @@
+import numpy as np
+import pandas as pd
+from pathlib import Path
+from scipy.spatial.distance import pdist, squareform
+import math
+from scipy.spatial import cKDTree
+import matplotlib.pyplot as plt
+import networkx as nx
+import re
+
+def _build_weighted_radius_graph(coords, radius=None, l=None, weight_key="w"):
+
+    if (radius is None) and (l is None):
+        raise ValueError("radius or l should be supplied")
+    if l is None:
+        l = float(radius)
+    if radius is None:
+        radius = 2.0 * float(l)
+
+    tree = cKDTree(coords)
+    coo = tree.sparse_distance_matrix(tree, max_distance=radius, output_type="coo_matrix")
+    G = nx.Graph()
+    G.add_nodes_from(range(coords.shape[0]))
+    inv_two_l2 = 1.0 / (2.0 * float(l) * float(l))
+
+    for i, j, d in zip(coo.row, coo.col, coo.data):
+        if i < j:
+            if d <= l:
+                w = 1.0
+            else:
+                w = float(np.exp(-(d * d) * inv_two_l2))
+            if w > 0.0:
+                G.add_edge(i, j, **{weight_key: w})
+    return G
+
+def _target_diag_M_from_matrix(G, X_mat, weight_key="w"):
+    M = X_mat.shape[1]
+    Mt = np.zeros(M, dtype=float)
+    for u, v, data in G.edges(data=True):
+        w = data.get(weight_key, 1.0)
+        Mt += w * X_mat[u] * X_mat[v]
+    return Mt
+
+def _build_W_from_coords(coords_xy, l):
+    D_condensed = pdist(coords_xy, metric="euclidean")
+    dist = squareform(D_condensed)
+    W = np.zeros_like(dist, dtype=float)
+
+    mask = dist > 0
+    W[mask] = np.exp(-(dist[mask]**2) / (2.0 * l**2))
+    np.fill_diagonal(W, 1.0)
+
+    row_sums = W.sum(axis=1, keepdims=True)
+    row_sums[row_sums == 0.0] = 1.0
+    W /= row_sums
+    return W
+
+def _zscore_cols(A: np.ndarray) -> np.ndarray:
+    mu = A.mean(axis=0, keepdims=True)
+    sd = A.std(axis=0, ddof=0, keepdims=True)
+    sd[sd == 0.0] = 1.0
+    return (A - mu) / sd
+
+def bh_fdr(p_values_1d):
+
+    p = np.asarray(p_values_1d, dtype=float)
+    n = p.size
+    order = np.argsort(p)
+    ranked = p[order]
+    q = np.empty_like(ranked)
+    prev = 1.0
+    for i in range(n-1, -1, -1):
+        rank = i + 1
+        q_i = ranked[i] * n / rank
+        if q_i > prev:
+            q_i = prev
+        prev = q_i
+        q[i] = q_i
+    out = np.empty_like(q)
+    out[order] = q
+    return out
+
+def pooled_empirical_p_two(real_mat, null_mat):
+    real = real_mat.ravel()
+    null_vals = null_mat.ravel()
+    null_vals = null_vals[np.isfinite(null_vals)]
+
+    null_sorted = np.sort(null_vals)
+    N = null_sorted.size
+
+    idx_right = np.searchsorted(null_sorted, real, side='right')
+    count_le = idx_right
+    count_ge = N - np.searchsorted(null_sorted, real, side='left')
+
+    p_left  = (count_le + 1) / (N + 1)
+    p_right = (count_ge + 1) / (N + 1)
+
+    p_two = 2 * np.minimum(p_left, p_right)
+    p_two = np.minimum(p_two, 1.0)
+    return p_two.reshape(real_mat.shape)
+
+def compute_genemet_sci(mdata, n_bins=10, alpha=0.05):
+    dmin = math.sqrt(2.0); l = 4*dmin
+    G = _build_weighted_radius_graph(mdata.obsm['spatial'].values, l=l, radius=float("inf"), weight_key="w")
+    X_all = np.asarray(mdata.mod['metabolite'].to_df(), dtype=float)
+    X_df = mdata.mod['metabolite'].to_df()
+    X_rna = mdata.mod['gene'].to_df().to_numpy()
+    met_names = X_df.columns.tolist()
+    X_mean = X_all.mean(axis=0, keepdims=True)
+    X_std  = X_all.std(axis=0, ddof=0, keepdims=True); X_std[X_std==0] = 1.0
+    Xz = (X_all - X_mean) / X_std
+
+    M0_varnorm = _target_diag_M_from_matrix(G, Xz, weight_key="w")
+    M0 = np.asarray(M0_varnorm, dtype=float)
+    q = np.linspace(0, 1, n_bins + 1)
+    bin_edges = np.quantile(M0, q, method="linear")
+    edges = [bin_edges[0]]
+    for v in bin_edges[1:]:
+        if v > edges[-1]:
+            edges.append(v)
+    bin_edges = np.array(edges, dtype=float)
+    k = len(bin_edges) - 1
+
+    s = pd.Series(M0, index=pd.Index(met_names, name="metabolite"))
+    idx = np.searchsorted(bin_edges, s.values, side="right") - 1
+    idx = np.clip(idx, 0, k-1)
+
+    bin_mets = [[] for _ in range(k)]
+    for name, b in zip(s.index, idx):
+        bin_mets[b].append(name)
+
+    name_to_idx = {name: i for i, name in enumerate(met_names)}
+    bin_counts = []
+    bin_dfs = {}
+    for i, mets in enumerate(bin_mets):
+        if not mets:
+            bin_counts.append(0)
+            continue
+        cols = [name_to_idx[m] for m in mets if m in name_to_idx]
+        bin_counts.append(len(cols))
+        if cols:
+            df_bin = pd.DataFrame(
+                X_all[:, cols],
+                columns=[met_names[j] for j in cols],
+                index=pd.Index(mdata.obs_names, name="spot_id")
+            )
+            left, right = float(bin_edges[i]), float(bin_edges[i+1])
+            bin_dfs[i+1] = df_bin
+    l = dmin
+    W = _build_W_from_coords(mdata.obsm['spatial'].values, l=l)
+    S0 = float(W.sum())
+    if S0 == 0: S0 = 1.0
+    genemet_sci_bins = {}
+    for i in bin_dfs:
+        X_met = bin_dfs[i].to_numpy(dtype=float)
+        X_rna_std = (X_rna - X_rna.mean(axis=0, keepdims=True)) / np.maximum(X_rna.std(axis=0, ddof=0, keepdims=True), 1e-12)
+        X_met_std = (X_met - X_met.mean(axis=0, keepdims=True)) / np.maximum(X_met.std(axis=0, ddof=0, keepdims=True), 1e-12)
+        WY = W.dot(X_met_std)
+        WY  = W @ X_met_std
+        SCI = (X_rna_std.T @ WY) / S0
+        sci_df = pd.DataFrame(SCI, index=mdata.mod['gene'].to_df().columns, columns=bin_dfs[i].columns)
+        genemet_sci_bins[i] = sci_df
+    
+    X_met_null_df = mdata.uns['metabolite_null'].to_df()
+    D = squareform(pdist(mdata.obsm['spatial'].values, metric="euclidean"))
+    pos = D > 0
+    dmin = float(D[pos].min()) if np.any(pos) else np.finfo(float).eps
+    l = dmin
+    W = _build_W_from_coords(mdata.obsm['spatial'].values, l=l)
+    S0  = float(W.sum())
+    if S0 == 0: S0 = 1.0
+    genemet_sci_bins_null = {}
+    for i in bin_dfs:
+        cols_present = [c for c in bin_dfs[i].columns if c in X_met_null_df.columns]
+        X_met_null = X_met_null_df[cols_present].to_numpy(dtype=float)
+        X_rna_std = _zscore_cols(X_rna)
+        X_met_null_std = _zscore_cols(X_met_null)
+
+        WY = W.dot(X_met_null_std)
+        WY  = W @ X_met_null_std
+        SCI = (X_rna_std.T @ WY) / S0
+        sci_df = pd.DataFrame(SCI, index=mdata.mod['gene'].to_df().columns, columns=bin_dfs[i].columns)
+        genemet_sci_bins_null[i] = sci_df
+    results = {}
+    for n in genemet_sci_bins:
+        common_genes = genemet_sci_bins[n].index.intersection(genemet_sci_bins_null[n].index)
+        common_mets  = genemet_sci_bins[n].columns.intersection(genemet_sci_bins_null[n].columns)
+        real_df = genemet_sci_bins[n].loc[common_genes, common_mets]
+        null_df = genemet_sci_bins_null[n].loc[common_genes, common_mets]
+        p_two = pooled_empirical_p_two(real_df.values, null_df.values)
+        q_two = bh_fdr(p_two.ravel()).reshape(p_two.shape)
+
+        sig_mask = (q_two < alpha)
+
+        res = []
+        genes = real_df.index.tolist()
+        mets  = real_df.columns.tolist()
+        for i, g in enumerate(genes):
+            for j, m in enumerate(mets):
+                res.append({
+                    "gene": g,
+                    "metabolite": m,
+                    "SCI": float(real_df.iloc[i, j]),
+                    "p_value": float(p_two[i, j]),
+                    "q_value": float(q_two[i, j]),
+                    "significant": bool(sig_mask[i, j])
+                })
+        res_df = pd.DataFrame(res)
+        print(int(sig_mask.sum()))
+        results[n] = res_df
+    dfs = []
+    for i in results:
+        results[i]["bin_index"] = i
+        dfs.append(results[i])
+    merged_eq = pd.concat(dfs, ignore_index=True, sort=False)
+    meta_cols = ["method", "bin_index", "bin_min", "bin_max", "bin_label", "source_file"]
+    front = [c for c in meta_cols if c in merged_eq.columns]
+    rest = [c for c in merged_eq.columns if c not in front]
+    merged_eq = merged_eq[front + rest]
+    summary = (
+        merged_eq.groupby(["bin_index"], dropna=False)
+                .size().reset_index(name="significant_pairs")
+    )
+    mdata.uns['genemet_sci'] = merged_eq
+    mdata.uns['genemet_sci_summary'] = summary
+    return mdata