pyscdblfinder 0.1.0__py3-none-any.whl

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/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}

pyscdblfinder/classifier.py

@@ -0,0 +1,171 @@
+"""xgboost training loop + iterative doublet scoring.
+
+Mirrors R's ``.scDblscore`` with ``scoreType='xgb'``: train a gradient-
+boosted binary classifier (real vs artificial doublet), predict scores
+for all cells, iteratively remove likely-doublet real cells from the
+training set, and retrain. Returns final per-cell score.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+
+DEFAULT_EXCLUDE_COLS = {
+    "mostLikelyOrigin", "originAmbiguous", "distanceToNearestDoublet",
+    "type", "src", "distanceToNearest", "class", "nearestClass",
+    "cluster", "sample", "expected", "include.in.training", "observed",
+}
+
+
+def _default_features(df: pd.DataFrame) -> list[str]:
+    return [c for c in df.columns if c not in DEFAULT_EXCLUDE_COLS]
+
+
+def _xgb_train(
+    X: np.ndarray,
+    y: np.ndarray,
+    *,
+    nrounds: float | int = 0.25,
+    max_depth: int = 4,
+    eta: float = 0.3,
+    metric: str = "logloss",
+    subsample: float = 0.75,
+    nfold: int = 5,
+    nthreads: int = 1,
+    random_state: int = 0,
+):
+    """Train the binary xgboost classifier.
+
+    If ``nrounds <= 1``, use 5-fold CV to pick a round count, then subtract
+    ``nrounds * sd(CV error)`` from the best round (matches R behavior).
+    Otherwise use ``nrounds`` directly.
+    """
+    import xgboost as xgb
+
+    params = {
+        "objective": "binary:logistic",
+        "eval_metric": metric,
+        "max_depth": int(max_depth),
+        "learning_rate": float(eta),
+        "subsample": float(subsample),
+        "tree_method": "exact",
+        "nthread": int(nthreads),
+        "verbosity": 0,
+        "seed": int(random_state),
+    }
+    dtrain = xgb.DMatrix(X, label=y.astype(np.float32))
+
+    if nrounds is None or float(nrounds) <= 1.0:
+        cv = xgb.cv(
+            params, dtrain, num_boost_round=100, nfold=min(nfold, max(3, X.shape[0] // 10)),
+            early_stopping_rounds=10, seed=int(random_state), verbose_eval=False,
+        )
+        err_col = next(c for c in cv.columns if c.endswith("-mean") and "test" in c)
+        sd_col = err_col.replace("-mean", "-std")
+        best = int(cv[err_col].idxmin())
+        best -= int(round(float(nrounds) * cv[sd_col].iloc[best]))
+        nrounds = max(5, best)
+    else:
+        nrounds = int(nrounds)
+
+    bst = xgb.train(params, dtrain, num_boost_round=nrounds)
+    return bst
+
+
+def scDbl_score(
+    d: pd.DataFrame,
+    *,
+    add_vals: Optional[np.ndarray] = None,
+    features: Optional[list[str]] = None,
+    nrounds: float | int = 0.25,
+    max_depth: int = 4,
+    iter: int = 3,
+    dbr: Optional[float] = None,
+    dbr_per1k: float = 0.008,
+    unident_th: float = 0.1,
+    metric: str = "logloss",
+    random_state: int = 0,
+    verbose: bool = False,
+) -> pd.DataFrame:
+    """Port of R ``.scDblscore`` (``scoreType='xgb'``).
+
+    ``d`` must have columns ``type`` ("real"/"doublet"), ``src`` ("real"/"artificial"),
+    and the numeric features from ``evaluate_knn`` / ``cxds_score``.
+    Adds a ``score`` column (predicted doublet probability) to ``d``.
+    """
+    import xgboost as xgb
+
+    d = d.copy()
+    if features is None:
+        feat_cols = _default_features(d)
+    else:
+        feat_cols = [c for c in features if c in d.columns]
+    X = d[feat_cols].astype(float).values
+    if add_vals is not None:
+        X = np.concatenate([X, np.asarray(add_vals, dtype=float)], axis=1)
+
+    y = (d["type"].values == "doublet").astype(np.int32)
+
+    # Initial score — average of cxds_score and normalized ratio (R line:
+    # d$score <- (d$cxds_score + d[[ratio]]/max(d[[ratio]]))/2)
+    ratio_cols = [c for c in d.columns if c.startswith("ratio.k")]
+    ratio_col = ratio_cols[-1] if ratio_cols else None
+    if ratio_col is not None and "cxds_score" in d.columns:
+        rat = d[ratio_col].astype(float).values
+        rat = rat / (rat.max() if rat.max() > 0 else 1.0)
+        d["score"] = (d["cxds_score"].astype(float).values + rat) / 2.0
+    elif ratio_col is not None:
+        d["score"] = d[ratio_col].astype(float).values
+    else:
+        d["score"] = 0.5
+
+    n_real = int((d["type"].values == "real").sum())
+    n_dbl = int((d["type"].values == "doublet").sum())
+    if dbr is None:
+        # Expected doublet rate from dbr.per1k: fraction ≈ dbr_per1k * n_real / 1000
+        dbr = dbr_per1k * n_real / 1000.0
+    # Deviation budget
+    for it in range(int(iter)):
+        # Exclude cells that look like doublets (top-dbr-ish fraction) from training
+        from .thresholding import doublet_thresholding
+        exclude_real = np.where(
+            (d["type"].values == "real") &
+            (doublet_thresholding(d, dbr=dbr, stringency=0.7, return_type="call") == "doublet")
+        )[0]
+        # Cap the excluded fraction so we don't starve the training set
+        if exclude_real.size > n_real // 3:
+            sort_idx = np.argsort(-d["score"].values)
+            exclude_real = [i for i in sort_idx if d["type"].values[i] == "real"][:int(0.2 * n_real)]
+            exclude_real = np.asarray(exclude_real, dtype=int)
+
+        exclude_dbl = np.where(
+            (d["type"].values == "doublet") & (d["score"].values < unident_th)
+        )[0]
+        if exclude_dbl.size > n_dbl // 4:
+            sort_idx = np.argsort(d["score"].values)
+            exclude_dbl = [i for i in sort_idx if d["type"].values[i] == "doublet"][:int(0.1 * n_dbl)]
+            exclude_dbl = np.asarray(exclude_dbl, dtype=int)
+
+        include = np.ones(len(d), dtype=bool)
+        include[exclude_real] = False
+        include[exclude_dbl] = False
+
+        if verbose:
+            print(f"[scDblscore] iter={it}  excluding {(~include).sum()} cells from training")
+
+        try:
+            bst = _xgb_train(
+                X[include], y[include],
+                nrounds=nrounds, max_depth=max_depth, metric=metric,
+                random_state=random_state,
+            )
+            dmat_all = xgb.DMatrix(X)
+            d["score"] = bst.predict(dmat_all)
+        except Exception as exc:  # pragma: no cover
+            if verbose:
+                print(f"[scDblscore] xgboost failed: {exc}; keeping previous score")
+
+    return d

pyscdblfinder/core.py

@@ -0,0 +1,170 @@
+"""Top-level scDblFinder pipeline — port of R ``scDblFinder`` (single-sample).
+
+Follows the R function's single-sample path (``scDblFinder.R`` lines ~330-520)
+end-to-end: feature selection → optional clustering → artificial-doublet
+synthesis → merged-matrix feature extraction → kNN → xgboost scoring →
+thresholding. Multi-sample (``samples=``), ATAC ``aggregateFeatures``,
+``knownDoublets``, and ``clustCor`` paths are not yet ported — follow-up
+work flagged in the README.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+
+from .artificial import get_artificial_doublets
+from .classifier import scDbl_score
+from .cxds import cxds_score
+from .knn_features import default_k_grid, evaluate_knn
+from .preprocessing import default_processing, select_features
+from .thresholding import doublet_thresholding
+
+
+@dataclass
+class ScDblFinderResult:
+    """Output of :func:`sc_dbl_finder`. Mirrors R's ``returnType='table'``.
+
+    Attributes
+    ----------
+    table : per-cell DataFrame with everything scDblFinder computes —
+        ``type`` (real/doublet), ``src`` (real/artificial), ``score``,
+        ``class``, kNN features, cxds_score, library size, etc.
+    score_threshold : the threshold used to produce ``class``.
+    n_real : number of real cells (always the *first* rows of ``table``).
+    """
+
+    table: pd.DataFrame
+    score_threshold: float
+    n_real: int
+
+    def real_cells(self) -> pd.DataFrame:
+        """Rows of ``table`` corresponding to real cells only (not artificial)."""
+        return self.table.iloc[: self.n_real]
+
+
+def sc_dbl_finder(
+    counts,
+    *,
+    clusters: Optional[np.ndarray] = None,
+    artificial_doublets: Optional[int] = None,
+    dbr: Optional[float] = None,
+    dbr_sd: Optional[float] = None,
+    dbr_per1k: float = 0.008,
+    n_features: int = 1352,
+    dims: int = 20,
+    k: Optional[int | list[int]] = None,
+    prop_random: float = 0.0,
+    include_pcs: int = 19,
+    metric: str = "logloss",
+    nrounds: float | int = 0.25,
+    max_depth: int = 4,
+    iter: int = 3,
+    unident_th: Optional[float] = None,
+    threshold: bool = True,
+    random_state: int = 0,
+    verbose: bool = False,
+) -> ScDblFinderResult:
+    """Python port of R ``scDblFinder`` (single-sample path).
+
+    Parameters largely match the R signature. ``counts`` must be a
+    **genes × cells** matrix (dense ndarray or scipy sparse).
+    """
+    counts = counts if sp.issparse(counts) else np.asarray(counts, dtype=np.float64)
+    n_genes, n_real = counts.shape
+
+    if unident_th is None:
+        unident_th = 0.2 if clusters is None else 0.0
+
+    # 1) Feature selection (purely variance-based; see R's selFeatures)
+    if n_features < n_genes:
+        sel = select_features(counts, clusters, n_features=n_features)
+        counts_sel = counts[sel] if sp.issparse(counts) else counts[sel, :]
+    else:
+        counts_sel = counts
+
+    # 2) Artificial doublet count
+    if artificial_doublets is None:
+        n_ad = int(min(25000, max(1500, np.ceil(n_real * 0.8),
+                                  10 * (1 if clusters is None else len(np.unique(clusters))) ** 2)))
+    else:
+        n_ad = int(artificial_doublets)
+    if n_ad <= 2:
+        n_ad = int(min(round(n_ad * n_real), 25000))
+
+    if verbose:
+        print(f"[scDblFinder] creating ~{n_ad} artificial doublets "
+              f"({'random' if clusters is None else 'cluster-aware'})")
+
+    ad = get_artificial_doublets(
+        counts_sel, n=n_ad, clusters=clusters, prop_random=prop_random,
+        seed=random_state,
+    )
+    ad_counts = ad["counts"]  # (n_genes_sel, n_ad_actual)
+    n_ad_actual = ad_counts.shape[1]
+    origins = ad["origins"]
+
+    # 3) Merge real + artificial
+    if sp.issparse(counts_sel):
+        merged = sp.hstack([counts_sel, sp.csr_matrix(ad_counts)]).tocsc()
+    else:
+        merged = np.concatenate([np.asarray(counts_sel), ad_counts], axis=1)
+
+    ctype = np.concatenate([np.zeros(n_real, dtype=int),
+                            np.ones(n_ad_actual, dtype=int)])
+    all_origins = np.array([None] * n_real + list(origins), dtype=object)
+
+    # 4) cxds_score, library size, n_features, n_above_2
+    if verbose:
+        print("[scDblFinder] computing cxds + size features")
+    lsizes = np.asarray(merged.sum(axis=0)).ravel() if sp.issparse(merged) else merged.sum(axis=0)
+    n_feat = np.asarray((merged > 0).sum(axis=0)).ravel() if sp.issparse(merged) else (merged > 0).sum(axis=0)
+    n_above2 = np.asarray((merged > 2).sum(axis=0)).ravel() if sp.issparse(merged) else (merged > 2).sum(axis=0)
+    artificial_idx = np.where(ctype == 1)[0]
+    cxds = cxds_score(merged, which_dbls=artificial_idx)
+
+    # 5) PCA
+    if verbose:
+        print(f"[scDblFinder] PCA (dims={dims})")
+    pca = default_processing(merged, dims=dims, random_state=random_state)
+
+    # 6) kNN features
+    if verbose:
+        print("[scDblFinder] kNN features")
+    k_list = default_k_grid(n_real, k)
+    d = evaluate_knn(pca, ctype, k=k_list, origins=all_origins)
+    d["type"] = np.where(ctype == 0, "real", "doublet")
+    d["src"] = np.where(ctype == 0, "real", "artificial")
+    d["cxds_score"] = cxds
+    d["lsizes"] = lsizes
+    d["nfeatures"] = n_feat
+    d["nAbove2"] = n_above2
+
+    # 7) xgboost classification loop
+    if verbose:
+        print("[scDblFinder] xgboost scoring")
+    # Include the top principal components as additional predictors
+    n_pc_use = int(include_pcs) if np.isscalar(include_pcs) else len(include_pcs)
+    add_vals = pca[:, : min(n_pc_use, pca.shape[1] - 1)]
+    d = scDbl_score(
+        d, add_vals=add_vals,
+        nrounds=nrounds, max_depth=max_depth, iter=iter,
+        dbr=dbr, dbr_per1k=dbr_per1k, unident_th=float(unident_th),
+        metric=metric, random_state=random_state, verbose=verbose,
+    )
+
+    # 8) Threshold
+    if threshold:
+        th = doublet_thresholding(
+            d, dbr=dbr, dbr_sd=dbr_sd, dbr_per1k=dbr_per1k,
+            return_type="threshold",
+        )
+        d["class"] = np.where(d["score"].values >= th, "doublet", "singlet")
+    else:
+        th = float("nan")
+        d["class"] = "singlet"
+
+    return ScDblFinderResult(table=d, score_threshold=float(th), n_real=n_real)