resolutiontree 0.1.0__py3-none-any.whl

resolutiontree/utils.py

@@ -0,0 +1,377 @@
+from __future__ import annotations
+import sys
+import pandas as pd
+from collections.abc import Sequence
+from typing import Literal
+from anndata import AnnData
+from scanpy.tools._rank_genes_groups import rank_genes_groups
+
+def find_cluster_specific_genes(
+    adata: AnnData,
+    resolutions: Sequence[float],
+    *,
+    prefix: str = "leiden_res_",
+    method: Literal["wilcoxon"] = "wilcoxon",
+    n_top_genes: int = 3,
+    min_cells: int = 2,
+    deg_mode: Literal["within_parent", "per_resolution"] = "within_parent",
+    verbose: bool = False,
+) -> dict[tuple[str, str], list[str]]:
+    """Find differentially expressed genes for clusters in two modes."""
+
+    if deg_mode not in ["within_parent", "per_resolution"]:
+        msg = "deg_mode must be 'within_parent' or 'per_resolution'"
+        raise ValueError(msg)
+
+    # Validate resolutions and clustering columns
+    for res in resolutions:
+        col = f"{prefix}{res}"
+        if col not in adata.obs:
+            msg = f"Column {col} not found in adata.obs"
+            raise ValueError(msg)
+
+    top_genes_dict: dict[tuple[str, str], list[str]] = {}
+
+    if deg_mode == "within_parent":
+        top_genes_dict.update(
+            find_within_parent_degs(
+                adata,
+                resolutions,
+                prefix=prefix,
+                n_top_genes=n_top_genes,
+                min_cells=min_cells,
+                rank_genes_groups=rank_genes_groups,
+                verbose=verbose,
+            )
+        )
+    elif deg_mode == "per_resolution":
+        top_genes_dict.update(
+            find_per_resolution_degs(
+                adata,
+                resolutions,
+                prefix=prefix,
+                n_top_genes=n_top_genes,
+                min_cells=min_cells,
+                rank_genes_groups=rank_genes_groups,
+                verbose=verbose,
+            )
+        )
+
+    return top_genes_dict
+
+
+def find_within_parent_degs(
+    adata: AnnData,
+    resolutions: Sequence[float],
+    *,
+    prefix: str,
+    n_top_genes: int,
+    min_cells: int,
+    rank_genes_groups,
+    verbose: bool = False,
+) -> dict[tuple[str, str], list[str]]:
+    top_genes_dict = {}
+
+    for i, res in enumerate(resolutions[:-1]):
+        res_key = f"{prefix}{res}"
+        next_res_key = f"{prefix}{resolutions[i + 1]}"
+        clusters = adata.obs[res_key].cat.categories
+
+        for cluster in clusters:
+            cluster_mask = adata.obs[res_key] == cluster
+            cluster_adata = adata[cluster_mask, :]
+
+            subclusters = cluster_adata.obs[next_res_key].value_counts()
+            valid_subclusters = subclusters[subclusters >= min_cells].index
+
+            if len(valid_subclusters) < 2:
+                if verbose:
+                    print(
+                        f"Skipping res_{res}_C{cluster}: < 2 subclusters with >= {min_cells} cells."
+                    )
+                continue
+
+            subcluster_mask = cluster_adata.obs[next_res_key].isin(valid_subclusters)
+            deg_adata = cluster_adata[subcluster_mask, :]
+
+            try:
+                rank_genes_groups(deg_adata, groupby=next_res_key, method="wilcoxon")
+                for subcluster in valid_subclusters:
+                    names = deg_adata.uns["rank_genes_groups"]["names"][subcluster]
+                    scores = deg_adata.uns["rank_genes_groups"]["scores"][subcluster]
+                    top_genes = [
+                        name
+                        for name, score in zip(names, scores, strict=False)
+                        if score > 0
+                    ][:n_top_genes]
+                    parent_node = f"res_{res}_C{cluster}"
+                    child_node = f"res_{resolutions[i + 1]}_C{subcluster}"
+                    top_genes_dict[(parent_node, child_node)] = top_genes
+                    if verbose:
+                        print(f"{parent_node} -> {child_node}: {top_genes}")
+            except KeyError as e:
+                print(f"Key error when processing {parent_node} -> {child_node}: {e}")
+                continue
+            except TypeError as e:
+                print(
+                    f"Type error with the data when processing {parent_node} -> {child_node}: {e}"
+                )
+                continue
+
+    return top_genes_dict
+
+
+def find_per_resolution_degs(
+    adata: AnnData,
+    resolutions: Sequence[float],
+    *,
+    prefix: str,
+    n_top_genes: int,
+    min_cells: int,
+    rank_genes_groups,
+    verbose: bool = False,
+) -> dict[tuple[str, str], list[str]]:
+    top_genes_dict = {}
+
+    for i, res in enumerate(resolutions[1:], 1):
+        res_key = f"{prefix}{res}"
+        prev_res_key = f"{prefix}{resolutions[i - 1]}"
+        clusters = adata.obs[res_key].cat.categories
+        valid_clusters = [
+            c for c in clusters if (adata.obs[res_key] == c).sum() >= min_cells
+        ]
+
+        if not valid_clusters:
+            if verbose:
+                print(
+                    f"Skipping resolution {res}: no clusters with >= {min_cells} cells."
+                )
+            continue
+
+        deg_adata = adata[adata.obs[res_key].isin(valid_clusters), :]
+        try:
+            rank_genes_groups(
+                deg_adata, groupby=res_key, method="wilcoxon", reference="rest"
+            )
+            for cluster in valid_clusters:
+                names = deg_adata.uns["rank_genes_groups"]["names"][cluster]
+                scores = deg_adata.uns["rank_genes_groups"]["scores"][cluster]
+                top_genes = [
+                    name
+                    for name, score in zip(names, scores, strict=False)
+                    if score > 0
+                ][:n_top_genes]
+                parent_cluster = adata.obs[deg_adata.obs[res_key] == cluster][
+                    prev_res_key
+                ].mode()[0]
+                parent_node = f"res_{resolutions[i - 1]}_C{parent_cluster}"
+                child_node = f"res_{res}_C{cluster}"
+                top_genes_dict[(parent_node, child_node)] = top_genes
+                if verbose:
+                    print(f"{parent_node} -> {child_node}: {top_genes}")
+        except KeyError as e:
+            print(f"Key error when processing {parent_node} -> {child_node}: {e}")
+            continue
+        except TypeError as e:
+            print(
+                f"Type error with the data when processing {parent_node} -> {child_node}: {e}"
+            )
+            continue
+
+    return top_genes_dict
+
+
+def cluster_resolution_finder(
+    adata: AnnData,
+    resolutions: list[float],
+    *,
+    prefix: str = "leiden_res_",
+    method: Literal["wilcoxon"] = "wilcoxon",
+    n_top_genes: int = 3,
+    min_cells: int = 2,
+    deg_mode: Literal["within_parent", "per_resolution"] = "within_parent",
+    flavor: Literal["igraph"] = "igraph",
+    n_iterations: int = 2,
+    inplace: bool = False,
+    verbose: bool = False,
+) -> None:
+    """
+    Find clusters across multiple resolutions and identify cluster-specific genes.
+
+    This function performs Leiden clustering at specified resolutions, identifies
+    differentially expressed genes (DEGs) for clusters, and stores the results in `adata`.
+
+    Params
+    ------
+    adata
+        The annotated data matrix.
+    resolutions
+        List of resolution values for Leiden clustering (e.g., [0.0, 0.2, 0.5]).
+    prefix
+        Prefix for clustering keys in `adata.obs` (e.g., "leiden_res_").
+    method
+        Method for differential expression analysis: only "wilcoxon" is supported.
+    n_top_genes
+        Number of top genes to identify per child cluster.
+    min_cells
+        Minimum number of cells required in a subcluster to include it.
+    deg_mode
+        Mode for DEG analysis: "within_parent" (compare child to parent cluster) or
+        "per_resolution" (compare within each resolution).
+    flavor
+        Flavor of Leiden clustering: only "igraph" is supported.
+    n_iterations
+        Number of iterations for Leiden clustering.
+    inplace
+        If True, modifies `adata` in place. If False, returns a new AnnData object.
+
+    Returns
+    -------
+    adata
+        If `inplace` is False, returns a new AnnData object with clustering results.
+
+    The following annotations are added to `adata`:
+
+    leiden_res_{resolution}
+        Cluster assignments for each resolution in `adata.obs`.
+    cluster_resolution_top_genes
+        Dictionary mapping (parent_node, child_node) pairs to lists of top marker genes,
+        stored in `adata.uns`.
+
+    Notes
+    -----
+    This function requires the `igraph` library for Leiden clustering, which is included in the
+    `leiden` extra. Install it with: ``pip install scanpy[leiden]``.
+
+    Requires `sc.pp.neighbors` to be run on `adata` beforehand.
+
+    Examples
+    --------
+    >>> import scanpy as sc
+    >>> adata = sc.datasets.pbmc68k()
+    >>> sc.pp.neighbors(adata)
+    >>> sc.tl.find_cluster_resolution(adata, resolutions=[0.0, 0.5])
+    >>> sc.pl.cluster_decision_tree(adata, resolutions=[0.0, 0.5])
+    """
+    import io
+
+    from scanpy.tools import leiden
+
+    # Suppress prints if pytest is running
+    if "pytest" in sys.modules:
+        sys.stdout = io.StringIO()
+
+    _validate_cluster_resolution_inputs(adata, resolutions, method, flavor)
+
+    # Run Leiden clustering
+    for resolution in resolutions:
+        res_key = f"{prefix}{resolution}"
+        try:
+            leiden(
+                adata,
+                resolution=resolution,
+                flavor="igraph",
+                n_iterations=n_iterations,
+                key_added=res_key,
+            )
+            if "pytest" not in sys.modules and not hasattr(
+                sys, "_called_from_test"
+            ):  # Suppress print in tests
+                print(f"Completed Leiden clustering for resolution {resolution}")
+        except ValueError as e:
+            msg = f"Leiden clustering failed at resolution {resolution} due to invalid value: {e}"
+            raise RuntimeError(msg) from None
+        except TypeError as e:
+            msg = f"Leiden clustering failed at resolution {resolution} due to incorrect type: {e}"
+            raise RuntimeError(msg) from None
+        except RuntimeError as e:
+            msg = f"Leiden clustering failed at resolution {resolution}: {e}"
+            raise RuntimeError(msg) from None
+
+    if not inplace:
+        adata = adata.copy()
+
+    # Find cluster-specific genes
+    top_genes_dict = find_cluster_specific_genes(
+        adata=adata,
+        resolutions=resolutions,
+        prefix=prefix,
+        method=method,
+        n_top_genes=n_top_genes,
+        min_cells=min_cells,
+        deg_mode=deg_mode,
+        verbose=verbose,
+    )
+
+    # Create DataFrame for clusterDecisionTree
+    try:
+        cluster_data = pd.DataFrame(
+            {f"{prefix}{r}": adata.obs[f"{prefix}{r}"] for r in resolutions}
+        )
+    except KeyError as e:
+        msg = f"Failed to create cluster_data DataFrame: missing column {e}"
+        raise RuntimeError(msg) from None
+    except ValueError as e:
+        msg = f"Failed to create cluster_data DataFrame due to invalid value: {e}"
+        raise RuntimeError(msg) from None
+    except TypeError as e:
+        msg = f"Failed to create cluster_data DataFrame due to incorrect type: {e}"
+        raise RuntimeError(msg) from None
+
+    # Store the results in adata.uns
+    # adata.uns["cluster_resolution_top_genes"] = top_genes_dict
+    adata.uns["cluster_resolution_top_genes"] = _convert_tuple_keys(top_genes_dict)
+    adata.uns["cluster_resolution_cluster_data"] = cluster_data
+
+    return adata
+
+def _validate_cluster_resolution_inputs(
+    adata: AnnData,
+    resolutions: Sequence[float],
+    method: str,
+    flavor: str,
+) -> None:
+    """Validate inputs for the find_cluster_resolution function."""
+    if not resolutions:
+        msg = "resolutions list cannot be empty"
+        raise ValueError(msg)
+    if not all(isinstance(r, int | float) and r >= 0 for r in resolutions):
+        msg = "All resolutions must be non-negative numbers"
+        raise ValueError(msg)
+    if method != "wilcoxon":
+        msg = "Only method='wilcoxon' is supported"
+        raise ValueError(msg)
+    if flavor != "igraph":
+        msg = "Only flavor='igraph' is supported"
+        raise ValueError(msg)
+    if "neighbors" not in adata.uns:
+        msg = "adata must have precomputed neighbors (run sc.pp.neighbors first)."
+        raise ValueError(msg)
+
+# Recursively convert tuple keys in .uns to strings
+def _convert_tuple_keys(d, delimiter="_"):
+    if isinstance(d, dict):
+        new_dict = {}
+        for k, v in d.items():
+            if isinstance(k, tuple):
+                k = delimiter.join(k)
+            new_dict[k] = _convert_tuple_keys(v, delimiter=delimiter)
+        return new_dict
+    elif isinstance(d, list):
+        return [_convert_tuple_keys(i, delimiter=delimiter) for i in d]
+    else:
+        return d
+
+# Recursively recover tuple keys in .uns from strings
+def _recover_tuple_keys(d, delimiter="_"):
+    if isinstance(d, dict):
+        new_dict = {}
+        for k, v in d.items():
+            if isinstance(k, str) and delimiter in k:
+                k = tuple(k.split(delimiter))
+            new_dict[k] = _recover_tuple_keys(v, delimiter=delimiter)
+        return new_dict
+    elif isinstance(d, list):
+        return [_recover_tuple_keys(i, delimiter=delimiter) for i in d]
+    else:
+        return d

