scdiagnostics 0.0.99.1__py3-none-any.whl

scdiagnostics/__init__.py

@@ -0,0 +1,15 @@
+from .dimred import plot_umap, plot_pca, compare_pca, compare_umap
+from .marginal import (
+    compare_boxplot,
+    compare_ecdf,
+    compare_histogram,
+    compare_means,
+    compare_moments,
+    compare_standard_deviation,
+    compare_variances,
+    compare_histogram2
+)
+from .spatial import (
+    plot_dispersion_surface,
+    plot_mean_surface
+)

scdiagnostics/data.py

@@ -0,0 +1,39 @@
+import numpy as np
+import pandas as pd
+
+
+def adata_df(adata):
+    return (
+        pd.DataFrame(check_sparse(adata.X), columns=adata.var_names)
+        .melt(id_vars=[], value_vars=adata.var_names)
+        .reset_index(drop=True)
+    )
+
+
+def merge_samples(adata, sim):
+    source = adata_df(adata)
+    simulated = adata_df(sim)
+    return pd.concat(
+        {"real": source, "simulated": simulated}, names=["source"]
+    ).reset_index(level="source")
+
+
+def check_sparse(X):
+    if not isinstance(X, np.ndarray):
+        X = X.todense()
+    return X
+
+
+def prepare_dense(real, simulated):
+    real_ = real.copy()
+    simulated_ = simulated.copy()
+    real_.X = check_sparse(real_.X)
+    simulated_.X = check_sparse(simulated_.X)
+    return real_, simulated_
+
+
+def concat_real_sim(real, simulated):
+    real_, simulated_ = prepare_dense(real, simulated)
+    real_.obs["source"] = "real"
+    simulated_.obs["source"] = "simulated"
+    return real_.concatenate(simulated_, join="outer", batch_key=None)

scdiagnostics/dimred.py

@@ -0,0 +1,96 @@
+import scanpy as sc
+import numpy as np
+import pandas as pd
+import altair as alt
+from .data import check_sparse, concat_real_sim
+
+
+def plot_umap(
+    adata,
+    color=None,
+    shape=None,
+    facet=None,
+    opacity=0.6,
+    n_comps=20,
+    n_neighbors=15,
+    transform=np.log1p,
+    **kwargs,
+):
+    mapping = {
+        "x": alt.X("UMAP1", scale=alt.Scale(zero=False)),
+        "y": alt.Y("UMAP2", scale=alt.Scale(zero=False)),
+        "color": color,
+        "shape": shape,
+    }
+    mapping = {k: v for k, v in mapping.items() if v is not None}
+
+    adata_ = adata.copy()
+    adata_.X = check_sparse(adata_.X)
+    Z = transform(adata_.X)
+    if Z.shape[1] == adata_.X.shape[1]:
+        adata_.X = transform(adata_.X)
+    else:
+        adata_ = adata_[:, : Z.shape[1]]
+        adata_.X = Z
+        adata_.var_names = [f"transform_{k}" for k in range(Z.shape[1])]
+
+    # umap on the top PCA dimensions
+    sc.pp.pca(adata_, n_comps=n_comps)
+    sc.pp.neighbors(adata_, n_neighbors=n_neighbors, n_pcs=n_comps)
+    sc.tl.umap(adata_, **kwargs)
+
+    # get umap embeddings
+    umap_df = pd.DataFrame(adata_.obsm["X_umap"], columns=["UMAP1", "UMAP2"])
+    umap_df = pd.concat([umap_df, adata_.obs.reset_index(drop=True)], axis=1)
+
+    # encode and visualize
+    alt.data_transformers.enable("vegafusion")
+    chart = alt.Chart(umap_df).mark_point(opacity=opacity).encode(**mapping)
+    if facet is not None:
+        chart = chart.facet(column=alt.Facet(facet))
+    return chart
+
+
+def plot_pca(
+    adata,
+    color=None,
+    shape=None,
+    facet=None,
+    opacity=0.6,
+    plot_dims=[0, 1],
+    transform=lambda x: np.log1p(x),
+    **kwargs,
+):
+    mapping = {
+        "x": alt.X("PCA1", scale=alt.Scale(zero=False)),
+        "y": alt.Y("PCA2", scale=alt.Scale(zero=False)),
+        "color": color,
+        "shape": shape,
+    }
+    mapping = {k: v for k, v in mapping.items() if v is not None}
+
+    adata_ = adata.copy()
+    adata_.X = check_sparse(adata_.X)
+    adata_.X = transform(adata_.X)
+
+    # get PCA scores
+    sc.pp.pca(adata_, **kwargs)
+    pca_df = pd.DataFrame(adata_.obsm["X_pca"][:, plot_dims], columns=["PCA1", "PCA2"])
+    pca_df = pd.concat([pca_df, adata_.obs.reset_index(drop=True)], axis=1)
+
+    # plot
+    alt.data_transformers.enable("vegafusion")
+    chart = alt.Chart(pca_df).mark_point(opacity=opacity).encode(**mapping)
+    if facet is not None:
+        chart = chart.facet(column=alt.Facet(facet))
+    return chart
+
+
+def compare_umap(real, simulated, transform=lambda x: x, **kwargs):
+    adata = concat_real_sim(real, simulated)
+    return plot_umap(adata, facet="source", transform=transform, **kwargs)
+
+
+def compare_pca(real, simulated, transform=lambda x: x, **kwargs):
+    adata = concat_real_sim(real, simulated)
+    return plot_pca(adata, facet="source", transform=transform, **kwargs)

