sclab 0.1.7__py3-none-any.whl → 0.3.4__py3-none-any.whl

sclab/tools/differential_expression/_pseudobulk_limma.py

@@ -0,0 +1,257 @@
+import pandas as pd
+from anndata import AnnData
+
+from ._pseudobulk_helpers import aggregate_and_filter
+
+
+def pseudobulk_limma(
+    adata_: AnnData,
+    group_key: str,
+    condition_group: str | list[str] | None = None,
+    reference_group: str | None = None,
+    cell_identity_key: str | None = None,
+    batch_key: str | None = None,
+    layer: str | None = None,
+    replicas_per_group: int = 5,
+    min_cells_per_group: int = 30,
+    bootstrap_sampling: bool = False,
+    use_cells: dict[str, list[str]] | None = None,
+    aggregate: bool = True,
+    verbosity: int = 0,
+) -> dict[str, pd.DataFrame]:
+    _try_imports()
+    import anndata2ri  # noqa: F401
+    import rpy2.robjects as robjects
+    from rpy2.rinterface_lib.embedded import RRuntimeError  # noqa: F401
+    from rpy2.robjects import pandas2ri  # noqa: F401
+    from rpy2.robjects.conversion import localconverter  # noqa: F401
+
+    R = robjects.r
+
+    if aggregate:
+        aggr_adata = aggregate_and_filter(
+            adata_,
+            group_key,
+            cell_identity_key,
+            layer,
+            replicas_per_group,
+            min_cells_per_group,
+            bootstrap_sampling,
+            use_cells,
+        )
+    else:
+        aggr_adata = adata_.copy()
+
+    with localconverter(anndata2ri.converter):
+        R.assign("aggr_adata", aggr_adata)
+
+    # defines the R function for fitting the model with limma
+    R(_fit_model_r_script)
+
+    if condition_group is None:
+        condition_group_list = aggr_adata.obs[group_key].unique()
+    elif isinstance(condition_group, str):
+        condition_group_list = [condition_group]
+    else:
+        condition_group_list = condition_group
+
+    if cell_identity_key is not None:
+        cids = aggr_adata.obs[cell_identity_key].unique()
+    else:
+        cids = [""]
+
+    tt_dict = {}
+    for condition_group in condition_group_list:
+        if reference_group is not None and condition_group == reference_group:
+            continue
+
+        if verbosity > 0:
+            print(f"Fitting model for {condition_group}...")
+
+        if reference_group is not None:
+            gk = group_key
+        else:
+            gk = f"{group_key}_{condition_group}"
+
+        try:
+            R(f"""
+                outs <- fit_limma_model(aggr_adata, "{gk}", "{cell_identity_key}", verbosity = {verbosity})
+                fit <- outs$fit
+                v <- outs$v
+            """)
+
+        except RRuntimeError as e:
+            print("Error fitting model for", condition_group)
+            print("Error:", e)
+            print("Skipping...", flush=True)
+            continue
+
+        if reference_group is None:
+            new_contrasts_tuples = [
+                (
+                    condition_group,  # common prefix
+                    "",  # condition group
+                    "not",  # reference group
+                    cid,  # cell identity
+                )
+                for cid in cids
+            ]
+
+        else:
+            new_contrasts_tuples = [
+                (
+                    "",  # common prefix
+                    condition_group,  # condition group
+                    reference_group,  # reference group
+                    cid,  # cell identity
+                )
+                for cid in cids
+            ]
+
+        new_contrasts = [
+            f"group{cnd}{prefix}_{cid}".strip("_")
+            + "-"
+            + f"group{ref}{prefix}_{cid}".strip("_")
+            for prefix, cnd, ref, cid in new_contrasts_tuples
+        ]
+
+        for contrast, contrast_tuple in zip(new_contrasts, new_contrasts_tuples):
+            prefix, cnd, ref, cid = contrast_tuple
+
+            if ref == "not":
+                cnd, ref = "", "rest"
+
+            contrast_key = f"{prefix}{cnd}_vs_{ref}"
+            if cid:
+                contrast_key = f"{cell_identity_key}:{cid}|{contrast_key}"
+
+            if verbosity > 0:
+                print(f"Computing contrast: {contrast_key}... ({contrast})")
+
+            R(f"myContrast <- makeContrasts('{contrast}', levels = v$design)")
+            R("fit2 <- contrasts.fit(fit, myContrast)")
+            R("fit2 <- eBayes(fit2)")
+            R("tt <- topTable(fit2, n = Inf)")
+            tt: pd.DataFrame = pandas2ri.rpy2py(R("tt"))
+            tt.index.name = "gene_ids"
+
+            genes = tt.index
+            cnd, ref = [c[5:] for c in contrast.split("-")]
+            tt["pct_expr_cnd"] = aggr_adata.var[f"pct_expr_{cnd}"].loc[genes]
+            tt["pct_expr_ref"] = aggr_adata.var[f"pct_expr_{ref}"].loc[genes]
+            tt["num_expr_cnd"] = aggr_adata.var[f"num_expr_{cnd}"].loc[genes]
+            tt["num_expr_ref"] = aggr_adata.var[f"num_expr_{ref}"].loc[genes]
+            tt["tot_expr_cnd"] = aggr_adata.var[f"tot_expr_{cnd}"].loc[genes]
+            tt["tot_expr_ref"] = aggr_adata.var[f"tot_expr_{ref}"].loc[genes]
+            tt["mean_cnd"] = tt["tot_expr_cnd"] / tt["num_expr_cnd"]
+            tt["mean_ref"] = tt["tot_expr_ref"] / tt["num_expr_ref"]
+            tt_dict[contrast_key] = tt
+
+    return tt_dict
+
+
+_fit_model_r_script = """
+suppressPackageStartupMessages({
+    library(edgeR)
+    library(limma)
+    library(MAST)
+})
+
+fit_limma_model <- function(adata_, group_key, cell_identity_key = "None", batch_key = "None", verbosity = 0){
+
+    if (verbosity > 0){
+        cat("Group key:", group_key, "\n")
+        cat("Cell identity key:", cell_identity_key, "\n")
+    }
+
+    # create a vector that is concatentation of condition and cell type that we will later use with contrasts
+    if (cell_identity_key == "None"){
+        group <- colData(adata_)[[group_key]]
+    } else {
+        group <- paste0(colData(adata_)[[group_key]], "_", colData(adata_)[[cell_identity_key]])
+    }
+
+    if (verbosity > 1){
+        cat("Group(s):", group, "\n")
+    }
+
+    group   <- factor(group)
+    replica <- factor(colData(adata_)$replica)
+
+    # create a design matrix
+    if (batch_key == "None"){
+        design <- model.matrix(~ 0 + group + replica)
+    } else {
+        batch  <- factor(colData(adata_)[[batch_key]])
+        design <- model.matrix(~ 0 + group + replica + batch)
+    }
+    colnames(design) <- make.names(colnames(design))
+
+    # create an edgeR object with counts and grouping factor
+    y <- DGEList(assay(adata_, "X"), group = group)
+
+    # filter out genes with low counts
+    if (verbosity > 1){
+        cat("Dimensions before subsetting:", dim(y), "\n")
+    }
+
+    keep <- filterByExpr(y, design = design)
+    y <- y[keep, , keep.lib.sizes=FALSE]
+    if (verbosity > 1){
+        cat("Dimensions after subsetting:", dim(y), "\n")
+    }
+
+    # normalize
+    y <- calcNormFactors(y)
+
+    # Apply voom transformation to prepare for linear modeling
+    v <- voom(y, design = design)
+
+    # fit the linear model
+    fit <- lmFit(v, design)
+    ne <- limma::nonEstimable(design)
+    if (!is.null(ne) && verbosity > 0) cat("Non-estimable:", ne, "\n")
+    fit <- eBayes(fit)
+
+    return(list("fit"=fit, "design"=design, "v"=v))
+}
+"""
+
+
+def _try_imports():
+    try:
+        import rpy2.robjects as robjects
+        from rpy2.robjects.packages import PackageNotInstalledError, importr
+
+        robjects.r("options(warn=-1)")
+        import anndata2ri  # noqa: F401
+        from rpy2.rinterface_lib.embedded import RRuntimeError  # noqa: F401
+        from rpy2.robjects import numpy2ri, pandas2ri  # noqa: F401
+        from rpy2.robjects.conversion import localconverter  # noqa: F401
+
+        importr("edgeR")
+        importr("limma")
+        importr("MAST")
+        importr("SingleCellExperiment")
+
+    except ModuleNotFoundError:
+        message = (
+            "pseudobulk_limma requires rpy2 and anndata2ri to be installed.\n"
+            "please install with one of the following:\n"
+            "$ pip install rpy2 anndata2ri\n"
+            "or\n"
+            "$ conda install -c conda-forge rpy2 anndata2ri\n"
+        )
+        print(message)
+        raise ModuleNotFoundError(message)
+
+    except PackageNotInstalledError:
+        message = (
+            "pseudobulk_limma requires the following R packages to be installed: limma, edgeR, MAST, and SingleCellExperiment.\n"
+            "> \n"
+            "> if (!require('BiocManager', quietly = TRUE)) install.packages('BiocManager');\n"
+            "> BiocManager::install(c('limma', 'edgeR', 'MAST', 'SingleCellExperiment'));\n"
+            "> \n"
+        )
+        print(message)
+        raise ImportError(message)