resolutiontree-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: resolutiontree
+Version: 0.1.0
+Summary: Systematic exploration of clustering resolutions in single-cell analysis
+Home-page: https://github.com/joe-jhou2/resolutiontree
+Author: Joe Hou
+Author-email: Joe Hou <joseph.houjue@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/joe-jhou2/resolutiontree
+Project-URL: Documentation, https://resolutiontree.readthedocs.io/
+Project-URL: Repository, https://github.com/joe-jhou2/resolutiontree
+Project-URL: Bug Tracker, https://github.com/joe-jhou2/resolutiontree/issues
+Keywords: single-cell,clustering,resolution,scanpy,leiden,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python

resolutiontree-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+resolutiontree/__init__.py,sha256=Jjk3APrAMIyWHuchBXAH1dCN7gETacl81MacpkmwZ-0,305
+resolutiontree/core.py,sha256=zrMzqvzyJwSS6kEfSIE1uRe3Spdufo1jkrvDYzb35h8,51597
+resolutiontree/utils.py,sha256=pEzAghm0JFsuDyb13Fm8ncjBg0QhRy6wnuxZgDBhDNk,13339
+resolutiontree-0.1.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+resolutiontree-0.1.0.dist-info/METADATA,sha256=v3O-wkDVaVsqHUk4Bl3h2uNGpieCkCLG3B5kyGznGsM,1248
+resolutiontree-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+resolutiontree-0.1.0.dist-info/top_level.txt,sha256=E0usvI1QBYLUw4m1v4wY2UsZ6wRy-YD_RJxwzu-kO2U,15
+resolutiontree-0.1.0.dist-info/RECORD,,

resolutiontree-0.1.0.dist-info/WHEEL

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

resolutiontree-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+resolutiontree