scdiagnostics 0.1.2__tar.gz → 0.2.0__tar.gz

{scdiagnostics-0.1.2/src/scdiagnostics.egg-info → scdiagnostics-0.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: scdiagnostics
-Version: 0.1.2
+Version: 0.2.0
 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: 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"

{scdiagnostics-0.1.2 → scdiagnostics-0.2.0}/pyproject.toml

@@ -7,15 +7,15 @@ name = "scdiagnostics"
 authors = [
   { name="Kris Sankaran", email="ksankaran@wisc.edu" },
 ]
-version = "0.1.2"
+version = "0.2.0"
 description = ""
 requires-python = ">=3.10"
 dependencies = [
-    "altair==6.0.0",
-    "pyarrow==23.0.1",
-    "scanpy==1.12",
-    "scipy==1.15.2",
-    "vegafusion==2.0.3",
+    "altair>=6.0.0",
+    "pyarrow>=23.0.1",
+    "scanpy>=1.12",
+    "scipy>=1.15.2",
+    "vegafusion>=2.0.3",
     "vl-convert-python>=1.8.0"
 ]
 

{scdiagnostics-0.1.2 → scdiagnostics-0.2.0}/src/scdiagnostics/__init__.py

@@ -1,4 +1,3 @@
-from .pseudotime import plot_fitted_curve
 from .bivariate import compare_correlation, compare_gene_pairs
 from .dimred import plot_umap, plot_pca, compare_pca, compare_umap, overlay_expression
 from .marginal import (
@@ -13,8 +12,9 @@ from .marginal import (
     compare_histogram2,
     gene_summary,
 )
-from .spatial import (
-    plot_dispersion_surface,
-    plot_mean_surface,
-    plot_spatial
-)
+from .spatial import plot_dispersion_surface, plot_mean_surface, plot_spatial
+from .plot_fit import (
+    plot_gene_correlations,
+    plot_fit_by_covariate,
+    plot_sampled_expression_by_covariate,
+)

scdiagnostics-0.2.0/src/scdiagnostics/plot_fit.py

@@ -0,0 +1,283 @@
+"""Diagnostic plots for assessing fitted single-cell generative models.
+
+The plotting functions in this module compare observed expression with predictions 
+or samples from a fitted model.
+"""
+
+import altair as alt
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+
+alt.data_transformers.enable("vegafusion")
+alt.renderers.enable("png")
+
+
+def plot_gene_correlations(sim, num_genes=5):
+    """Plot pairwise expression relationships in a simulated sample.
+
+    Expression is transformed with ``log1p`` before plotting. The first
+    ``num_genes`` genes in the sampled data are shown as a scatterplot matrix.
+    """
+    sampled = sim.sample()
+    expression = (
+        sampled.X.toarray() if sp.issparse(sampled.X) else np.asarray(sampled.X)
+    )
+    expression = pd.DataFrame(
+        np.log1p(expression),
+        columns=sampled.var_names,
+        index=sampled.obs.index,
+    )
+
+    sampled_subset = pd.concat([expression.iloc[:, :num_genes], sampled.obs], axis=1)
+    genes = list(sampled.var_names[:num_genes])
+    return (
+        alt.Chart(sampled_subset)
+        .mark_circle(opacity=1, size=1)
+        .encode(
+            alt.X(alt.repeat("column"), type="quantitative"),
+            alt.Y(alt.repeat("row"), type="quantitative"),
+        )
+        .properties(width=40, height=40)
+        .repeat(row=genes, column=genes)
+        .configure_axis(labelFontSize=9, titleFontSize=9)
+    )
+
+
+_DISTRIBUTIONS = {"negbin", "poisson", "bernoulli", "gaussian"}
+
+
+def _validate_distribution(distribution):
+    distribution = distribution.lower()
+    if distribution not in _DISTRIBUTIONS:
+        options = ", ".join(sorted(_DISTRIBUTIONS))
+        raise ValueError(f"distribution must be one of: {options}")
+    return distribution
+
+
+def _covariate_info(sce, covariate):
+    if covariate not in sce.obs.columns:
+        raise KeyError(f"{covariate!r} is not a column in sce.obs")
+
+    values = sce.obs[covariate]
+    if values.isna().any():
+        raise ValueError(f"sce.obs[{covariate!r}] contains missing values")
+    numeric = pd.api.types.is_numeric_dtype(values) and not pd.api.types.is_bool_dtype(
+        values
+    )
+    if numeric:
+        return values, True, None
+
+    values = values.astype(str)
+    return values, False, list(dict.fromkeys(values))
+
+
+def _standard_deviation(predictions, gene_ix, distribution):
+    """Return the fitted standard deviation."""
+    mean = np.asarray(predictions["mean"][:, gene_ix])
+    if distribution == "negbin":
+        dispersion = np.asarray(predictions["dispersion"][:, gene_ix])
+        return np.sqrt(mean + mean**2 / dispersion)
+    if distribution == "poisson":
+        return np.sqrt(mean)
+    if distribution == "gaussian":
+        return np.asarray(predictions["sdev"][:, gene_ix])
+    return np.sqrt(np.clip(mean * (1 - mean), 0, None))
+
+
+def _numeric_fit_chart(observed, mean, sdev, covariate, distribution):
+    x = alt.X(field=covariate, type="quantitative", title=covariate)
+    y = alt.Y("expression:Q", title="Expression")
+    points = alt.Chart(observed).mark_circle(size=20, opacity=0.35).encode(x=x, y=y)
+    fitted = pd.DataFrame({covariate: observed[covariate], "mean": mean})
+
+    if distribution == "bernoulli":
+        fitted = fitted.groupby(covariate, as_index=False, sort=True).mean()
+        return points + alt.Chart(fitted).mark_circle(size=20, color="red").encode(
+            x=x, y=alt.Y("mean:Q", title="Expression")
+        )
+
+    fitted["second_moment"] = sdev**2 + fitted["mean"] ** 2
+    fitted = fitted.groupby(covariate, as_index=False, sort=True).mean()
+    fitted["sdev"] = np.sqrt(
+        np.clip(fitted["second_moment"] - fitted["mean"] ** 2, 0, None)
+    )
+    fitted["lower"] = fitted["mean"] - fitted["sdev"]
+    fitted["upper"] = fitted["mean"] + fitted["sdev"]
+    band = alt.Chart(fitted).mark_area(opacity=0.3, color="orange").encode(
+        x=x, y=alt.Y("lower:Q", title="Expression"), y2="upper:Q"
+    )
+    line = alt.Chart(fitted).mark_line(color="red").encode(
+        x=x, y=alt.Y("mean:Q", title="Expression")
+    )
+    return band + line + points
+
+
+def _categorical_fit_chart(observed, mean, sdev, covariate, category_order):
+    observed = observed.copy()
+    observed["jitter"] = np.random.default_rng(0).uniform(-0.5, 0.5, len(observed))
+    fitted = pd.DataFrame(
+        {covariate: observed[covariate], "mean": mean, "sdev": sdev}
+    )
+    fitted["second_moment"] = fitted["sdev"] ** 2 + fitted["mean"] ** 2
+    fitted = fitted.groupby(covariate, sort=False, observed=True, as_index=False).mean()
+    fitted["sdev"] = np.sqrt(
+        np.clip(fitted["second_moment"] - fitted["mean"] ** 2, 0, None)
+    )
+    fitted["lower"] = fitted["mean"] - fitted["sdev"]
+    fitted["upper"] = fitted["mean"] + fitted["sdev"]
+    fitted["jitter"] = 0.0
+    x = alt.X(
+        field=covariate, type="nominal", title=covariate, sort=category_order,
+    )
+    jitter = alt.XOffset(
+        "jitter:Q", scale=alt.Scale(domain=[-0.5, 0.5])
+    )
+
+    error_bars = alt.Chart(fitted).mark_rule(color="red").encode(
+        x=x,
+        xOffset=jitter,
+        y=alt.Y("lower:Q", title="Expression"),
+        y2="upper:Q",
+    )
+    lower_caps = alt.Chart(fitted).mark_tick(
+        color="red", orient="horizontal", size=24
+    ).encode(x=x, xOffset=jitter, y="lower:Q")
+    upper_caps = alt.Chart(fitted).mark_tick(
+        color="red", orient="horizontal", size=24
+    ).encode(x=x, xOffset=jitter, y="upper:Q")
+    fitted_means = alt.Chart(fitted).mark_point(color="red", filled=True, size=55).encode(
+        x=x, xOffset=jitter, y=alt.Y("mean:Q", title="Expression")
+    )
+    points = alt.Chart(observed).mark_circle(size=24, opacity=0.35).encode(
+        x=x,
+        xOffset=jitter,
+        y=alt.Y("expression:Q", title="Expression"),
+    )
+    return points + error_bars + lower_caps + upper_caps + fitted_means
+
+
+def plot_fit_by_covariate(
+    sim,
+    sce,
+    distribution="negbin",
+    covariate="pseudotime",
+    num_genes=5,
+):
+    """Plot fitted gene expression against a numeric or categorical covariate.
+
+    Numeric covariates show observations and fitted values; negative-binomial,
+    Poisson, and Gaussian fits also show a one-standard-deviation band.
+    Categorical covariates show jittered observations with the model's
+    category-level mean and one-standard-deviation error bars.
+
+    Parameters
+    ----------
+    distribution : {"negbin", "poisson", "bernoulli", "gaussian"}
+        Distribution used by the fitted model.
+    covariate : str
+        Column in ``sce.obs``. Its dtype determines which plot is produced.
+    """
+    distribution = _validate_distribution(distribution)
+    values, numeric, category_order = _covariate_info(sce, covariate)
+
+    expression = sce.X.toarray() if sp.issparse(sce.X) else np.asarray(sce.X)
+    predictions = sim.predict(sce.obs)
+    charts = []
+    for ix in range(min(num_genes, sce.n_vars)):
+        mean = np.asarray(predictions["mean"][:, ix])
+        observed = pd.DataFrame(
+            {covariate: values.to_numpy(), "expression": expression[:, ix]}
+        )
+        sdev = _standard_deviation(predictions, ix, distribution)
+        if numeric:
+            chart = _numeric_fit_chart(
+                observed, mean, sdev, covariate, distribution
+            )
+        else:
+            chart = _categorical_fit_chart(
+                observed, mean, sdev, covariate, category_order
+            )
+        charts.append(
+            chart.properties(
+                title=f"Gene {ix}: {sce.var_names[ix]}", width=300, height=200
+            )
+        )
+
+    return alt.vconcat(*charts)
+
+
+def plot_sampled_expression_by_covariate(
+    sim,
+    sce,
+    covariate="pseudotime",
+    num_genes=5,
+    jitter=False,
+):
+    """Compare real and simulated expression by a numeric or categorical covariate.
+
+    A sample is drawn from the fitted model at ``sce.obs``. Numeric covariates
+    use an overlaid scatter plot. Categorical covariates use horizontally
+    jittered points within each category. Color distinguishes real and simulated
+    expression.
+
+    Parameters
+    ----------
+    covariate : str
+        Column in ``sce.obs``. Its dtype determines which plot is produced.
+    jitter : bool
+        Add small vertical jitter to expression values. Horizontal jitter is
+        always applied for categorical covariates.
+    """
+    values, numeric, category_order = _covariate_info(sce, covariate)
+
+    real_X = sce.X.toarray() if sp.issparse(sce.X) else np.asarray(sce.X)
+    sampled = sim.sample(sce.obs)
+    sim_X = sampled.X.toarray() if sp.issparse(sampled.X) else np.asarray(sampled.X)
+    if real_X.shape != sim_X.shape:
+        raise ValueError("real and simulated expression matrices must have equal shapes")
+
+    rng = np.random.default_rng(0)
+    charts = []
+    for ix in range(min(num_genes, sce.n_vars)):
+        real_values = real_X[:, ix]
+        simulated_values = sim_X[:, ix]
+        if jitter:
+            real_values = real_values + rng.normal(0, 0.1, len(values))
+            simulated_values = simulated_values + rng.normal(0, 0.1, len(values))
+
+        combined = pd.DataFrame(
+            {
+                covariate: np.tile(values.to_numpy(), 2),
+                "expression": np.concatenate([real_values, simulated_values]),
+                "type": np.repeat(["real", "simulated"], len(values)),
+            }
+        )
+        x = alt.X(
+            field=covariate,
+            type="quantitative" if numeric else "nominal",
+            title=covariate,
+            sort=None if numeric else category_order,
+        )
+        if not numeric:
+            combined["x_jitter"] = rng.uniform(-0.5, 0.5, len(combined))
+
+        encoding = {
+            "x": x,
+            "y": alt.Y("expression:Q", title="Expression"),
+            "color": alt.Color("type:N", title=None),
+        }
+        if not numeric:
+            encoding["xOffset"] = alt.XOffset(
+                "x_jitter:Q", scale=alt.Scale(domain=[-0.5, 0.5])
+            )
+        charts.append(
+            alt.Chart(combined)
+            .mark_circle(size=24, opacity=0.35)
+            .encode(**encoding)
+            .properties(
+                title=f"Gene {ix}: {sce.var_names[ix]}", width=300, height=200
+            )
+        )
+
+    return alt.vconcat(*charts)

{scdiagnostics-0.1.2 → scdiagnostics-0.2.0/src/scdiagnostics.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: scdiagnostics
-Version: 0.1.2
+Version: 0.2.0
 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: 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"

{scdiagnostics-0.1.2 → scdiagnostics-0.2.0}/src/scdiagnostics.egg-info/SOURCES.txt

@@ -10,7 +10,7 @@ src/scdiagnostics/bivariate.py
 src/scdiagnostics/data.py
 src/scdiagnostics/dimred.py
 src/scdiagnostics/marginal.py
-src/scdiagnostics/pseudotime.py
+src/scdiagnostics/plot_fit.py
 src/scdiagnostics/spatial.py
 src/scdiagnostics.egg-info/PKG-INFO
 src/scdiagnostics.egg-info/SOURCES.txt

scdiagnostics-0.2.0/src/scdiagnostics.egg-info/requires.txt

@@ -0,0 +1,10 @@
+altair>=6.0.0
+pyarrow>=23.0.1
+scanpy>=1.12
+scipy>=1.15.2
+vegafusion>=2.0.3
+vl-convert-python>=1.8.0
+
+[dev]
+pytest
+ruff

scdiagnostics-0.1.2/src/scdiagnostics/pseudotime.py

@@ -1,151 +0,0 @@
-"""Plot observed expression and model fitted mean/sd along one-dimensional pseudotime."""
-
-import altair as alt
-import pandas as pd
-
-
-def plot_fitted_curve(
-    observed,
-    fitted,
-    *,
-    x,
-    y,
-    mean="mean",
-    group=None,
-    model=None,
-    lower=None,
-    upper=None,
-    n_bins=10,
-    transform=None,
-    y_title=None,
-    width=300,
-    height=220,
-    columns=2,
-):
-    """Plot observations and model fits against one-dimensional time or pseudotime.
-
-    Parameters
-    ----------
-    observed, fitted : pandas.DataFrame
-        Two pandas DFs. Observed should have columns `x`, `y`, and optionally a
-        `group`.  Fitted should have `x`, `mean`, optionally `group`, `model`,
-        and the intervals.  Each `model` will get a curve.
-    x, y, mean : str
-        Column names for the feature to plot against, the response, and the
-        fitted mean.
-    group, model : str, optional
-        Column names to facet by (group) and to use for separate lines (model).
-    lower, upper : str, optional
-        Column names for the intervals.
-    n_bins : int or None
-        Equal-width bins used for averaging. Defaults to None.
-    transform : callable, optional
-        Transform applied after averaging within bins.  E.g., np.log1p plots
-        log(1 + E[Y|x]).
-    y_title : str, optional
-        Axis label.
-    columns : int, default 2
-        Number of facet columns.
-
-    Returns
-    -------
-    altair.LayerChart or altair.FacetChart
-        Observations, fitted curves, and optional intervals and binned means.
-    """
-    obs, fit = _prepare_tables(
-        observed, fitted, x=x, y=y, mean=mean, group=group, model=model,
-        lower=lower, upper=upper,
-    )
-    tables = [obs, fit]
-    if n_bins is not None:
-        tables.append(_bin_observations(obs, n_bins))
-    data = pd.concat(tables, ignore_index=True)
-    if transform is not None:
-        data = _transform_response(data, transform)
-
-    chart = _curve_layers(
-        data, x_title=x, y_title=y_title or y, model_title=model or "Model",
-        show_intervals=lower is not None, show_bins=n_bins is not None,
-    ).properties(width=width, height=height)
-    if group is not None:
-        chart = chart.facet(facet=alt.Facet("_group:N", title=group), columns=columns)
-        chart = chart.resolve_scale(y="independent")
-    return chart
-
-
-def _prepare_tables(observed, fitted, *, x, y, mean, group, model, lower, upper):
-    """Copy input columns into the shared internal schema used by plot layers."""
-    obs = pd.DataFrame({
-        "_x": observed[x].to_numpy(),
-        "_y": observed[y].to_numpy(),
-        "_group": observed[group].to_numpy() if group is not None else "All",
-        "_kind": "observed",
-    })
-    fit = pd.DataFrame({
-        "_x": fitted[x].to_numpy(),
-        "_y": fitted[mean].to_numpy(),
-        "_group": fitted[group].to_numpy() if group is not None else "All",
-        "_model": fitted[model].to_numpy() if model is not None else "Fitted mean",
-        "_kind": "fitted",
-    })
-    if lower is not None:
-        fit["_lower"] = fitted[lower].to_numpy()
-        fit["_upper"] = fitted[upper].to_numpy()
-    return obs, fit
-
-
-def _bin_observations(observed, n_bins):
-    """Average time and response in equal-width bins within each group."""
-    tables = []
-    for label, part in observed.groupby("_group", sort=False, observed=True):
-        time_bins = pd.cut(part["_x"], n_bins)
-        means = part.groupby(time_bins, observed=True)[["_x", "_y"]].mean()
-        tables.append(means.assign(_group=label, _kind="binned"))
-    if not tables:
-        return observed.iloc[:0].copy()
-    return pd.concat(tables, ignore_index=True)
-
-
-def _transform_response(data, transform):
-    """Transform response columns, leaving absent layer-specific values alone."""
-    data = data.copy()
-    for column in ("_y", "_lower", "_upper"):
-        data[column] = data[column].astype(float)
-        valid = data[column].notna()
-        data.loc[valid, column] = transform(data.loc[valid, column].to_numpy())
-    return data
-
-
-def _curve_layers(data, *, x_title, y_title, model_title, show_intervals, show_bins):
-    """Compose layers back-to-front using one shared dataset for faceting."""
-    base = alt.Chart(data).encode(
-        x=alt.X("_x:Q", title=x_title, scale=alt.Scale(zero=False)),
-        y=alt.Y("_y:Q", title=y_title, scale=alt.Scale(zero=False)),
-    )
-    fitted = base.transform_filter(alt.datum._kind == "fitted")
-    color = alt.Color("_model:N", title=model_title)
-    observations = base.transform_filter(alt.datum._kind == "observed").mark_circle(
-        color="black", opacity=0.25, size=15,
-    )
-    curves = fitted.mark_line().encode(color=color, order="_x:Q")
-
-    layers = []
-    if show_intervals:
-        bands = fitted.mark_area(opacity=0.12).encode(
-            y=alt.Y("_lower:Q", title=y_title, stack=None, scale=alt.Scale(zero=False)),
-            y2="_upper:Q",
-            color=color,
-        )
-        layers.append(bands)
-    layers.extend([observations, curves])
-    if show_bins:
-        binned_means = (
-            base.transform_filter(alt.datum._kind == "binned")
-            .mark_point(shape="diamond", filled=True, color="#6E9CB6", size=55)
-            .encode(tooltip=[
-                alt.Tooltip("_x:Q", title=x_title),
-                alt.Tooltip("_y:Q", title="Observed bin mean"),
-            ])
-        )
-        layers.append(binned_means)
-    return alt.layer(*layers)

scdiagnostics-0.1.2/src/scdiagnostics.egg-info/requires.txt

@@ -1,10 +0,0 @@
-altair==6.0.0
-pyarrow==23.0.1
-scanpy==1.12
-scipy==1.15.2
-vegafusion==2.0.3
-vl-convert-python>=1.8.0
-
-[dev]
-pytest
-ruff