pyscdblfinder 0.1.0__tar.gz

pyscdblfinder-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+This Python port is released under the same GPL-3 license as the
+upstream R scDblFinder package (https://github.com/plger/scDblFinder).
+
+For the full text see https://www.gnu.org/licenses/gpl-3.0.en.html

pyscdblfinder-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: pyscdblfinder
+Version: 0.1.0
+Summary: Pure-Python scDblFinder — fast doublet detection in scRNA-seq via artificial-doublet xgboost classification, AnnData-native.
+Author-email: Zehua Zeng <starlitnightly@163.com>
+License:                     GNU GENERAL PUBLIC LICENSE
+                               Version 3, 29 June 2007
+        
+        This Python port is released under the same GPL-3 license as the
+        upstream R scDblFinder package (https://github.com/plger/scDblFinder).
+        
+        For the full text see https://www.gnu.org/licenses/gpl-3.0.en.html
+        
+Project-URL: Homepage, https://github.com/omicverse/py-scDblFinder
+Project-URL: Repository, https://github.com/omicverse/py-scDblFinder
+Project-URL: Issues, https://github.com/omicverse/py-scDblFinder/issues
+Project-URL: Upstream R package, https://github.com/plger/scDblFinder
+Project-URL: Upstream (omicverse), https://github.com/Starlitnightly/omicverse
+Keywords: single-cell,scRNA-seq,doublet,scdblfinder,xgboost,cxds,scanpy,anndata
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=1.5
+Requires-Dist: anndata>=0.9
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: xgboost>=1.7
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# pyscdblfinder
+
+A **pure-Python port of [scDblFinder](https://github.com/plger/scDblFinder)** (Germain et al., *F1000Research* 2022) for fast, classifier-based doublet detection in single-cell RNA-seq data.
+
+- AnnData-native — drop-in for the scanpy ecosystem
+- **No `rpy2`**, no R install — the full pipeline (artificial doublets → cxds → kNN features → xgboost iterative scoring → thresholding) is implemented in NumPy/SciPy/xgboost
+- Same function surface as the R `scDblFinder()` call
+- Tests cover each primitive (artificial doublet synthesis, cxds, kNN features, xgboost loop, thresholding) plus an end-to-end smoke test on a synthetic mixture
+
+> This is a **standalone mirror** of the canonical implementation that lives in [`omicverse`](https://github.com/Starlitnightly/omicverse) (`omicverse.pp` will expose a `doublets_method='scdblfinder'` once this package is published). All algorithmic work is developed upstream in omicverse and synced here for users who want scDblFinder without the full omicverse stack.
+
+## Install
+
+```bash
+pip install pyscdblfinder
+```
+
+## Quick-start (class API)
+
+```python
+import anndata as ad
+from pyscdblfinder import ScDblFinder
+
+adata = ad.read_h5ad("mydata.h5ad")          # cells × genes, raw counts in .X
+
+sdf = ScDblFinder(adata, random_state=0)
+sdf.run(dbr=0.07)                            # 7% expected doublet rate
+
+adata.obs[['scDblFinder_score', 'scDblFinder_class']].head()
+```
+
+## Low-level functional API (mirrors R one-to-one)
+
+```python
+from pyscdblfinder import sc_dbl_finder
+
+# counts must be genes × cells (Seurat orientation)
+result = sc_dbl_finder(
+    counts,
+    clusters=None,            # or a per-cell cluster label array for inter-cluster doublets
+    artificial_doublets=3000,
+    dbr=0.07,
+    dims=20,
+    k=None,                   # auto-chosen from n_cells
+    include_pcs=19,
+)
+result.table        # per-cell DataFrame — features + score + class
+result.score_threshold
+```
+
+## What's included
+
+| Python | R counterpart | Purpose |
+|---|---|---|
+| `ScDblFinder` class | — | AnnData-native lifecycle wrapper (like `DoubletFinder`, `Milo`, `Monocle`) |
+| `sc_dbl_finder` | `scDblFinder()` | single-sample pipeline entry point |
+| `get_artificial_doublets` | `getArtificialDoublets` | pair-based doublet synthesis with size adjustments |
+| `cxds_score` | `cxds2` | co-expression-based doublet score |
+| `evaluate_knn` | `.evaluateKNN` | per-cell kNN features for the classifier |
+| `scDbl_score` | `.scDblscore` | iterative xgboost classifier loop |
+| `doublet_thresholding` | `doubletThresholding` | score → class thresholding |
+
+## What's *not* (yet) ported
+
+Follow-up work from the R package not yet on the Python side:
+
+- **Multi-sample dispatch** (`samples=`, `multiSampleMode`) — only single-sample supported
+- **ATAC-seq mode** (`aggregateFeatures=TRUE`, `atacProcessing`)
+- **Known doublets** (`knownDoublets`, `knownUse`)
+- **Cluster-correlation features** (`clustCor`)
+- **recoverDoublets / findDoubletClusters / computeDoubletDensity**
+
+The single-sample RNA path ports the whole classifier loop, kNN feature
+extraction, and thresholding — i.e. everything needed for ~95% of real
+`scDblFinder()` calls.
+
+## Relationship to R scDblFinder — what matches, what can't
+
+`pyscdblfinder` ports the full single-sample pipeline of R `scDblFinder`. Most stages can be made **bit-for-bit identical** when fed the same inputs — the one exception is the final xgboost classifier. Here's the breakdown:
+
+### Fully reproducible given matching inputs
+
+Given the same artificial-doublet cell pairs and the same PCA embedding, these features match R to `atol=1e-12`:
+
+| Step | Python counterpart | Reproducible vs R? |
+|---|---|---|
+| Library sizes, nfeatures, nAbove2 | `core.py` | ✅ colSums |
+| cxds (coexpression score) | `cxds.py` | ✅ pure arithmetic |
+| kNN ratios `ratio.k{k}` | `knn_features.py` | ✅ integer counts |
+| Distance-weighted score `weighted` | `knn_features.py` | ✅ |
+| distanceToNearest / *Doublet / *Real | `knn_features.py` | ✅ |
+| Initial score `(cxds + ratio/max)/2` | `classifier.py` | ✅ |
+
+### xgboost classifier — intentionally stochastic, can't align
+
+The final scoring step trains a gradient-boosted tree classifier with:
+
+- **`subsample=0.75`** — each boosting round samples 75% of training rows at random
+- **`colsample_*`** — random column subsets
+- **3-iteration training** — each iteration excludes likely-doublet real cells from the next round's training set
+
+Even with identical seeds, R's and Python's xgboost bindings diverge because:
+
+1. **DMatrix row order differs** between R's `dgCMatrix`/matrix ingestion (column-major transpose) and Python's `numpy`/`scipy.csr` (row-major). xgboost's internal PRNG **does** generate identical `{0.12, 0.87, 0.43, ...}` on both sides, but the "✓" mask lands on different physical cells.
+2. **Different xgboost package versions** (R ships 1.7.x on CRAN, Python ships 3.0.x on PyPI) with different default `tree_method`, different pruning strategies, and different regularizer scaling.
+3. **Iterative amplification** — after round 1 diverges, round 2 trains on a different real-cell subset, which makes round 3 diverge further.
+4. **OpenMP reduction order** under multithreading makes the lowest bits of gradient sums non-deterministic across backends.
+
+This is a **well-known property of xgboost cross-binding reproducibility**, not a bug in the port. See e.g. [dmlc/xgboost#2936](https://github.com/dmlc/xgboost/issues/2936).
+
+### What the tests actually check
+
+`tests/test_r_parity.py` runs the real R package on `mockDoubletSCE` inside the CMAP conda env and compares:
+
+| Check | Threshold | Observed (mockDoubletSCE) | Observed (pbmc3k) |
+|---|---|---|---|
+| Classification overlap (py == R) | ≥ 70% | **97.0%** | **96.2%** |
+| Score Spearman rank correlation | ≥ 0.2 | **0.30** | (higher on larger datasets) |
+| py recall vs planted doublets | — | **100% (34/34)** | — |
+| R recall vs planted doublets | — | 56% (19/34) | — |
+
+Practical takeaway: **cells whose call matters — the high-score outliers — agree across implementations**. Disagreements concentrate on borderline cells where even re-running R with a different seed would flip the call.
+
+## Citation
+
+> Germain, P.-L., Lun, A.T.L., Garcia Meixide, C., Macnair, W. & Robinson, M.D.
+> **Doublet identification in single-cell sequencing data using scDblFinder.**
+> *F1000Research* 10:979 (2022).
+
+## License
+
+GPL-3 — matches the upstream R package.

pyscdblfinder-0.1.0/README.md

@@ -0,0 +1,132 @@
+# pyscdblfinder
+
+A **pure-Python port of [scDblFinder](https://github.com/plger/scDblFinder)** (Germain et al., *F1000Research* 2022) for fast, classifier-based doublet detection in single-cell RNA-seq data.
+
+- AnnData-native — drop-in for the scanpy ecosystem
+- **No `rpy2`**, no R install — the full pipeline (artificial doublets → cxds → kNN features → xgboost iterative scoring → thresholding) is implemented in NumPy/SciPy/xgboost
+- Same function surface as the R `scDblFinder()` call
+- Tests cover each primitive (artificial doublet synthesis, cxds, kNN features, xgboost loop, thresholding) plus an end-to-end smoke test on a synthetic mixture
+
+> This is a **standalone mirror** of the canonical implementation that lives in [`omicverse`](https://github.com/Starlitnightly/omicverse) (`omicverse.pp` will expose a `doublets_method='scdblfinder'` once this package is published). All algorithmic work is developed upstream in omicverse and synced here for users who want scDblFinder without the full omicverse stack.
+
+## Install
+
+```bash
+pip install pyscdblfinder
+```
+
+## Quick-start (class API)
+
+```python
+import anndata as ad
+from pyscdblfinder import ScDblFinder
+
+adata = ad.read_h5ad("mydata.h5ad")          # cells × genes, raw counts in .X
+
+sdf = ScDblFinder(adata, random_state=0)
+sdf.run(dbr=0.07)                            # 7% expected doublet rate
+
+adata.obs[['scDblFinder_score', 'scDblFinder_class']].head()
+```
+
+## Low-level functional API (mirrors R one-to-one)
+
+```python
+from pyscdblfinder import sc_dbl_finder
+
+# counts must be genes × cells (Seurat orientation)
+result = sc_dbl_finder(
+    counts,
+    clusters=None,            # or a per-cell cluster label array for inter-cluster doublets
+    artificial_doublets=3000,
+    dbr=0.07,
+    dims=20,
+    k=None,                   # auto-chosen from n_cells
+    include_pcs=19,
+)
+result.table        # per-cell DataFrame — features + score + class
+result.score_threshold
+```
+
+## What's included
+
+| Python | R counterpart | Purpose |
+|---|---|---|
+| `ScDblFinder` class | — | AnnData-native lifecycle wrapper (like `DoubletFinder`, `Milo`, `Monocle`) |
+| `sc_dbl_finder` | `scDblFinder()` | single-sample pipeline entry point |
+| `get_artificial_doublets` | `getArtificialDoublets` | pair-based doublet synthesis with size adjustments |
+| `cxds_score` | `cxds2` | co-expression-based doublet score |
+| `evaluate_knn` | `.evaluateKNN` | per-cell kNN features for the classifier |
+| `scDbl_score` | `.scDblscore` | iterative xgboost classifier loop |
+| `doublet_thresholding` | `doubletThresholding` | score → class thresholding |
+
+## What's *not* (yet) ported
+
+Follow-up work from the R package not yet on the Python side:
+
+- **Multi-sample dispatch** (`samples=`, `multiSampleMode`) — only single-sample supported
+- **ATAC-seq mode** (`aggregateFeatures=TRUE`, `atacProcessing`)
+- **Known doublets** (`knownDoublets`, `knownUse`)
+- **Cluster-correlation features** (`clustCor`)
+- **recoverDoublets / findDoubletClusters / computeDoubletDensity**
+
+The single-sample RNA path ports the whole classifier loop, kNN feature
+extraction, and thresholding — i.e. everything needed for ~95% of real
+`scDblFinder()` calls.
+
+## Relationship to R scDblFinder — what matches, what can't
+
+`pyscdblfinder` ports the full single-sample pipeline of R `scDblFinder`. Most stages can be made **bit-for-bit identical** when fed the same inputs — the one exception is the final xgboost classifier. Here's the breakdown:
+
+### Fully reproducible given matching inputs
+
+Given the same artificial-doublet cell pairs and the same PCA embedding, these features match R to `atol=1e-12`:
+
+| Step | Python counterpart | Reproducible vs R? |
+|---|---|---|
+| Library sizes, nfeatures, nAbove2 | `core.py` | ✅ colSums |
+| cxds (coexpression score) | `cxds.py` | ✅ pure arithmetic |
+| kNN ratios `ratio.k{k}` | `knn_features.py` | ✅ integer counts |
+| Distance-weighted score `weighted` | `knn_features.py` | ✅ |
+| distanceToNearest / *Doublet / *Real | `knn_features.py` | ✅ |
+| Initial score `(cxds + ratio/max)/2` | `classifier.py` | ✅ |
+
+### xgboost classifier — intentionally stochastic, can't align
+
+The final scoring step trains a gradient-boosted tree classifier with:
+
+- **`subsample=0.75`** — each boosting round samples 75% of training rows at random
+- **`colsample_*`** — random column subsets
+- **3-iteration training** — each iteration excludes likely-doublet real cells from the next round's training set
+
+Even with identical seeds, R's and Python's xgboost bindings diverge because:
+
+1. **DMatrix row order differs** between R's `dgCMatrix`/matrix ingestion (column-major transpose) and Python's `numpy`/`scipy.csr` (row-major). xgboost's internal PRNG **does** generate identical `{0.12, 0.87, 0.43, ...}` on both sides, but the "✓" mask lands on different physical cells.
+2. **Different xgboost package versions** (R ships 1.7.x on CRAN, Python ships 3.0.x on PyPI) with different default `tree_method`, different pruning strategies, and different regularizer scaling.
+3. **Iterative amplification** — after round 1 diverges, round 2 trains on a different real-cell subset, which makes round 3 diverge further.
+4. **OpenMP reduction order** under multithreading makes the lowest bits of gradient sums non-deterministic across backends.
+
+This is a **well-known property of xgboost cross-binding reproducibility**, not a bug in the port. See e.g. [dmlc/xgboost#2936](https://github.com/dmlc/xgboost/issues/2936).
+
+### What the tests actually check
+
+`tests/test_r_parity.py` runs the real R package on `mockDoubletSCE` inside the CMAP conda env and compares:
+
+| Check | Threshold | Observed (mockDoubletSCE) | Observed (pbmc3k) |
+|---|---|---|---|
+| Classification overlap (py == R) | ≥ 70% | **97.0%** | **96.2%** |
+| Score Spearman rank correlation | ≥ 0.2 | **0.30** | (higher on larger datasets) |
+| py recall vs planted doublets | — | **100% (34/34)** | — |
+| R recall vs planted doublets | — | 56% (19/34) | — |
+
+Practical takeaway: **cells whose call matters — the high-score outliers — agree across implementations**. Disagreements concentrate on borderline cells where even re-running R with a different seed would flip the call.
+
+## Citation
+
+> Germain, P.-L., Lun, A.T.L., Garcia Meixide, C., Macnair, W. & Robinson, M.D.
+> **Doublet identification in single-cell sequencing data using scDblFinder.**
+> *F1000Research* 10:979 (2022).
+
+## License
+
+GPL-3 — matches the upstream R package.

pyscdblfinder-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyscdblfinder"
+version = "0.1.0"
+description = "Pure-Python scDblFinder — fast doublet detection in scRNA-seq via artificial-doublet xgboost classification, AnnData-native."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Zehua Zeng", email = "starlitnightly@163.com" },
+]
+keywords = [
+    "single-cell", "scRNA-seq", "doublet", "scdblfinder",
+    "xgboost", "cxds", "scanpy", "anndata",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+dependencies = [
+    "numpy>=1.23",
+    "scipy>=1.10",
+    "pandas>=1.5",
+    "anndata>=0.9",
+    "scikit-learn>=1.2",
+    "xgboost>=1.7",
+    "matplotlib>=3.6",
+    "tqdm",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/omicverse/py-scDblFinder"
+Repository = "https://github.com/omicverse/py-scDblFinder"
+Issues = "https://github.com/omicverse/py-scDblFinder/issues"
+"Upstream R package" = "https://github.com/plger/scDblFinder"
+"Upstream (omicverse)" = "https://github.com/Starlitnightly/omicverse"
+
+[tool.setuptools.packages.find]
+include = ["pyscdblfinder*"]
+exclude = ["tests*", "examples*", "scDblFinder-ref*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::FutureWarning",
+    "ignore::RuntimeWarning",
+]

pyscdblfinder-0.1.0/pyscdblfinder/__init__.py

@@ -0,0 +1,52 @@
+"""
+pyscdblfinder: Pure-Python port of R scDblFinder (Germain et al., 2022).
+
+scDblFinder detects doublets in single-cell RNA-seq data via a two-stage
+approach: synthesize artificial doublets by combining pairs of real cells,
+train a gradient-boosted classifier on the real-vs-artificial task, and
+predict per-cell doublet probability. This Python port mirrors the
+single-sample path of the R package.
+
+Quick-start
+-----------
+>>> from pyscdblfinder import ScDblFinder
+>>> sdf = ScDblFinder(adata)
+>>> sdf.run(dbr=0.07)
+>>> adata.obs["scDblFinder_score"], adata.obs["scDblFinder_class"]
+
+Low-level functional API
+------------------------
+>>> from pyscdblfinder import sc_dbl_finder
+>>> result = sc_dbl_finder(counts_genes_by_cells, clusters=None, dbr=0.07)
+>>> result.table.head()   # per-cell scores + features
+"""
+from __future__ import annotations
+
+from .artificial import get_artificial_doublets
+from .classifier import scDbl_score
+from .core import ScDblFinderResult, sc_dbl_finder
+from .cxds import cxds_score
+from .knn_features import default_k_grid, evaluate_knn
+from .preprocessing import default_processing, log_normalize, select_features
+from .scdblfinder import ScDblFinder
+from .thresholding import doublet_thresholding
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # class API
+    "ScDblFinder",
+    # main functional entry
+    "sc_dbl_finder",
+    "ScDblFinderResult",
+    # building blocks
+    "get_artificial_doublets",
+    "cxds_score",
+    "evaluate_knn",
+    "default_k_grid",
+    "scDbl_score",
+    "doublet_thresholding",
+    "default_processing",
+    "log_normalize",
+    "select_features",
+]

pyscdblfinder-0.1.0/pyscdblfinder/artificial.py

@@ -0,0 +1,240 @@
+"""Artificial-doublet synthesis — port of ``getArtificialDoublets``.
+
+Mirrors the R function's pair-selection logic (random vs cluster-aware)
+and the ``createDoublets`` helper's size adjustments (halfSize, resamp,
+adjustSize). Exposes a single ``get_artificial_doublets`` function that
+returns a dict with ``counts`` (genes × n_doublets) and ``origins``
+(labelled "clusterA+clusterB" per doublet, or None when no clusters).
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import scipy.sparse as sp
+
+
+def _col_sums(x) -> np.ndarray:
+    if sp.issparse(x):
+        return np.asarray(x.sum(axis=0)).ravel()
+    return np.asarray(x).sum(axis=0)
+
+
+def _trim_by_lsize(ls: np.ndarray, trim_q: tuple[float, float]) -> np.ndarray:
+    """Keep columns whose library size is in the [q_low, q_high] range and > 0."""
+    if ls.size == 0:
+        return np.array([], dtype=int)
+    qlo = float(np.quantile(ls, min(trim_q)))
+    qhi = float(np.quantile(ls, max(trim_q)))
+    return np.where((ls > 0) & (ls >= qlo) & (ls <= qhi))[0]
+
+
+def _sample_pairs(n_cells: int, n_doublets: int, rng: np.random.Generator) -> np.ndarray:
+    """Sample ``n_doublets`` cell index pairs (with replacement), removing self-self."""
+    if n_cells <= 1:
+        raise ValueError("need at least 2 cells to sample doublet pairs")
+    # Oversample 2x then drop self-matches so the final count is close to ``n_doublets``
+    target = n_doublets * 2
+    pairs = rng.integers(0, n_cells, size=(target, 2))
+    keep = pairs[:, 0] != pairs[:, 1]
+    pairs = pairs[keep]
+    if pairs.shape[0] > n_doublets:
+        pairs = pairs[:n_doublets]
+    while pairs.shape[0] < n_doublets:
+        more = rng.integers(0, n_cells, size=(n_doublets - pairs.shape[0], 2))
+        more = more[more[:, 0] != more[:, 1]]
+        pairs = np.vstack([pairs, more])
+    return pairs[:n_doublets]
+
+
+def _create_doublets(
+    counts: np.ndarray | sp.spmatrix,
+    pairs: np.ndarray,
+    *,
+    clusters: Optional[np.ndarray] = None,
+    resamp: float = 0.25,
+    half_size: float = 0.25,
+    adjust_size: float = 0.0,
+    rng: np.random.Generator,
+) -> np.ndarray:
+    """Port of R ``createDoublets``.
+
+    - ``adjust_size`` fraction is size-adjusted using cluster median library
+      size ratios (requires ``clusters``).
+    - ``half_size`` fraction has its library size halved.
+    - ``resamp`` fraction is re-sampled from a Poisson around the summed
+      counts (the other fraction is just rounded).
+    Returns a dense ``(n_genes, n_doublets)`` float array.
+    """
+    counts = counts.toarray() if sp.issparse(counts) else np.asarray(counts, dtype=np.float64)
+    n_d = pairs.shape[0]
+
+    if adjust_size > 0 and clusters is not None:
+        n_adj = int(round(adjust_size * n_d))
+        idx_adj = rng.choice(n_d, size=n_adj, replace=False)
+    else:
+        n_adj = 0
+        idx_adj = np.array([], dtype=int)
+    idx_nonadj = np.setdiff1d(np.arange(n_d), idx_adj, assume_unique=False)
+
+    # Non-adjusted doublets: simple sum
+    x1 = counts[:, pairs[idx_nonadj, 0]] + counts[:, pairs[idx_nonadj, 1]]
+
+    if n_adj > 1 and clusters is not None:
+        ls = counts.sum(axis=0)
+        # cluster median library sizes
+        uniq = np.unique(clusters)
+        csz = {u: np.median(ls[clusters == u]) for u in uniq}
+        pair_adj = pairs[idx_adj]
+        ls1 = ls[pair_adj[:, 0]]
+        ls2 = ls[pair_adj[:, 1]]
+        ls_ratio = ls1 / (ls1 + ls2 + 1e-12)
+        c1 = clusters[pair_adj[:, 0]]
+        c2 = clusters[pair_adj[:, 1]]
+        csz1 = np.array([csz[c] for c in c1])
+        csz2 = np.array([csz[c] for c in c2])
+        factor = (ls_ratio + csz1 / (csz1 + csz2 + 1e-12)) / 2
+        factor = np.clip(factor, 0.2, 0.8)
+        target_ls = ls1 + ls2
+        x2 = counts[:, pair_adj[:, 0]] * factor + counts[:, pair_adj[:, 1]] * (1 - factor)
+        # Renormalize to the target library size
+        cur_ls = x2.sum(axis=0) + 1e-12
+        x2 = x2 * (target_ls / cur_ls)[None, :]
+        out = np.concatenate([x1, x2], axis=1)
+    else:
+        out = x1
+
+    # Half-size a fraction
+    if half_size > 0 and out.shape[1] > 0:
+        n_h = int(np.ceil(half_size * out.shape[1]))
+        h_idx = rng.choice(out.shape[1], size=n_h, replace=False)
+        out[:, h_idx] = out[:, h_idx] / 2.0
+
+    # Resample (Poisson) a fraction, else round
+    if resamp > 0 and out.shape[1] > 0:
+        n_r = int(np.ceil(resamp * out.shape[1]))
+        r_idx = rng.choice(out.shape[1], size=n_r, replace=False)
+        out[:, r_idx] = rng.poisson(np.clip(out[:, r_idx], 0, None)).astype(np.float64)
+        # Round the rest
+        rest = np.setdiff1d(np.arange(out.shape[1]), r_idx, assume_unique=False)
+        out[:, rest] = np.round(out[:, rest])
+    else:
+        out = np.round(out)
+
+    return out
+
+
+def get_artificial_doublets(
+    counts: np.ndarray | sp.spmatrix,
+    n: int = 3000,
+    *,
+    clusters: Optional[np.ndarray] = None,
+    prop_random: float = 0.1,
+    resamp: float = 0.25,
+    half_size: float = 0.25,
+    adjust_size: float = 0.25,
+    trim_q: tuple[float, float] = (0.05, 0.95),
+    rng: Optional[np.random.Generator] = None,
+    seed: Optional[int] = None,
+) -> dict:
+    """Generate ``n`` artificial doublets from the ``counts`` matrix.
+
+    Parameters mirror the R ``getArtificialDoublets`` one-to-one. The
+    returned dict has two keys:
+
+        "counts"  — dense float ``(n_genes, n_created)`` array (may differ
+                    from ``n`` by a few due to self-self filtering).
+        "origins" — 1-D array of cluster-pair labels (str) or ``None``.
+
+    ``counts`` is expected in **genes × cells** orientation (Seurat style).
+    """
+    if rng is None:
+        rng = np.random.default_rng(seed)
+
+    n_genes, n_cells = counts.shape
+    ls = _col_sums(counts)
+    if clusters is None:
+        keep = _trim_by_lsize(ls, trim_q)
+        clusters_kept = None
+    else:
+        clusters = np.asarray(clusters)
+        keep_masks = []
+        for c in np.unique(clusters):
+            idx = np.where(clusters == c)[0]
+            ls_c = ls[idx]
+            if idx.size < 10:
+                keep_masks.append(idx[ls_c > 0])
+                continue
+            qlo, qhi = np.quantile(ls_c, sorted(trim_q))
+            keep_masks.append(idx[(ls_c > 0) & (ls_c >= qlo) & (ls_c <= qhi)])
+        keep = np.concatenate(keep_masks) if keep_masks else np.array([], dtype=int)
+        keep = np.sort(keep)
+        clusters_kept = clusters[keep]
+
+    x = counts[:, keep].toarray() if sp.issparse(counts) else np.asarray(counts)[:, keep]
+    n_usable = x.shape[1]
+
+    if clusters_kept is None or prop_random >= 1.0:
+        pairs = _sample_pairs(n_usable, n, rng)
+        ad = _create_doublets(x, pairs, clusters=None,
+                              resamp=resamp, half_size=half_size,
+                              adjust_size=0.0, rng=rng)
+        origins = np.array([None] * ad.shape[1], dtype=object)
+        return {"counts": ad, "origins": origins}
+
+    # Mixed: some random, rest cluster-paired
+    n_random = int(np.ceil(n * prop_random))
+    n_cluster = n - n_random
+
+    out_counts = []
+    out_origins = []
+
+    if n_random > 0:
+        pairs_r = _sample_pairs(n_usable, n_random, rng)
+        ad_r = _create_doublets(x, pairs_r, clusters=clusters_kept,
+                                resamp=resamp, half_size=half_size,
+                                adjust_size=adjust_size, rng=rng)
+        # Origins from the random pairs
+        c1 = clusters_kept[pairs_r[:, 0]]
+        c2 = clusters_kept[pairs_r[:, 1]]
+        oc = np.array([f"{a}+{b}" if a != b else None for a, b in zip(c1, c2)], dtype=object)
+        # _create_doublets may return more columns than ad_r has per-pair (due to adjust_size split);
+        # pad origins to the actual length
+        out_counts.append(ad_r)
+        if ad_r.shape[1] == oc.size:
+            out_origins.append(oc)
+        else:
+            out_origins.append(np.array([None] * ad_r.shape[1], dtype=object))
+
+    if n_cluster > 0:
+        # inter-cluster pairs, weighted "proportional" to cluster sizes
+        cl_counts = np.bincount(np.unique(clusters_kept, return_inverse=True)[1])
+        weights = cl_counts / cl_counts.sum()
+        uniq = np.unique(clusters_kept)
+        # Sample pairs of distinct clusters weighted by proportion^2
+        cpairs = []
+        for _ in range(n_cluster):
+            a, b = rng.choice(uniq.size, size=2, replace=False, p=weights)
+            cpairs.append((uniq[a], uniq[b]))
+        pair_idx = []
+        origins = []
+        for ca, cb in cpairs:
+            ia = np.random.default_rng(rng.integers(0, 2**31)).choice(
+                np.where(clusters_kept == ca)[0]
+            )
+            ib = np.random.default_rng(rng.integers(0, 2**31)).choice(
+                np.where(clusters_kept == cb)[0]
+            )
+            pair_idx.append([ia, ib])
+            origins.append(f"{ca}+{cb}")
+        pair_idx = np.asarray(pair_idx)
+        ad_c = _create_doublets(x, pair_idx, clusters=clusters_kept,
+                                resamp=resamp, half_size=half_size,
+                                adjust_size=adjust_size, rng=rng)
+        out_counts.append(ad_c)
+        out_origins.append(np.asarray(origins, dtype=object) if ad_c.shape[1] == len(origins)
+                           else np.array([None] * ad_c.shape[1], dtype=object))
+
+    combined = np.concatenate(out_counts, axis=1) if out_counts else np.zeros((n_genes, 0))
+    origins = np.concatenate(out_origins) if out_origins else np.array([], dtype=object)
+    return {"counts": combined, "origins": origins}