bootstrap2-sc 0.1.0__py3-none-any.whl

bootstrap2/__init__.py

@@ -0,0 +1,7 @@
+"""BOOTSTRAP2: hierarchical bootstrap for scRNA-seq DEA."""
+
+from .core import bootstrap2h
+
+__all__ = ["bootstrap2h", "__version__"]
+__version__ = "0.1.0"
+

bootstrap2/core.py

@@ -0,0 +1,173 @@
+"""Two-level batch--subject bootstrap, without cell-level resampling."""
+
+from __future__ import annotations
+
+import warnings
+from numbers import Integral
+
+import numpy as np
+import pandas as pd
+from joblib import Parallel, delayed, effective_n_jobs
+from scipy import sparse
+
+
+def _matrix(adata, layer):
+    if layer is not None and layer not in adata.layers:
+        raise ValueError(f"Layer {layer!r} is not present in adata.layers.")
+    counts = adata.X if layer is None else adata.layers[layer]
+    if counts is None:
+        raise ValueError("AnnData must contain a raw count matrix.")
+    matrix = sparse.csr_matrix(counts, copy=True)
+    if not np.isfinite(matrix.data).all() or (matrix.data < 0).any():
+        raise ValueError("Expression must contain finite, nonnegative values.")
+    if matrix.dtype.kind != "f":
+        matrix = matrix.astype(np.float32)
+    totals = np.asarray(matrix.sum(axis=1)).ravel()
+    if not np.isfinite(totals).all():
+        raise ValueError("Nonfinite cell library sizes; check expression values.")
+    zero = totals == 0
+    if zero.any():
+        warnings.warn(
+            f"{zero.sum()} cells have zero total counts and remain zero after CPM normalization.",
+            UserWarning, stacklevel=3,
+        )
+    scale = totals / 1e6
+    scale[zero] = 1
+    matrix.data /= np.repeat(scale, np.diff(matrix.indptr))
+    return matrix
+
+
+def _prepare(adata, matrix, condition_col, sample_col, batch_col, condition):
+    for column in [condition_col, sample_col]:
+        if column not in adata.obs:
+            raise ValueError(f"Required metadata column {column!r} is missing.")
+    columns = [condition_col, sample_col]
+    if batch_col is not None and batch_col in adata.obs:
+        columns.append(batch_col)
+    if len(set(columns)) != len(columns):
+        raise ValueError("Condition, sample and batch columns must be different.")
+    obs = adata.obs[columns].copy()
+    if obs.isna().any().any():
+        raise ValueError("Condition, sample and batch labels must not be missing.")
+    # Reject labels whose string conversion would merge different identifiers.
+    for column in columns:
+        if obs[column].nunique() != obs[column].astype(str).nunique():
+            raise ValueError(f"Labels in {column!r} collide after conversion to strings.")
+        obs[column] = obs[column].astype(str)
+    batches = obs[batch_col] if batch_col in obs else pd.Series("single_batch", index=obs.index)
+    labels = obs[condition_col].unique().tolist()
+    if len(labels) != 2:
+        raise ValueError("Exactly two conditions are required; subset the AnnData first.")
+    if condition is None:
+        condition = tuple(labels)
+    else:
+        if isinstance(condition, (str, bytes)):
+            raise ValueError("condition must be a pair of condition labels, not a string.")
+        condition = tuple(str(value) for value in condition)
+    if len(condition) != 2 or condition[0] == condition[1] or set(condition) != set(labels):
+        raise ValueError("condition must contain the two observed conditions, numerator first.")
+    layout = pd.DataFrame({"sample": obs[sample_col], "condition": obs[condition_col], "batch": batches})
+    for column in ["condition", "batch"]:
+        if (layout.groupby("sample", sort=False)[column].nunique() > 1).any():
+            raise ValueError(
+                "Each Sample must belong to one condition and one batch. "
+                "Repeated/paired subjects or subjects spanning batches require a different design."
+            )
+    valid, dropped, group_a, group_b = [], [], {}, {}
+    for batch in layout["batch"].unique():
+        in_batch = layout["batch"] == batch
+        a = layout.loc[in_batch & (layout["condition"] == condition[0]), "sample"].unique()
+        b = layout.loc[in_batch & (layout["condition"] == condition[1]), "sample"].unique()
+        if len(a) and len(b):
+            valid.append(batch)
+            group_a[batch], group_b[batch] = a, b
+        else:
+            dropped.append(batch)
+    if dropped:
+        raise ValueError("Each batch must contain both conditions. Batches lacking one condition: " + ", ".join(dropped))
+    if not valid:
+        raise ValueError("No batch contains both conditions; condition and batch may be confounded.")
+    all_samples = [sample for batch in valid for group in (group_a, group_b) for sample in group[batch]]
+    counts = [sum(len(group[batch]) for batch in valid) for group in (group_a, group_b)]
+    if min(counts) < 2:
+        raise ValueError("At least two independent subjects per condition must remain.")
+    positions = {sample: i for i, sample in enumerate(all_samples)}
+    transposed = matrix.T.tocsc()
+    profiles = np.array([
+        np.asarray(transposed[:, np.flatnonzero(layout["sample"].to_numpy() == sample)].mean(axis=1)).ravel()
+        for sample in all_samples
+    ])
+    indices_a = {batch: np.array([positions[s] for s in group_a[batch]]) for batch in valid}
+    indices_b = {batch: np.array([positions[s] for s in group_b[batch]]) for batch in valid}
+    return profiles, indices_a, indices_b
+
+
+def _worker(profiles, indices_a, indices_b, fold_threshold, n_iters, seed):
+    rng = np.random.RandomState(seed)
+    up = np.zeros(profiles.shape[1], dtype=np.int64)
+    down = np.zeros(profiles.shape[1], dtype=np.int64)
+    batches_a, batches_b = np.array(list(indices_a)), np.array(list(indices_b))
+    for _ in range(n_iters):
+        sampled_a = rng.choice(batches_a, size=len(batches_a), replace=True)
+        sampled_b = rng.choice(batches_b, size=len(batches_b), replace=True)
+        a = np.concatenate([rng.choice(indices_a[b], size=len(indices_a[b]), replace=True) for b in sampled_a])
+        b = np.concatenate([rng.choice(indices_b[b], size=len(indices_b[b]), replace=True) for b in sampled_b])
+        mean_a, mean_b = profiles[a].mean(axis=0), profiles[b].mean(axis=0)
+        up += mean_a <= mean_b * fold_threshold
+        down += mean_b <= mean_a * fold_threshold
+    return up, down
+
+
+def _adjust_pvalues(up, down, n_iters):
+    return (2.0 * np.minimum(up, down) + 1.0) / (n_iters + 1.0)
+
+
+def bootstrap2h(
+    adata, *, condition=None, n_bootstraps=10_000, n_jobs=4, seed=0, lfc=0.0,
+    condition_col="Condition", sample_col="Sample", batch_col="Batch", layer=None,
+):
+    """Run two-level bootstrap on raw counts without modifying the input.
+
+    ``condition`` is the numerator/denominator pair; if omitted, use label order
+    in ``adata.obs``. ``lfc`` is a nonnegative log2 threshold (0 for point null).
+    Metadata defaults to Condition, Sample and Batch; a missing Batch column
+    means one batch. ``layer`` optionally selects a raw-count layer instead of X.
+    ``n_jobs`` is the worker count; -1 uses available CPUs.
+    Return a gene-indexed DataFrame with unadjusted ``p_val`` and ``lfc``.
+    """
+    if adata.n_obs == 0 or adata.n_vars == 0:
+        raise ValueError("AnnData must contain cells and genes.")
+    if not adata.var_names.is_unique:
+        raise ValueError("Gene names must be unique.")
+    if isinstance(n_bootstraps, bool) or not isinstance(n_bootstraps, Integral) or n_bootstraps < 1:
+        raise ValueError("n_bootstraps must be a positive integer.")
+    if isinstance(n_jobs, bool) or not isinstance(n_jobs, Integral) or (n_jobs < 1 and n_jobs != -1):
+        raise ValueError("n_jobs must be a positive integer or -1.")
+    if isinstance(seed, bool) or not isinstance(seed, Integral) or not 0 <= seed < 2**32:
+        raise ValueError("seed must be an integer in [0, 2**32).")
+    if not np.isfinite(lfc) or lfc < 0:
+        raise ValueError("lfc must be finite and nonnegative.")
+    with np.errstate(over="ignore"):
+        fold_threshold = float(np.exp2(lfc))
+    if not np.isfinite(fold_threshold):
+        raise ValueError("lfc is too large.")
+    matrix = _matrix(adata, layer)
+    profiles, a, b = _prepare(
+        adata, matrix, condition_col, sample_col, batch_col, condition,
+    )
+    workers = min(effective_n_jobs(n_jobs), n_bootstraps)
+    iterations = [n_bootstraps // workers + (i < n_bootstraps % workers) for i in range(workers)]
+    seeds = np.random.RandomState(seed).randint(0, 1_000_000, size=workers)
+    results = Parallel(n_jobs=workers)(
+        delayed(_worker)(profiles, a, b, fold_threshold, count, int(worker_seed))
+        for count, worker_seed in zip(iterations, seeds)
+    )
+    up, down = np.sum([r[0] for r in results], axis=0), np.sum([r[1] for r in results], axis=0)
+    mean_a = profiles[np.concatenate(list(a.values()))].mean(axis=0)
+    mean_b = profiles[np.concatenate(list(b.values()))].mean(axis=0)
+    result = pd.DataFrame({
+        "p_val": _adjust_pvalues(up, down, n_bootstraps),
+        "lfc": np.log2((mean_a + 1e-9) / (mean_b + 1e-9)),
+    }, index=pd.Index(adata.var_names, name="gene"))
+    return result
+

bootstrap2_sc-0.1.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: bootstrap2-sc
+Version: 0.1.0
+Summary: Subject-aware two-level hierarchical bootstrap for single-cell differential expression
+Author: ZW.G
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anndata<1,>=0.10
+Requires-Dist: joblib<2,>=1.3
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: pandas<4,>=2
+Requires-Dist: scipy<2,>=1.10
+
+# BOOTSTRAP2
+
+Two-level hierarchical bootstrap for single-cell differential expression.
+
+## Installation
+
+Python 3.10 or newer is required. Install with:
+
+```sh
+python -m pip install bootstrap2-sc
+```
+
+For installation from a local source checkout:
+
+```sh
+python -m pip install .
+```
+
+## Input
+
+Provide an AnnData object containing raw counts in `adata.X`.
+
+| `adata.obs` field | Description |
+| --- | --- |
+| `Sample` | Globally unique biological subject identifier |
+| `Condition` | Exactly two comparison groups |
+| `Batch` | Batch identifier; optional for a single-batch design |
+
+Each subject must belong to one condition and one batch. The method supports
+the nested batch--subject design, not general covariate adjustment,
+paired/repeated subjects or condition-batch confounding.
+
+## Python API
+
+```python
+import anndata as ad
+from bootstrap2 import bootstrap2h
+
+adata = ad.read_h5ad("counts.h5ad")
+result = bootstrap2h(
+    adata,
+    condition=("SLE", "Control"),
+    n_bootstraps=10000,
+    n_jobs=4,
+    seed=0,
+    lfc=0.0,
+)
+result.to_csv("results.tsv", sep="\t")
+```
+
+The input AnnData is not modified. Use `layer="counts"` to select a raw-count
+layer in the API.
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `n_bootstraps` | 10000 | Number of bootstrap iterations |
+| `n_jobs` | 4 | Worker processes; -1 uses available CPUs |
+| `seed` | 0 | Random seed |
+| `lfc` | 0 | Nonnegative log2 threshold; 0 gives the point null |
+| `condition` | First-appearance order | Numerator then denominator condition |
+
+With `condition=("SLE", "Control")`, a positive LFC indicates higher expression
+in SLE. Use `condition_col`, `sample_col` and `batch_col` for alternative
+metadata field names.
+
+## Output
+
+Returns a DataFrame indexed by gene, with `p_val` and `lfc` columns.
+

bootstrap2_sc-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+bootstrap2/__init__.py,sha256=mwNvjlA8T-s2XvDAdW2bXv1uFlOnaJHNAXtVisGdJ3Q,156
+bootstrap2/core.py,sha256=T4nqg5SczdrttqZSwZCSA_-aCY9Buwk27WBNdHthA60,8792
+bootstrap2_sc-0.1.0.dist-info/METADATA,sha256=j8_QzQcAHh-DJd6WBv875uucOV_KwB91PWk5-cC4Sk0,2255
+bootstrap2_sc-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+bootstrap2_sc-0.1.0.dist-info/top_level.txt,sha256=z_wmfp_2Spmi3r1eJbQQy3GBSSYrYEdSyuL-SQ6TRQ0,11
+bootstrap2_sc-0.1.0.dist-info/RECORD,,

bootstrap2_sc-0.1.0.dist-info/WHEEL

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

bootstrap2_sc-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bootstrap2