scdiagnostics/marginal.py

@@ -0,0 +1,178 @@
+import numpy as np
+import pandas as pd
+import altair as alt
+import matplotlib.pyplot as plt
+from .data import prepare_dense, merge_samples
+
+
+def compare_summary(real, simulated, summary_fun, labels=None):
+    df = pd.DataFrame({"real": summary_fun(real), "simulated": summary_fun(simulated)})
+
+    identity = pd.DataFrame(
+        {
+            "real": [df["real"].min(), df["real"].max()],
+            "simulated": [df["real"].min(), df["real"].max()],
+        }
+    )
+    chart = alt.Chart(identity).mark_line(color="#dedede").encode(
+        x="real", y="simulated"
+    ) + alt.Chart(df).mark_circle().encode(x="real", y="simulated")
+
+    if labels is not None:
+        df["label"] = labels
+        chart = chart + alt.Chart(df[df["label"] != ""]).mark_text(
+            dx=6, dy=-6, align="left"
+        ).encode(x="real:Q", y="simulated:Q", text="label:N")
+
+    return chart
+
+
+def compare_means(real, simulated, transform=np.log1p, labels=None):
+    real_, simulated_ = prepare_dense(real, simulated)
+    summary = lambda a: np.asarray(transform(a.X).mean(axis=0)).flatten()
+    return compare_summary(real_, simulated_, summary, labels)
+
+
+def compare_variances(real, simulated, transform=np.log1p, labels=None):
+    real_, simulated_ = prepare_dense(real, simulated)
+    summary = lambda a: np.asarray(np.var(transform(a.X), axis=0)).flatten()
+    return compare_summary(real_, simulated_, summary, labels)
+
+
+def compare_standard_deviation(real, simulated, transform=np.log1p, labels=None):
+    real_, simulated_ = prepare_dense(real, simulated)
+    summary = lambda a: np.asarray(np.std(transform(a.X), axis=0)).flatten()
+    return compare_summary(real_, simulated_, summary, labels)
+
+
+def compare_histogram2(sim_data, real_data, idx):
+    sim = sim_data[:, idx]
+    real = real_data[:, idx]
+    b = np.linspace(min(min(sim), min(real)), max(max(sim), max(real)), 50)
+
+    plt.hist([real, sim], b, label=["Real", "Simulated"], histtype="bar")
+    plt.xlabel("x")
+    plt.ylabel("Density")
+    plt.legend()
+    plt.show()
+
+
+def compare_ecdf(adata, sim, var_names=None, max_plot=10, n_cols=5, transform=np.log1p, **kwargs):
+    if var_names is None:
+        var_names = adata.var_names[:max_plot]
+
+    combined = merge_samples(adata[:, var_names], sim[:, var_names])
+    combined["value"] = transform(combined["value"])
+    alt.data_transformers.enable("vegafusion")
+
+    plot = (
+        alt.Chart(combined)
+        .transform_window(
+            ecdf="cume_dist()", sort=[{"field": "value"}], groupby=["variable", "source"]
+        )
+        .mark_line(
+            interpolate="step-after",
+        )
+        .encode(
+            x="value:Q",
+            y="ecdf:Q",
+            color="source:N",
+            facet=alt.Facet(
+                "variable", sort=alt.EncodingSortField("value"), columns=n_cols
+            ),
+        )
+        .properties(**kwargs)
+    )
+    plot.show()
+    return plot, combined
+
+
+def compare_boxplot(adata, sim, var_names=None, max_plot=20, transform=np.log1p, **kwargs):
+    if var_names is None:
+        var_names = adata.var_names[:max_plot]
+
+    combined = merge_samples(adata[:, var_names], sim[:, var_names])
+    combined["value"] = transform(combined["value"])
+    alt.data_transformers.enable("vegafusion")
+
+    plot = (
+        alt.Chart(combined)
+        .mark_boxplot(extent="min-max")
+        .encode(
+            x=alt.X("value:Q").scale(zero=False),
+            y=alt.Y(
+                "variable:N",
+                sort=alt.EncodingSortField("mid_box_value", order="descending"),
+            ),
+            facet="source:N",
+        )
+        .properties(**kwargs)
+    )
+    plot.show()
+    return plot, combined
+
+
+def compare_histogram(adata, sim, var_names=None, max_plot=10, transform=np.log1p, ncol=5, **kwargs):
+    if var_names is None:
+        var_names = adata.var_names[:max_plot]
+
+    combined = merge_samples(adata[:, var_names], sim[:, var_names])
+    combined["value"] = transform(combined["value"])
+    alt.data_transformers.enable("vegafusion")
+
+    plot = (
+        alt.Chart(combined)
+        .mark_bar(opacity=0.7)
+        .encode(
+            x=alt.X("value:Q").bin(maxbins=20),
+            y=alt.Y("count()").stack(None),
+            color="source:N",
+            facet=alt.Facet(
+                "variable", sort=alt.EncodingSortField(f"bin_maxbins_{ncol}_value"), columns=ncol
+            ),
+        )
+        .properties(**kwargs)
+    )
+    plot.show()
+    return plot, combined
+
+
+def compare_moments(real, simulated, log_scale=True, labels=None, label_threshold=None):
+    """Compare real vs. simulated means and standard deviations gene-wise.
+
+    Parameters
+    ----------
+    log_scale : bool
+        If True, log-transform the gene-level statistics before plotting
+        (useful when counts span several orders of magnitude).
+    labels : array-like of str, optional
+        Gene labels aligned with the variables. Non-empty strings are
+        rendered as text marks next to the corresponding point.
+    label_threshold : float, optional
+        If provided, genes where the absolute difference between real and
+        simulated exceeds this value in either the mean or SD are labeled
+        with their gene name in both panels.
+    """
+    real_, simulated_ = prepare_dense(real, simulated)
+    transform = np.log if log_scale else lambda x: x
+
+    def gene_summary(stat_fn):
+        def summary(a):
+            return transform(np.asarray(stat_fn(a.X)).flatten())
+        return summary
+
+    means_summary = gene_summary(lambda X: X.mean(axis=0))
+    sd_summary = gene_summary(lambda X: np.std(X, axis=0))
+
+    if label_threshold is not None:
+        means_real = means_summary(real_)
+        means_sim = means_summary(simulated_)
+        sd_real = sd_summary(real_)
+        sd_sim = sd_summary(simulated_)
+        exceeds = (np.abs(means_real - means_sim) > label_threshold) | (np.abs(sd_real - sd_sim) > label_threshold)
+        labels = np.where(exceeds, real_.var_names, "")
+
+    return (
+        compare_summary(real_, simulated_, means_summary, labels).properties(title="Means")
+        | compare_summary(real_, simulated_, sd_summary, labels).properties(title="Standard Deviations")
+    )

