lotsofcells 0.0.0__tar.gz

lotsofcells-0.0.0/.github/workflows/publish.yml

@@ -0,0 +1,127 @@
+name: Release
+
+# Push a tag like `v0.4.0` to trigger a build + PyPI publish + GitHub release.
+# Can also be run manually (workflow_dispatch) for dry-runs without publishing.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  # ----------------------------------------------------------------------
+  # 1. Sanity tests on every supported Python version.
+  # ----------------------------------------------------------------------
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Import smoke test
+        run: |
+          python -c "import lotsofcells; print('lotsofcells', lotsofcells.__version__)"
+          python -c "from lotsofcells import lots_of_cells, entropy_score, bar_chart, waffle_chart, polar_chart, density_chart, dynamics_chart, plot_abundance_test; print('imports OK')"
+
+  # ----------------------------------------------------------------------
+  # 2. Build sdist + wheel.
+  # ----------------------------------------------------------------------
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Check distributions
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 7
+
+  # ----------------------------------------------------------------------
+  # 3. Publish to PyPI using OIDC trusted publishing.
+  #    Only runs on real tag pushes — not on workflow_dispatch dry runs.
+  #    Requires one-time setup on PyPI (see notes below).
+  # ----------------------------------------------------------------------
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lotsofcells
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ----------------------------------------------------------------------
+  # 4. Create a GitHub Release with the built sdist + wheel attached.
+  # ----------------------------------------------------------------------
+  github-release:
+    name: GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            dist/* \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes

lotsofcells-0.0.0/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+.Rapp.history
+.Rbuildignore
+.Rhistory
+.Rproj.user
+lotOfCells.Rproj
+LotOfCells.Rproj
+

lotsofcells-0.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: lotsofcells
+Version: 0.0.0
+Summary: Python port of lotsOfCells: proportion-test statistics and visualization on single-cell metadata. Compatible with scanpy/AnnData and spatial transcriptomics.
+Author: Oscar Gonzalez-Velasco
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: anndata>=0.9
+Provides-Extra: scanpy
+Requires-Dist: scanpy>=1.9; extra == "scanpy"
+Provides-Extra: spatial
+Requires-Dist: spatialdata>=0.1; extra == "spatial"
+Provides-Extra: mudata
+Requires-Dist: mudata>=0.2; extra == "mudata"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"

lotsofcells-0.0.0/example.py

@@ -0,0 +1,104 @@
+"""End-to-end example mirroring the R README.
+
+Run from the `python/` folder:
+    python -m pip install -e .
+    python example.py
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+import lotsofcells as loc
+
+
+def simulated_metadata() -> pd.DataFrame:
+    """Reproduce the simulated dataset from the R README."""
+    sample_blocks = [
+        ("A", "time 0h", "wt",  [("CellTypeA", 700), ("CellTypeB", 300), ("CellTypeC", 500), ("CellTypeD", 1000)]),
+        ("B", "time 0h", "mut", [("CellTypeA", 1700), ("CellTypeB", 350), ("CellTypeC", 550), ("CellTypeD", 800)]),
+        ("C", "time 2h", "wt",  [("CellTypeA", 1200), ("CellTypeB", 200), ("CellTypeC", 420), ("CellTypeD", 800)]),
+        ("D", "time 2h", "mut", [("CellTypeA", 500),  ("CellTypeB", 1000), ("CellTypeC", 10), ("CellTypeD", 1200)]),
+        ("E", "time 4h", "wt",  [("CellTypeA", 550),  ("CellTypeB", 990),  ("CellTypeC", 10), ("CellTypeD", 1100)]),
+        ("F", "time 4h", "mut", [("CellTypeA", 1350), ("CellTypeB", 590),  ("CellTypeC", 300), ("CellTypeD", 600)]),
+    ]
+    rows = []
+    for sample, t, cond, ct_counts in sample_blocks:
+        for ct, n in ct_counts:
+            for _ in range(n):
+                rows.append((sample, ct, t, cond))
+    return pd.DataFrame(rows, columns=["sample", "cell_type", "times", "condition"])
+
+
+def main():
+    rng = np.random.default_rng(0)
+    meta = simulated_metadata()
+    print("Metadata head:")
+    print(meta.head())
+    print("Shape:", meta.shape)
+
+    print("\n--- 2-condition test (mut vs wt) ---")
+    res = loc.lots_of_cells(
+        meta,
+        main_variable="condition",
+        subtype_variable="cell_type",
+        sample_id="sample",
+        label_order=["mut", "wt"],
+        permutations=300,
+        seed=0,
+        plot=False,
+    )
+    print(res)
+
+    print("\n--- >2-condition gamma rank (time 0h, 2h, 4h) ---")
+    gamma = loc.lots_of_cells(
+        meta,
+        main_variable="times",
+        subtype_variable="cell_type",
+        sample_id="sample",
+        label_order=["time 0h", "time 2h", "time 4h"],
+        permutations=100,
+        seed=0,
+        plot=False,
+    )
+    print(gamma)
+
+    print("\n--- Symmetric divergence score (mut vs wt) ---")
+    ent = loc.entropy_score(
+        meta,
+        main_variable="condition",
+        subtype_variable="cell_type",
+        label_order=["mut", "wt"],
+        permutations=200,
+        seed=0,
+        plot=False,
+    )
+    print(ent)
+
+    print("\n--- AnnData round-trip ---")
+    try:
+        import anndata as ad
+        adata = ad.AnnData(np.zeros((len(meta), 1), dtype=float), obs=meta.copy())
+        adata.obs_names = adata.obs_names.astype(str)
+        # Simulate a numerical feature so density_chart works on .obs
+        adata.obs["n_features_RNA"] = np.abs(
+            rng.normal(loc=2500, scale=600, size=adata.n_obs)
+        )
+        res2 = loc.lots_of_cells(
+            adata,
+            main_variable="condition",
+            subtype_variable="cell_type",
+            sample_id="sample",
+            label_order=["mut", "wt"],
+            permutations=100,
+            seed=0,
+            plot=False,
+        )
+        assert res2.shape[0] == res.shape[0]
+        print("AnnData path OK. Same #covariables in result.")
+    except ImportError:
+        print("(anndata not installed — skipping AnnData round-trip)")
+
+
+if __name__ == "__main__":
+    main()

lotsofcells-0.0.0/lotsofcells/__init__.py

@@ -0,0 +1,39 @@
+"""lotsofcells: proportion-test statistics and visualization on single-cell metadata.
+
+Python port of the R package `lotsOfCells`, designed for the scanpy / AnnData
+framework. Compatible with single-cell (`AnnData`) and spatial transcriptomics
+(`SpatialData` / `MuData`) objects, since metadata is read from `.obs`.
+
+References
+----------
+Óscar González-Velasco; lotsOfCells: data visualization and statistics of
+single cell metadata. bioRxiv 2024.05.23.595582;
+https://doi.org/10.1101/2024.05.23.595582
+"""
+
+from ._utils import get_metadata, get_palette
+from .lotsofcells import lots_of_cells
+from .entropy import entropy_score
+from .plots import (
+    bar_chart,
+    waffle_chart,
+    polar_chart,
+    density_chart,
+    dynamics_chart,
+    plot_abundance_test,
+)
+
+__all__ = [
+    "get_metadata",
+    "get_palette",
+    "lots_of_cells",
+    "entropy_score",
+    "bar_chart",
+    "waffle_chart",
+    "polar_chart",
+    "density_chart",
+    "dynamics_chart",
+    "plot_abundance_test",
+]
+
+__version__ = "0.3.0"

lotsofcells-0.0.0/lotsofcells/_stats.py

@@ -0,0 +1,279 @@
+"""Internal statistical primitives.
+
+Direct ports of the R helpers `cellToGamma`, `cellToGammaOriginal` and
+`cellToMontecarlo`. Implementation choices (pseudocounts, transforms) match
+the R version exactly so results are comparable.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Sequence, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+
+# --- Transformations used everywhere ---------------------------------------------------
+
+def pseudo_count(counts: np.ndarray) -> np.ndarray:
+    """`counts + 0.5` — matches the R pseudocount in lotsOfCells.R."""
+    return counts + 0.5
+
+
+def pseudo_count_arcsin(counts: np.ndarray) -> np.ndarray:
+    """`counts + sqrt(counts^2 + 1)` — matches the R pseudocount in entropyScore.R."""
+    return counts + np.sqrt(counts * counts + 1)
+
+
+def asrt(p: np.ndarray) -> np.ndarray:
+    """Arcsin square-root transform (Anscombe-style)."""
+    return np.arcsin(np.sqrt(np.clip(p, 0, 1)))
+
+
+def logit(f: np.ndarray) -> np.ndarray:
+    return np.log(f / (1 - f))
+
+
+def geom_mean(x: np.ndarray) -> float:
+    """Geometric mean over the strictly positive entries of ``x``.
+
+    Note: this intentionally diverges from R's literal ``exp(mean(log(x)))``,
+    which collapses to 0 whenever **any** entry is 0. In the symmetric
+    divergence formula used by `entropyScore`, a zero in
+    ``|p * log2(p/q)|`` means ``p[i] == q[i]`` (the two distributions agree
+    on cell type ``i``); such a term should contribute *nothing* to the
+    divergence — not zero out the entire score.
+
+    The 1-class test makes this critical: random partitions inside a single
+    condition often share integer totals after the ``int(sqrt(count_s))``
+    crowd sizing, which forces ``p[i] == q[i]`` for any cell type missing
+    from both subsamples. With strict R semantics every iteration collapses
+    to 0; with this version the geom_mean is taken over the cell types
+    that actually disagree.
+
+    If every entry is zero, the divergence really is 0.
+    """
+    x = np.asarray(x, dtype=float)
+    nonzero = x[x > 0]
+    if nonzero.size == 0:
+        return 0.0
+    return float(np.exp(np.mean(np.log(nonzero))))
+
+
+# --- Contingency tables --------------------------------------------------------------
+
+def _table(groups: Sequence[str], covariable: Sequence[str]) -> pd.DataFrame:
+    """Equivalent of R `table(data.frame(groups, covariable))`."""
+    return (
+        pd.crosstab(pd.Series(groups, name="groups"),
+                    pd.Series(covariable, name="covariable"))
+    )
+
+
+def _ensure_rows(tab: pd.DataFrame, label_order: Sequence[str]) -> pd.DataFrame:
+    """Add zero rows for any missing labels and reindex."""
+    missing = [l for l in label_order if l not in tab.index]
+    if missing:
+        z = pd.DataFrame(0, index=missing, columns=tab.columns)
+        tab = pd.concat([tab, z])
+    return tab.reindex(label_order)
+
+
+def _ensure_cols(tab: pd.DataFrame, indexes: Sequence[str]) -> pd.DataFrame:
+    missing = [c for c in indexes if c not in tab.columns]
+    if missing:
+        for m in missing:
+            tab[m] = 0
+    return tab[list(indexes)]
+
+
+# --- Goodman & Kruskal gamma rank correlation ----------------------------------------
+
+def _ranked_proportions(
+    tab: pd.DataFrame,
+    label_order: Sequence[str],
+    indexes: Sequence[str],
+) -> np.ndarray:
+    """Rows=label_order, cols=covariables.
+
+    Computes per-covariable proportions then ranks across labels.
+    Mirrors `t(apply(dftmp,2,function(row){row/(sum(row)+0.1)}))[labelOrder, indexes]`
+    followed by `t(apply(.,1,rank))`.
+    """
+    tab = _ensure_rows(tab, label_order)
+    tab = _ensure_cols(tab, indexes)
+    # column-wise proportions: row/(sum(row)+0.1) per column => divide each column by (col_sum+0.1)
+    col_sums = tab.values.sum(axis=0) + 0.1  # shape (n_cov,)
+    contig = tab.values / col_sums[np.newaxis, :]  # rows = labels in label_order
+    # rank within each row across covariables (R: apply(contig_tab,1,rank))
+    # 'average' ties to mirror base::rank's default
+    ranks = np.apply_along_axis(_rank_avg, 1, contig)
+    return ranks  # shape (n_labels, n_cov)
+
+
+def _rank_avg(x: np.ndarray) -> np.ndarray:
+    """Equivalent of R base::rank(x, ties.method='average')."""
+    order = np.argsort(x, kind="mergesort")
+    ranks = np.empty_like(order, dtype=float)
+    ranks[order] = np.arange(1, len(x) + 1, dtype=float)
+    # average over ties
+    _, inv, counts = np.unique(x, return_inverse=True, return_counts=True)
+    sums = np.zeros_like(counts, dtype=float)
+    np.add.at(sums, inv, ranks)
+    avg = sums / counts
+    return avg[inv]
+
+
+def _concordant_discordant(
+    ranks: np.ndarray, rank_index: np.ndarray, original: bool
+) -> Tuple[np.ndarray, np.ndarray]:
+    """For each covariable column, count concordant and discordant pairs.
+
+    If `original=False` (random/null): concordant means
+    sign(ranks[i]-ranks[i+1:]) == -1 (matches the R cellToGamma which assumes
+    monotonic 1..N and sign always = -1). Discordant counts where
+    `ranks[i] != ranks[k]` and sign != -1.
+
+    If `original=True`: compare against the actual rank_index sign pattern.
+    """
+    n_labels, n_cov = ranks.shape
+    nconc = np.zeros(n_cov, dtype=int)
+    ndisc = np.zeros(n_cov, dtype=int)
+    for i in range(n_labels - 1):
+        ri = ranks[i]
+        rj = ranks[i + 1 :]  # (rest, n_cov)
+        diff_r = ri[np.newaxis, :] - rj  # (rest, n_cov)
+        if original:
+            idx_diff = rank_index[i] - rank_index[i + 1 :]
+            target_sign = np.sign(idx_diff)[:, np.newaxis]  # (rest, 1)
+            nconc += np.sum(np.sign(diff_r) == target_sign, axis=0)
+            mask_neq = diff_r != 0
+            ndisc += np.sum((np.sign(diff_r) != target_sign) & mask_neq, axis=0)
+        else:
+            nconc += np.sum(np.sign(diff_r) == -1, axis=0)
+            mask_neq = diff_r != 0
+            ndisc += np.sum((np.sign(diff_r) != -1) & mask_neq, axis=0)
+    return nconc, ndisc
+
+
+def cell_to_gamma(
+    covariable: np.ndarray,
+    groups: np.ndarray,
+    label_order: Sequence[str],
+    indexes: Sequence[str],
+    cell_crowd: Dict[str, int],
+    rank_index: np.ndarray,
+    rng: np.random.Generator,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Random null distribution: mix all covariables, then subsample per-group.
+
+    Returns (n_concordant, n_discordant) per covariable column (length n_cov).
+    """
+    pieces_cov, pieces_grp = [], []
+    for label in label_order:
+        n = int(cell_crowd[label])
+        sample = rng.choice(covariable, size=n, replace=True)
+        pieces_cov.append(sample)
+        pieces_grp.append(np.repeat(label, n))
+    cov = np.concatenate(pieces_cov)
+    grp = np.concatenate(pieces_grp)
+    tab = _table(grp, cov)
+    ranks = _ranked_proportions(tab, label_order, indexes)
+    return _concordant_discordant(ranks, rank_index, original=False)
+
+
+def cell_to_gamma_original(
+    covariable: np.ndarray,
+    groups: np.ndarray,
+    label_order: Sequence[str],
+    indexes: Sequence[str],
+    cell_crowd: Dict[str, int],
+    rank_index: np.ndarray,
+    rng: np.random.Generator,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Original-data subsampling: subsample within each group preserving labels."""
+    pieces_cov, pieces_grp = [], []
+    for label in label_order:
+        n = int(cell_crowd[label])
+        pool = covariable[groups == label]
+        if len(pool) == 0:
+            continue
+        replace = n > len(pool)
+        sample = rng.choice(pool, size=n, replace=replace)
+        pieces_cov.append(sample)
+        pieces_grp.append(np.repeat(label, n))
+    cov = np.concatenate(pieces_cov)
+    grp = np.concatenate(pieces_grp)
+    tab = _table(grp, cov)
+    ranks = _ranked_proportions(tab, label_order, indexes)
+    return _concordant_discordant(ranks, rank_index, original=True)
+
+
+# --- Monte Carlo for 2-condition fold-change -----------------------------------------
+
+def _proportions_from_table(
+    tab: pd.DataFrame,
+    label_order: Sequence[str],
+    indexes: Sequence[str],
+    pseudo: bool = True,
+) -> np.ndarray:
+    """`pseudo_count(tab)` then column-wise proportions, indexed by label_order/indexes."""
+    tab = _ensure_rows(tab, label_order)
+    tab = _ensure_cols(tab, indexes)
+    vals = tab.values.astype(float)
+    if pseudo:
+        vals = pseudo_count(vals)
+    col_sums = vals.sum(axis=0) + 1.0
+    return vals / col_sums[np.newaxis, :]  # (n_labels, n_cov)
+
+
+def cell_to_montecarlo(
+    covariable: np.ndarray,
+    groups: np.ndarray,
+    label_order: Sequence[str],
+    indexes: Sequence[str],
+    cell_crowd: Union[Dict[str, int], Dict[str, List[int]]],
+    rng: np.random.Generator,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Return (mixed-pool fold change, original-resampled fold change).
+
+    Both are arrays of length len(indexes), holding
+    log2( asrt(p1) / asrt(p2) ).
+    """
+    def _build_mixed(crowd_for_label):
+        if isinstance(crowd_for_label, (list, np.ndarray)):
+            sizes = np.asarray(crowd_for_label, dtype=int)
+            return np.concatenate(
+                [rng.choice(covariable, size=int(s), replace=True) for s in sizes]
+            )
+        return rng.choice(covariable, size=int(crowd_for_label), replace=True)
+
+    def _build_orig(crowd_for_label, label):
+        pool = covariable[groups == label]
+        if len(pool) == 0:
+            return np.array([], dtype=covariable.dtype)
+        if isinstance(crowd_for_label, (list, np.ndarray)):
+            sizes = np.asarray(crowd_for_label, dtype=int)
+            return np.concatenate(
+                [rng.choice(pool, size=int(s), replace=True) for s in sizes]
+            )
+        n = int(crowd_for_label)
+        return rng.choice(pool, size=n, replace=True)
+
+    mixed_cov, mixed_grp, orig_cov, orig_grp = [], [], [], []
+    for label in label_order:
+        cm = _build_mixed(cell_crowd[label])
+        co = _build_orig(cell_crowd[label], label)
+        mixed_cov.append(cm)
+        mixed_grp.append(np.repeat(label, len(cm)))
+        orig_cov.append(co)
+        orig_grp.append(np.repeat(label, len(co)))
+
+    mixed_tab = _table(np.concatenate(mixed_grp), np.concatenate(mixed_cov))
+    orig_tab = _table(np.concatenate(orig_grp), np.concatenate(orig_cov))
+
+    p_mixed = _proportions_from_table(mixed_tab, label_order, indexes, pseudo=True)
+    p_orig = _proportions_from_table(orig_tab, label_order, indexes, pseudo=True)
+
+    fc_mixed = np.log2(asrt(p_mixed[0]) / asrt(p_mixed[1]))
+    fc_orig = np.log2(asrt(p_orig[0]) / asrt(p_orig[1]))
+    return fc_mixed, fc_orig