sclab 0.2.5__py3-none-any.whl → 0.3.0__py3-none-any.whl

sclab/tools/differential_expression/_pseudobulk_helpers.py

@@ -0,0 +1,277 @@
+import random
+
+import numpy as np
+import pandas as pd
+from anndata import AnnData
+from numpy import ndarray
+from scipy.sparse import csr_matrix, issparse
+
+
+# code inspired from
+# https://www.sc-best-practices.org/conditions/differential_gene_expression.html
+def aggregate_and_filter(
+    adata: AnnData,
+    group_key: str = "batch",
+    cell_identity_key: str | None = None,
+    layer: str | None = None,
+    replicas_per_group: int = 3,
+    min_cells_per_group: int = 30,
+    bootstrap_sampling: bool = False,
+    use_cells: dict[str, list[str]] | None = None,
+) -> AnnData:
+    """
+    Aggregate and filter cells in an AnnData object into cell populations.
+
+    Parameters
+    ----------
+    adata : AnnData
+        AnnData object to aggregate and filter.
+    group_key : str, optional
+        Key to group cells by. Defaults to 'batch'.
+    cell_identity_key : str, optional
+        Key to use to identify cell identities. Defaults to None.
+    layer : str, optional
+        Layer in AnnData object to use for aggregation. Defaults to None.
+    replicas_per_group : int, optional
+        Number of replicas to create for each group. Defaults to 3.
+    min_cells_per_group : int, optional
+        Minimum number of cells required for a group to be included. Defaults to 30.
+    bootstrap_sampling : bool, optional
+        Whether to use bootstrap sampling to create replicas. Defaults to False.
+    use_cells : dict[str, list[str]], optional
+        If not None, only use the specified cells. Defaults to None.
+
+    Returns
+    -------
+    AnnData
+        AnnData object with aggregated and filtered cells.
+    """
+    adata = _prepare_dataset(adata, use_cells)
+
+    grouping_keys = [group_key]
+    if cell_identity_key is not None:
+        grouping_keys.append(cell_identity_key)
+
+    groups_to_drop = _get_groups_to_drop(adata, grouping_keys, min_cells_per_group)
+
+    _prepare_categorical_column(adata, group_key)
+    group_dtype = adata.obs[group_key].dtype
+
+    if cell_identity_key is not None:
+        _prepare_categorical_column(adata, cell_identity_key)
+        cell_identity_dtype = adata.obs[cell_identity_key].dtype
+
+    var_dataframe = _create_var_dataframe(adata, layer, grouping_keys, groups_to_drop)
+
+    data = {}
+    meta = {}
+    groups = adata.obs.groupby(grouping_keys, observed=True).groups
+    for group, group_idxs in groups.items():
+        if not isinstance(group, tuple):
+            group = (group,)
+
+        if not _including(group, groups_to_drop):
+            continue
+
+        sample_id = "_".join(group)
+        match group:
+            case (gid, cid):
+                group_metadata = {group_key: gid, cell_identity_key: cid}
+            case (gid,):
+                group_metadata = {group_key: gid}
+
+        adata_group = adata[group_idxs]
+        indices = _get_replica_idxs(adata_group, replicas_per_group, bootstrap_sampling)
+        for i, rep_idx in enumerate(indices):
+            replica_number = i + 1
+            replica_size = len(rep_idx)
+            replica_sample_id = f"{sample_id}_rep{replica_number}"
+
+            adata_group_replica = adata_group[rep_idx]
+            X = _get_layer(adata_group_replica, layer)
+
+            data[replica_sample_id] = np.array(X.sum(axis=0)).flatten()
+            meta[replica_sample_id] = {
+                **group_metadata,
+                "replica": str(replica_number),
+                "replica_size": replica_size,
+            }
+
+    data = pd.DataFrame(data).T
+    meta = pd.DataFrame(meta).T
+    meta["replica"] = meta["replica"].astype("category")
+    meta[group_key] = meta[group_key].astype(group_dtype)
+    if cell_identity_key is not None:
+        meta[cell_identity_key] = meta[cell_identity_key].astype(cell_identity_dtype)
+
+    aggr_adata = AnnData(
+        data.values,
+        obs=meta,
+        var=var_dataframe,
+    )
+
+    _join_dummies(aggr_adata, group_key)
+
+    return aggr_adata
+
+
+def _prepare_dataset(
+    adata: AnnData,
+    use_cells: dict[str, list[str]] | None,
+) -> AnnData:
+    if use_cells is not None:
+        for key, value in use_cells.items():
+            adata = adata[adata.obs[key].isin(value)]
+
+    return adata.copy()
+
+
+def _get_groups_to_drop(
+    adata: AnnData,
+    grouping_keys: str | list[str],
+    min_cells_per_group: int,
+):
+    group_sizes = adata.obs.groupby(grouping_keys, observed=True).size()
+    groups_to_drop = group_sizes[group_sizes < min_cells_per_group].index.to_list()
+
+    if len(groups_to_drop) > 0:
+        print("Dropping the following samples:")
+
+    groups_to_drop = groups_to_drop + [
+        (g,) for g in groups_to_drop if not isinstance(g, tuple)
+    ]
+
+    return groups_to_drop
+
+
+def _prepare_categorical_column(adata: AnnData, column: str) -> None:
+    if not isinstance(adata.obs[column].dtype, pd.CategoricalDtype):
+        adata.obs[column] = adata.obs[column].astype("category")
+
+
+def _create_var_dataframe(
+    adata: AnnData,
+    layer: str,
+    grouping_keys: list[str],
+    groups_to_drop: list[str],
+):
+    columns = _get_var_dataframe_columns(adata, grouping_keys, groups_to_drop)
+    var_dataframe = pd.DataFrame(index=adata.var_names, columns=columns, dtype=float)
+
+    groups = adata.obs.groupby(grouping_keys, observed=True).groups
+    for group, idx in groups.items():
+        if not isinstance(group, tuple):
+            group = (group,)
+
+        if not _including(group, groups_to_drop):
+            continue
+
+        sample_id = "_".join(group)
+        rest_id = f"not{sample_id}"
+
+        adata_subset = adata[idx]
+        rest_subset = adata[~adata.obs_names.isin(idx)]
+
+        X = _get_layer(adata_subset, layer, dense=True)
+        Y = _get_layer(rest_subset, layer, dense=True)
+
+        var_dataframe[f"pct_expr_{sample_id}"] = (X > 0).mean(axis=0)
+        var_dataframe[f"pct_expr_{rest_id}"] = (Y > 0).mean(axis=0)
+        var_dataframe[f"num_expr_{sample_id}"] = (X > 0).sum(axis=0)
+        var_dataframe[f"num_expr_{rest_id}"] = (Y > 0).sum(axis=0)
+        var_dataframe[f"tot_expr_{sample_id}"] = X.sum(axis=0)
+        var_dataframe[f"tot_expr_{rest_id}"] = Y.sum(axis=0)
+
+    return var_dataframe
+
+
+def _get_var_dataframe_columns(
+    adata: AnnData, grouping_keys: list[str], groups_to_drop: list[str]
+) -> list[str]:
+    columns = []
+
+    groups = adata.obs.groupby(grouping_keys, observed=True).groups
+    for group, _ in groups.items():
+        if not isinstance(group, tuple):
+            group = (group,)
+
+        if not _including(group, groups_to_drop):
+            continue
+
+        sample_id = "_".join(group)
+        rest_id = f"not{sample_id}"
+
+        columns.extend(
+            [
+                f"pct_expr_{sample_id}",
+                f"pct_expr_{rest_id}",
+                f"num_expr_{sample_id}",
+                f"num_expr_{rest_id}",
+                f"tot_expr_{sample_id}",
+                f"tot_expr_{rest_id}",
+            ]
+        )
+
+    return columns
+
+
+def _including(group: tuple | str, groups_to_drop: list[str]) -> bool:
+    match group:
+        case (gid, cid):
+            if isinstance(cid, float) and np.isnan(cid):
+                return False
+
+        case (gid,) | gid:
+            ...
+
+    if gid in groups_to_drop:
+        return False
+
+    return True
+
+
+def _get_replica_idxs(
+    adata_group: AnnData,
+    replicas_per_group: int,
+    bootstrap_sampling: bool,
+):
+    group_size = adata_group.n_obs
+    indices = list(adata_group.obs_names)
+    if bootstrap_sampling:
+        indices = np.array(
+            [
+                np.random.choice(indices, size=group_size, replace=True)
+                for _ in range(replicas_per_group)
+            ]
+        )
+
+    else:
+        random.shuffle(indices)
+        indices = np.array_split(np.array(indices), replicas_per_group)
+
+    return indices
+
+
+def _get_layer(adata: AnnData, layer: str | None, dense: bool = False):
+    X: ndarray | csr_matrix
+
+    if layer is None or layer == "X":
+        X = adata.X
+    else:
+        X = adata.layers[layer]
+
+    if dense:
+        if issparse(X):
+            X = np.asarray(X.todense())
+        else:
+            X = np.asarray(X)
+
+    return X
+
+
+def _join_dummies(aggr_adata: AnnData, group_key: str) -> None:
+    dummies = pd.get_dummies(aggr_adata.obs[group_key], prefix=group_key).astype(str)
+    dummies = dummies.astype(str).apply(lambda s: s.map({"True": "", "False": "not"}))
+    dummies = dummies + aggr_adata.obs[group_key].cat.categories
+
+    aggr_adata.obs = aggr_adata.obs.join(dummies)

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

sclab/utils/__init__.py

@@ -0,0 +1,5 @@
+from ._write_excel import write_excel
+
+__all__ = [
+    "write_excel",
+]