scdiagnostics/spatial.py

@@ -0,0 +1,190 @@
+from scipy.interpolate import RBFInterpolator
+import scipy.sparse as sp
+import altair as alt
+import numpy as np
+import pandas as pd
+
+
+def make_grid_obs(adata, basis_cols, n_grid=30):
+    s1 = adata.obs["spatial1"].values
+    s2 = adata.obs["spatial2"].values
+    g1 = np.linspace(s1.min(), s1.max(), n_grid)
+    g2 = np.linspace(s2.min(), s2.max(), n_grid)
+    G1, G2 = np.meshgrid(g1, g2, indexing="ij")
+
+    grid_base = pd.DataFrame(
+        {
+            "spatial1": G1.ravel(),
+            "spatial2": G2.ravel(),
+            "bin1": pd.cut(G1.ravel(), bins=n_grid, labels=False, include_lowest=True),
+            "bin2": pd.cut(G2.ravel(), bins=n_grid, labels=False, include_lowest=True),
+        }
+    )
+    obs_bins = (
+        pd.DataFrame(
+            {
+                "bin1": pd.cut(s1, bins=n_grid, labels=False, include_lowest=True),
+                "bin2": pd.cut(s2, bins=n_grid, labels=False, include_lowest=True),
+            }
+        )
+        .dropna()
+        .astype(int)
+        .drop_duplicates()
+    )
+    occupied = set(map(tuple, obs_bins[["bin1", "bin2"]].to_numpy()))
+    keep = pd.Series(list(zip(grid_base["bin1"], grid_base["bin2"]))).isin(occupied)
+    grid_base = grid_base.loc[keep, ["spatial1", "spatial2"]].reset_index(drop=True)
+
+    cell_types = list(adata.obs["cell_type"].unique())
+    n_pts = len(grid_base)
+    grid_obs = pd.DataFrame(
+        {
+            "spatial1": np.tile(grid_base["spatial1"].values, len(cell_types)),
+            "spatial2": np.tile(grid_base["spatial2"].values, len(cell_types)),
+            "cell_type": np.repeat(cell_types, n_pts),
+        }
+    )
+
+    train_coords = adata.obs[["spatial1", "spatial2"]].values
+    grid_coords = grid_obs[["spatial1", "spatial2"]].values
+    interp = RBFInterpolator(train_coords, adata.obs[basis_cols].values, neighbors=50)
+    grid_basis = interp(grid_coords)
+    for i, col in enumerate(basis_cols):
+        grid_obs[col] = grid_basis[:, i]
+    return grid_obs
+
+
+def dense_gene_counts(adata, gene_idx):
+    if sp.issparse(adata.X):
+        return adata.X[:, gene_idx].toarray().ravel()
+    return np.array(adata.X)[:, gene_idx]
+
+
+def binned_obs_df(adata, gene_idx, n_obs_bins, value_col):
+    s1 = adata.obs["spatial1"].values
+    s2 = adata.obs["spatial2"].values
+    return pd.DataFrame(
+        {
+            "spatial1": pd.cut(s1, bins=n_obs_bins)
+            .map(lambda b: round(b.mid, 2))
+            .astype(float),
+            "spatial2": pd.cut(s2, bins=n_obs_bins)
+            .map(lambda b: round(b.mid, 2))
+            .astype(float),
+            value_col: dense_gene_counts(adata, gene_idx),
+        }
+    )
+
+
+def fitted_surface_df(sim, adata, basis_cols, gene_idx, pred_key, value_col, n_grid):
+    grid_obs = make_grid_obs(adata, basis_cols, n_grid)
+    n_ct = adata.obs["cell_type"].nunique()
+    n_pts = len(grid_obs) // n_ct
+    pred = np.log1p(sim.predict(obs=grid_obs)[pred_key][:, gene_idx])
+    pred_avg = pred.reshape(n_ct, n_pts).mean(axis=0)
+    ref = grid_obs.iloc[:n_pts]
+    return pd.DataFrame(
+        {
+            "spatial1": ref["spatial1"].round(2).values,
+            "spatial2": ref["spatial2"].round(2).values,
+            value_col: pred_avg,
+        }
+    )
+
+
+def surface_heatmaps(
+    fitted_df, obs_df, value_col, color_title, fitted_title, obs_title
+):
+    vmax = max(fitted_df[value_col].max(), obs_df[value_col].max())
+    scale = alt.Scale(domain=[0, vmax], scheme="viridis")
+
+    def heatmap(df, title):
+        return (
+            alt.Chart(df)
+            .mark_rect()
+            .encode(
+                x=alt.X("spatial1:O", title="", axis=alt.Axis(labels=False, ticks=False, domain=False)),
+                y=alt.Y("spatial2:O", title="", axis=alt.Axis(labels=False, ticks=False, domain=False)),
+                color=alt.Color(f"{value_col}:Q", scale=scale, title=color_title),
+            )
+            .properties(width=300, height=300, title=title)
+        )
+
+    return heatmap(fitted_df, fitted_title) | heatmap(obs_df, obs_title)
+
+
+def plot_mean_surface(sim, adata, basis_cols=["spatial1", "spatial2"], gene=None, n_grid=30, n_obs_bins=30):
+    # Handle gene specification - automatically detect if gene is index or name
+    if isinstance(gene, str):
+        gene_idx = adata.var_names.get_loc(gene)
+        gene_name = gene
+    elif isinstance(gene, int):
+        gene_idx = gene
+        gene_name = adata.var_names[gene_idx]
+    else:
+        raise ValueError("gene must be either integer index or string name")
+
+    fitted_df = fitted_surface_df(
+        sim,
+        adata,
+        basis_cols,
+        gene_idx,
+        pred_key="mean",
+        value_col="mu",
+        n_grid=n_grid,
+    )
+    obs_df = (
+        binned_obs_df(adata, gene_idx, n_obs_bins, value_col="mu")
+        .groupby(["spatial1", "spatial2"], as_index=False)["mu"]
+        .mean()
+        .assign(mu=lambda d: np.log1p(d["mu"]))
+    )
+    return surface_heatmaps(
+        fitted_df,
+        obs_df,
+        value_col="mu",
+        color_title="log(mu+1)",
+        fitted_title=f"Fitted mean(x) - Gene {gene_name}",
+        obs_title=f"Observed bin mean - Gene {gene_name}",
+    )
+
+
+def plot_dispersion_surface(sim, adata, basis_cols=["spatial1", "spatial2"], gene=None, n_grid=10, n_obs_bins=10):
+    if isinstance(gene, str):
+        gene_idx = adata.var_names.get_loc(gene)
+        gene_name = gene
+    elif isinstance(gene, int):
+        gene_idx = gene
+        gene_name = adata.var_names[gene_idx]
+    else:
+        raise ValueError("gene must be either integer index or string name")
+
+    fitted_df = fitted_surface_df(
+        sim,
+        adata,
+        basis_cols,
+        gene_idx,
+        pred_key="dispersion",
+        value_col="dispersion",
+        n_grid=n_grid,
+    )
+    obs_df = (
+        binned_obs_df(adata, gene_idx, n_obs_bins, value_col="count")
+        .groupby(["spatial1", "spatial2"], as_index=False)["count"]
+        .agg(mu="mean", var="var")
+        .assign(
+            dispersion=lambda d: np.where(
+                d["var"] > d["mu"], d["mu"] ** 2 / (d["var"] - d["mu"]), np.nan
+            )
+        )
+        .assign(dispersion=lambda d: np.log1p(d["dispersion"]))
+        .dropna(subset=["dispersion"])
+    )
+    return surface_heatmaps(
+        fitted_df,
+        obs_df,
+        value_col="dispersion",
+        color_title="log(dispersion+1)",
+        fitted_title=f"Fitted dispersion(x) - Gene {gene_name}",
+        obs_title=f"Observed bin dispersion - Gene {gene_name}",
+    )