sclab/tools/doublet_detection/__init__.py

@@ -0,0 +1,5 @@
+from ._scrublet import scrublet
+
+__all__ = [
+    "scrublet",
+]

sclab/tools/doublet_detection/_scrublet.py

@@ -0,0 +1,64 @@
+from importlib.util import find_spec
+from typing import Any
+
+import pandas as pd
+from anndata import AnnData
+from numpy import ndarray
+
+
+def scrublet(
+    adata: AnnData,
+    layer: str = "X",
+    key_added: str = "scrublet",
+    total_counts: ndarray | None = None,
+    sim_doublet_ratio: float = 2.0,
+    n_neighbors: int = None,
+    expected_doublet_rate: float = 0.1,
+    stdev_doublet_rate: float = 0.02,
+    random_state: int = 0,
+    scrub_doublets_kwargs: dict[str, Any] = dict(
+        synthetic_doublet_umi_subsampling=1.0,
+        use_approx_neighbors=True,
+        distance_metric="euclidean",
+        get_doublet_neighbor_parents=False,
+        min_counts=3,
+        min_cells=3,
+        min_gene_variability_pctl=85,
+        log_transform=False,
+        mean_center=True,
+        normalize_variance=True,
+        n_prin_comps=30,
+        svd_solver="arpack",
+        verbose=True,
+    ),
+):
+    if find_spec("scrublet") is None:
+        raise ImportError(
+            "scrublet is not installed. Install with:\npip install scrublet"
+        )
+    from scrublet import Scrublet  # noqa: E402
+
+    if layer == "X":
+        X = adata.X
+    else:
+        X = adata.layers[layer]
+
+    scrub = Scrublet(
+        counts_matrix=X,
+        total_counts=total_counts,
+        sim_doublet_ratio=sim_doublet_ratio,
+        n_neighbors=n_neighbors,
+        expected_doublet_rate=expected_doublet_rate,
+        stdev_doublet_rate=stdev_doublet_rate,
+        random_state=random_state,
+    )
+
+    _scores, labels = scrub.scrub_doublets(**scrub_doublets_kwargs)
+    if labels is not None:
+        _labels = list(map(lambda v: "doublet" if v else "singlet", labels))
+        _labels = pd.Categorical(_labels, ["singlet", "doublet"])
+        adata.obs[f"{key_added}_label"] = _labels
+    else:
+        adata.obs[f"{key_added}_label"] = "singlet"
+
+    adata.obs[f"{key_added}_score"] = _scores

