pyclustree
==========

.. py:module:: pyclustree


Attributes
----------

.. autoapisummary::

   pyclustree.pyclustree


Functions
---------

.. autoapisummary::

   pyclustree.clustree


Package Contents
----------------

.. py:function:: clustree(adata, cluster_keys, title = None, scatter_reference = None, node_colormap = 'tab20', node_color_gene = None, node_color_gene_use_raw = True, node_color_gene_transformer = None, node_size_range = (100, 1000), edge_width_range = (0.5, 5.0), edge_weight_threshold = 0.0, x_spacing = 2.5, y_spacing = 1.25, order_clusters = True, show_colorbar = False, show_fraction = False, show_cluster_keys = True, graph_plot_kwargs = None)

   Create a hierarchical clustering tree visualization to compare different clustering resolutions.

   .. code-block:: python

       import scanpy as sc
       from pyclustree import clustree

       adata = sc.datasets.pbmc3k_processed()

       # Run leiden clustering for different resolutions
       for resolution in [0.2, 0.4, 0.6, 0.8, 1.0]:
           sc.tl.leiden(
               adata,
               resolution=resolution,
               flavor="igraph",
               n_iterations=2,
               key_added=f"leiden_{str(resolution).replace('.', '_')}",
           )

       # Create a clustree visualization
       fig = clustree(
           adata,
           [f"leiden_{str(resolution).replace('.', '_')}" for resolution in [0.2, 0.4, 0.6, 0.8, 1.0]],
       )

   :param adata: The AnnData object from `scanpy` or any other library.
   :type adata: AnnData
   :param cluster_keys: The list of cluster keys to visualize, in hierarchical order. Keys should be present
                        in `adata.obs`.
   :type cluster_keys: list[str]
   :param title: The title of the plot. Defaults to None.
   :type title: str, optional
   :param scatter_reference: The key in `adata.obsm` to use as a reference for the scatter plot. If None,
                             the nodes will be placed in a hierarchical tree. Defaults to None.
   :type scatter_reference: str, optional
   :param node_colormap: The colormap to use for coloring the nodes. If a list is
                         provided, the first colormap will be used for the first clustering, the second colormap for the second
                         clustering, and so on. For each clustering, the colors will be scaled based on the number of clusters.
                         Defaults to "tab20".
   :type node_colormap: Union[Colormap, str], optional
   :param node_color_gene: The gene to use for coloring the nodes. If provided, node colors will be based
                           on the expression of this gene. If None, node colors will be based on the cluster key/level.
                           Defaults to None.
   :type node_color_gene: str, optional
   :param node_color_gene_use_raw: Whether to use the raw data for the gene expression if available.
                                   Defaults to True.
   :type node_color_gene_use_raw: bool, optional
   :param node_color_gene_transformer: A function to transform the gene expression values
                                       to a single value for coloring the nodes. If None, the mean expression of the gene will be used.
                                       Defaults to None.
   :type node_color_gene_transformer: Optional[callable], optional
   :param node_size_range: The range of node sizes to use. Defaults to (100, 1000).
   :type node_size_range: tuple[float, float], optional
   :param edge_width_range: The range of edge widths to use. Defaults to (0.5, 5.0).
   :type edge_width_range: tuple[float, float], optional
   :param edge_weight_threshold: The threshold for edge weights to include in the visualization.
                                 Defaults to 0.0.
   :type edge_weight_threshold: float, optional
   :param x_spacing: The horizontal spacing between nodes. Defaults to 2.5.
   :type x_spacing: float, optional
   :param y_spacing: The vertical spacing between nodes. Defaults to 1.25.
   :type y_spacing: float, optional
   :param order_clusters: Whether to order the clusters based on the transition matrix. Defaults to True.
   :type order_clusters: bool, optional
   :param show_colorbar: Whether to show the colorbar. Defaults to False.
   :type show_colorbar: bool, optional
   :param show_fraction: Whether to show the fraction of cells from the parent cluster that transitioned
                         to the child cluster. Defaults to False.
   :type show_fraction: bool, optional
   :param show_cluster_keys: Whether to show the cluster keys on the left side of the plot.
                             Defaults to True.
   :type show_cluster_keys: bool, optional
   :param graph_plot_kwargs: Additional keyword arguments to pass to `nx.draw`. Will override
                             the default arguments. Defaults to None.
   :type graph_plot_kwargs: Optional[dict], optional

   :returns: The matplotlib figure object of the clustree visualization.
   :rtype: plt.Figure


.. py:data:: pyclustree