scdiagnostics-0.0.99.1.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: scdiagnostics
+Version: 0.0.99.1
+Author-email: Kris Sankaran <ksankaran@wisc.edu>
+Requires-Python: >=3.10
+Requires-Dist: altair==6.0.0
+Requires-Dist: pyarrow==23.0.1
+Requires-Dist: scanpy==1.12
+Requires-Dist: scipy==1.15.2
+Requires-Dist: vegafusion==2.0.3
+Requires-Dist: vl-convert-python>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"

scdiagnostics-0.0.99.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+scdiagnostics/__init__.py,sha256=OtPZabaI4wXtscFOyULey_9bN6-2bb7oTYf6t7WXAq8,348
+scdiagnostics/data.py,sha256=pmefSH7bmKzP4uWV-XLHLFdgPlRra6j8GkbwCMZGCmQ,998
+scdiagnostics/dimred.py,sha256=g2JXwkYz0H5B6z3-4rSM3sURAyTPnU_PnffHXuQdXuM,2821
+scdiagnostics/marginal.py,sha256=rwPnjJisTpP44bsSqnJdMjQkn9JgASWYlVZhMB_Hak8,6186
+scdiagnostics/spatial.py,sha256=Z-zGrw9lfc3ZPW49PHXMeeNIjCLVyDMO1qXRwS3i_0U,6464
+scdiagnostics-0.0.99.1.dist-info/METADATA,sha256=TEBpxAheLQEomZrSQCAVhnwOpO2Z_5PoOx4jRW-I5GE,417
+scdiagnostics-0.0.99.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scdiagnostics-0.0.99.1.dist-info/top_level.txt,sha256=bXGLWwICaXihQ7AVa6iCbiIYWyIzYvuC3y7FvFsuB1I,14
+scdiagnostics-0.0.99.1.dist-info/RECORD,,

scdiagnostics-0.0.99.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scdiagnostics-0.0.99.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+scdiagnostics