sclab/tools/imputation/_alra.py

@@ -0,0 +1,135 @@
+import gc
+
+import numpy as np
+from numpy import float32
+from numpy.typing import NDArray
+from scipy.sparse import csc_matrix, csr_matrix, issparse
+
+
+def _alra_on_ndarray(
+    data: NDArray | csr_matrix,
+) -> tuple[NDArray[float32], NDArray[float32]]:
+    """
+    Run ALRA on the given data.
+
+    Parameters
+    ----------
+    data : NDArray | csr_matrix
+        Input data to impute.
+
+    Returns
+    -------
+    data_aprx : NDArray
+        Approximated data.
+    data_alra : NDArray
+        Imputed data.
+    """
+    import rpy2.robjects as robjects
+    import rpy2.robjects.numpy2ri
+    from rpy2.robjects.packages import importr
+
+    rpy2.robjects.numpy2ri.activate()
+    R = robjects.r
+    alra = importr("ALRA")
+
+    if issparse(data):
+        data = np.ascontiguousarray(data.todense("C"), dtype=np.float32)
+
+    # convert to R object
+    r_X = R.matrix(data, nrow=data.shape[0], ncol=data.shape[1])
+    # run ALRA
+    r_res = alra.alra(r_X, 0, 10, 0.001)
+    # retrieve imputed data
+    r_K = r_res[0]  # rank k
+    r_T = r_res[1]  # rank k thresholded
+    r_S = r_res[2]  # rank k thresholded scaled
+    # convert back to numpy array
+    data_aprx = np.array(r_K, dtype=float32)
+    data_thrs = np.array(r_T, dtype=float32)
+    data_alra = np.array(r_S, dtype=float32)
+
+    # clean up
+    del (r_X, r_res, r_K, r_T, r_S)
+    R("gc()")
+    gc.collect()
+
+    return data_aprx, data_thrs, data_alra
+
+
+def _fix_alra_scale(
+    input_data: NDArray | csr_matrix | csc_matrix,
+    thrs_data: NDArray,
+    target_data: NDArray,
+) -> NDArray:
+    # Convert sparse -> dense
+    if issparse(input_data):
+        input_data = input_data.toarray("C")
+        input_data = input_data.astype(np.float32)
+        input_data = np.ascontiguousarray(input_data, dtype=np.float32)
+
+    n_cells, n_genes = input_data.shape
+
+    # per-gene nonzero means/sds (match R: sample sd ddof=1)
+    input_means = np.full(n_genes, fill_value=np.nan)
+    input_stds = np.full(n_genes, fill_value=np.nan)
+    thrs_means = np.full(n_genes, fill_value=np.nan)
+    thrs_stds = np.full(n_genes, fill_value=np.nan)
+    v: NDArray
+
+    for i, e in enumerate(input_data.T):
+        v = e[e > 0]
+
+        if v.size == 0:
+            continue
+        input_means[i] = v.mean()
+
+        if v.size == 1:
+            continue
+        input_stds[i] = v.std(ddof=1)
+
+    for i, e in enumerate(thrs_data.T):
+        v = e[e > 0]
+
+        if v.size == 0:
+            continue
+        thrs_means[i] = v.mean()
+
+        if v.size == 1:
+            continue
+        thrs_stds[i] = v.std(ddof=1)
+
+    # columns to scale (mirror R's toscale)
+    toscale = (
+        ~np.isnan(thrs_stds)
+        & ~np.isnan(input_stds)
+        & ~((thrs_stds == 0) & (input_stds == 0))
+        & ~(thrs_stds == 0)
+    )
+
+    # affine params
+    a = np.full(n_genes, fill_value=1.0)
+    b = np.full(n_genes, fill_value=0.0)
+    a[toscale] = input_stds[toscale] / thrs_stds[toscale]
+    b[toscale] = input_means[toscale] - a[toscale] * thrs_means[toscale]
+
+    # apply to target matrix (only columns in toscale)
+    out = target_data.copy()
+    out[:, toscale] = out[:, toscale] * a[toscale] + b[toscale]
+
+    # keep zeros as zeros
+    out[thrs_data == 0] = 0
+
+    # clip negatives to zero
+    out[out < 0] = 0
+
+    # restore originally observed positives that became zero
+    mask = (input_data > 0) & (out == 0)
+    out[mask] = input_data[mask]
+
+    return out
+
+
+__all__ = [
+    "_alra_on_ndarray",
+    "_fix_alra_scale",
+]

sclab/tools/labeling/__init__.py

@@ -0,0 +1,6 @@
+from . import sctype
+
+
+__all__ = [
+    "sctype",
+]

sclab/tools/labeling/sctype.py

@@ -0,0 +1,233 @@
+import logging
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+from anndata import AnnData
+from numpy.typing import NDArray
+from scipy import stats
+from scipy.sparse import csc_matrix, csr_matrix, issparse
+
+from ...preprocess import pool_neighbors
+
+logger = logging.getLogger(__name__)
+
+
+def _get_classification_scores_matrix(
+    adata: AnnData,
+    markers: pd.DataFrame,
+    marker_class_key: str,
+    neighbors_key: Optional[str] = None,
+    weighted_pooling: bool = False,
+    directed_pooling: bool = True,
+    layer: Optional[str] = None,
+    penalize_non_specific: bool = True,
+):
+    # Ianevski, A., Giri, A.K. & Aittokallio, T.
+    # Fully-automated and ultra-fast cell-type identification using specific
+    # marker combinations from single-cell transcriptomic data.
+    # Nat Commun 13, 1246 (2022).
+    # https://doi.org/10.1038/s41467-022-28803-w
+
+    if layer is not None:
+        X = adata.layers[layer]
+
+    else:
+        X = adata.X
+
+    min_val: np.number = X.min()
+    M = X > min_val
+    n_cells = np.asarray(M.sum(axis=0)).squeeze()
+    mask = n_cells > 5
+    print(f"using {mask.sum()} genes")
+
+    markers = markers.loc[markers["names"].isin(adata.var_names[mask])].copy()
+    classes = markers[marker_class_key].cat.categories
+
+    x = markers[[marker_class_key, "names"]].groupby("names").count()[marker_class_key]
+    if penalize_non_specific:
+        S = 1.0 - (x - x.min()) / (x.max() - x.min())
+        S = S[S > 0]
+    else:
+        S = x * 0.0 + 1.0
+
+    X: NDArray | csr_matrix | csc_matrix
+    if neighbors_key is not None:
+        X = pool_neighbors(
+            adata[:, S.index],
+            layer=layer,
+            neighbors_key=neighbors_key,
+            weighted=weighted_pooling,
+            directed=directed_pooling,
+            copy=True,
+        )
+
+    elif layer is not None:
+        X = adata[:, S.index].layers[layer].copy()
+
+    else:
+        X = adata[:, S.index].X.copy()
+
+    if issparse(X):
+        X = np.asarray(X.todense("C"))
+
+    Z: NDArray
+    Z = stats.zscore(X, axis=0)
+    Xp = Z * S.values
+
+    Xc = np.zeros((adata.shape[0], len(classes)))
+    for c, cell_class in enumerate(classes):
+        if cell_class == "Unknown":
+            continue
+        up_genes = markers.loc[
+            (markers[marker_class_key] == cell_class) & (markers["logfoldchanges"] > 0),
+            "names",
+        ]
+        dw_genes = markers.loc[
+            (markers[marker_class_key] == cell_class) & (markers["logfoldchanges"] < 0),
+            "names",
+        ]
+        x_up = Xp[:, S.index.isin(up_genes)]
+        x_dw = Xp[:, S.index.isin(dw_genes)]
+        if len(up_genes) > 0:
+            Xc[:, c] += x_up.sum(axis=1) / np.sqrt(len(up_genes))
+        if len(dw_genes) > 0:
+            Xc[:, c] -= x_dw.sum(axis=1) / np.sqrt(len(dw_genes))
+
+    return Xc
+
+
+def classify_cells(
+    adata: AnnData,
+    markers: pd.DataFrame,
+    marker_class_key: Optional[str] = None,
+    cluster_key: Optional[str] = None,
+    layer: Optional[str] = None,
+    key_added: Optional[str] = None,
+    threshold: float = 0.25,
+    penalize_non_specific: bool = True,
+    neighbors_key: Optional[str] = None,
+    save_scores: bool = False,
+):
+    """
+    Classify cells based on a set of marker genes.
+
+    Ianevski, A., Giri, A.K. & Aittokallio, T.
+    Fully-automated and ultra-fast cell-type identification using specific
+    marker combinations from single-cell transcriptomic data.
+    Nat Commun 13, 1246 (2022).
+    https://doi.org/10.1038/s41467-022-28803-w
+
+    Parameters
+    ----------
+    adata
+        AnnData object.
+    markers
+        Marker genes.
+    marker_class_key
+        Column in `markers` that contains the cell type information.
+    cluster_key
+        Column in `adata.obs` that contains the cluster information. If
+        not provided, the classification will be performed on a cell by cell
+        basis, pooling across neighbor cells. This pooling can be avoided by
+        setting `force_pooling` to `False`.
+    layer
+        Layer to use for classification. Defaults to `X`.
+    key_added
+        Key under which to add the classification information.
+    threshold
+        Confidence threshold for classification. Defaults to `0.25`.
+    penalize_non_specific
+        Whether to penalize non-specific markers. Defaults to `True`.
+    neighbors_key
+        If provided, counts will be pooled across neighbor cells using the
+        distances in `adata.uns[neighbors_key]["distances"]`. Defaults to `None`.
+    save_scores
+        Whether to save the classification scores. Defaults to `False`
+    """
+    # cite("10.1038/s41467-022-28803-w", __package__)
+
+    if marker_class_key is not None:
+        marker_class = markers[marker_class_key]
+        if not marker_class.dtype.name.startswith("category"):
+            markers[marker_class_key] = marker_class.astype("category")
+    else:
+        col_mask = markers.dtypes == "category"
+        assert col_mask.sum() == 1, (
+            "markers_df must have exactly one column of type 'category'"
+        )
+        marker_class_key = markers.loc[:, col_mask].squeeze().name
+
+    classes = markers[marker_class_key].cat.categories
+    dtype = markers[marker_class_key].dtype
+
+    # if doing cell by cell classification, we should pool counts to use cell
+    # neighborhood information. This allows to estimate the confidence of the
+    # classification. We specify pooling by providing a neighbors_key.
+    posXc = _get_classification_scores_matrix(
+        adata,
+        markers.query("logfoldchanges > 0"),
+        marker_class_key,
+        neighbors_key,
+        weighted_pooling=True,
+        directed_pooling=True,
+        layer=layer,
+        penalize_non_specific=penalize_non_specific,
+    )
+    negXc = _get_classification_scores_matrix(
+        adata,
+        markers.query("logfoldchanges < 0"),
+        marker_class_key,
+        neighbors_key,
+        weighted_pooling=True,
+        directed_pooling=True,
+        layer=layer,
+        penalize_non_specific=penalize_non_specific,
+    )
+    Xc = posXc + negXc
+
+    if cluster_key is not None:
+        mappings = {}
+        mappings_nona = {}
+        for c in adata.obs[cluster_key].cat.categories:
+            cluster_scores_matrix = Xc[adata.obs[cluster_key] == c]
+            n_cells_in_cluster = cluster_scores_matrix.shape[0]
+
+            scores = cluster_scores_matrix.sum(axis=0)
+            confidence = scores.max() / n_cells_in_cluster
+            if confidence >= threshold:
+                mappings[c] = classes[np.argmax(scores)]
+            else:
+                mappings[c] = pd.NA
+                logger.warning(
+                    f"Cluster {str(c):>5} classified as Unknown with confidence score {confidence: 8.2f}"
+                )
+            mappings_nona[c] = classes[np.argmax(scores)]
+        classifications = adata.obs[cluster_key].map(mappings).astype(dtype)
+        classifications_nona = adata.obs[cluster_key].map(mappings_nona).astype(dtype)
+    else:
+        if neighbors_key is not None:
+            n_neigs = adata.uns[neighbors_key]["params"]["n_neighbors"]
+        else:
+            n_neigs = 1
+        index = adata.obs_names
+        classifications = classes.values[Xc.argmax(axis=1)]
+        classifications = pd.Series(classifications, index=index).astype(dtype)
+        classifications_nona = classifications.copy()
+        classifications.loc[Xc.max(axis=1) < threshold * n_neigs] = pd.NA
+
+        N = len(classifications)
+        n_unknowns = pd.isna(classifications).sum()
+        n_estimated = N - n_unknowns
+
+        logger.info(f"Estimated types for {n_estimated} cells ({n_estimated / N:.2%})")
+
+    if key_added is None:
+        key_added = marker_class_key
+
+    adata.obs[key_added] = classifications
+    adata.obs[key_added + "_noNA"] = classifications_nona
+
+    if save_scores:
+        adata.obs[key_added + "_score"] = Xc.max(axis=1)
+        adata.obsm[key_added + "_scores"] = Xc