Source code for dynamo.plot.connectivity

"""
# code are largely adapted from https://github.com/lmcinnes/umap/blob/7e051d8f3c4adca90ca81eb45f6a9d1372c076cf/umap/plot.py
The code base will be extended extensively to consider the following cases:
    1. nneighbors: kNN graph constructed from umap/scKDTree/annoy, etc
    2. mutual kNN shared between spliced or unspliced layer
    3. principal graph that learnt from DDRTree, L1graph or other principal graph algorithms
    4. regulatory network learnt from Scribe
    5. spatial kNN graph
    6. others
"""

import scipy
import pandas as pd
import numpy as np
from warnings import warn
from typing import Optional, Union
from matplotlib.axes import Axes
from anndata import AnnData
from matplotlib.figure import Figure

from ..tools.utils import update_dict
from .utils import (
    _select_font_color,
    _get_extent,
    _embed_datashader_in_an_axis,
    _datashade_points,
    save_fig,
)
from .utils import is_list_of_lists  # is_gene_name
from ..configuration import _themes
from ..docrep import DocstringProcessor

docstrings = DocstringProcessor()


def _plt_connectivity(coord: dict, connectivity: scipy.sparse.csr_matrix):
    """Plot connectivity graph via networkx and matplotlib.

    Parameters
    ----------
        coord: `dict`
            A dictionary where the keys are the graph node names and values are the corresponding coordinates of the node.
        connectivity: `scipy.sparse.csr_matrix`
            A csr sparse matrix of the cell connectivities.

    Returns
    -------
        Nothing but a connectivity graph plot built upon networkx and matplotlib.
    """

    import networkx as nx
    import matplotlib.pyplot as plt

    if_symmetric = (abs(connectivity - connectivity.T) > 1e-10).nnz == 0

    G = (
        nx.from_scipy_sparse_matrix(connectivity, create_using=nx.Graph())
        if if_symmetric
        else nx.from_scipy_sparse_matrix(connectivity, create_using=nx.DiGraph())
    )
    W = []
    for n, nbrs in G.adj.items():
        for nbr, eattr in nbrs.items():
            W.append(eattr["weight"])

    options = {
        "width": 30,
        "arrowstyle": "-|>",
        "arrowsize": 10,
    }
    edge_color = "gray"
    plt.figure(figsize=[6, 4])

    nx.draw(
        G,
        pos=coord,
        with_labels=False,
        node_color="skyblue",
        node_size=1,
        edge_color=edge_color,
        width=W / np.max(W) * 1,
        edge_cmap=plt.cm.Blues,
        options=options,
    )

    plt.show()


@docstrings.get_sectionsf("con_base")
def connectivity_base(
    x: int,
    y: int,
    edge_df: pd.DataFrame,
    highlights: Optional[list] = None,
    edge_bundling: Optional[str] = None,
    edge_cmap: str = "gray_r",
    show_points: bool = True,
    labels: Optional[list] = None,
    values: Optional[list] = None,
    theme: Optional[str] = None,
    cmap: str = "Blues",
    color_key: Union[dict, list, None] = None,
    color_key_cmap: str = "Spectral",
    background: str = "black",
    figsize: tuple = (7, 5),
    ax: Optional[Axes] = None,
    sort: str = "raw",
    save_show_or_return: str = "return",
    save_kwargs: dict = {},
) -> Union[None, Axes]:
    """Plot connectivity relationships of the underlying UMAP
    simplicial set data structure. Internally UMAP will make
    use of what can be viewed as a weighted graph. This graph
    can be plotted using the layout provided by UMAP as a
    potential diagnostic view of the embedding. Currently this only works
    for 2D embeddings. While there are many optional parameters
    to further control and tailor the plotting, you need only
    pass in the trained/fit umap model to get results. This plot
    utility will attempt to do the hard work of avoiding
    overplotting issues and provide options for plotting the
    points as well as using edge bundling for graph visualization.

    Parameters
    ----------
        x: `int`
            The first component of the embedding.
        y: `int`
            The second component of the embedding.
        edge_df `pd.DataFrame`
            The dataframe denotes the graph edge pairs. The three columns
            include 'source', 'target' and 'weight'.
        highlights: `list`, `list of list` or None (default: `None`)
            The list that cells will be restricted to.
        edge_bundling: string or None (optional, default None)
            The edge bundling method to use. Currently supported
            are None or 'hammer'. See the datashader docs
            on graph visualization for more details.
        edge_cmap: string (default 'gray_r')
            The name of a matplotlib colormap to use for shading/
            coloring the edges of the connectivity graph. Note that
            the ``theme``, if specified, will override this.
        show_points: bool (optional False)
            Whether to display the points over top of the edge
            connectivity. Further options allow for coloring/
            shading the points accordingly.
        labels: array, shape (n_samples,) (optional, default None)
            An array of labels (assumed integer or categorical),
            one for each data sample.
            This will be used for coloring the points in
            the plot according to their label. Note that
            this option is mutually exclusive to the ``values``
            option.
        values: array, shape (n_samples,) (optional, default None)
            An array of values (assumed float or continuous),
            one for each sample.
            This will be used for coloring the points in
            the plot according to a colorscale associated
            to the total range of values. Note that this
            option is mutually exclusive to the ``labels``
            option.
        theme: string (optional, default None)
            A color theme to use for plotting. A small set of
            predefined themes are provided which have relatively
            good aesthetics. Available themes are:
               * 'blue'
               * 'red'
               * 'green'
               * 'inferno'
               * 'fire'
               * 'viridis'
               * 'darkblue'
               * 'darkred'
               * 'darkgreen'
        cmap: string (optional, default 'Blues')
            The name of a matplotlib colormap to use for coloring
            or shading points. If no labels or values are passed
            this will be used for shading points according to
            density (largely only of relevance for very large
            datasets). If values are passed this will be used for
            shading according the value. Note that if theme
            is passed then this value will be overridden by the
            corresponding option of the theme.
        color_key: dict or array, shape (n_categories) (optional, default None)
            A way to assign colors to categoricals. This can either be
            an explicit dict mapping labels to colors (as strings of form
            '#RRGGBB'), or an array like object providing one color for
            each distinct category being provided in ``labels``. Either
            way this mapping will be used to color points according to
            the label. Note that if theme
            is passed then this value will be overridden by the
            corresponding option of the theme.
        color_key_cmap: string (optional, default 'Spectral')
            The name of a matplotlib colormap to use for categorical coloring.
            If an explicit ``color_key`` is not given a color mapping for
            categories can be generated from the label list and selecting
            a matching list of colors from the given colormap. Note
            that if theme
            is passed then this value will be overridden by the
            corresponding option of the theme.
        background: string (optional, default 'white)
            The color of the background. Usually this will be either
            'white' or 'black', but any color name will work. Ideally
            one wants to match this appropriately to the colors being
            used for points etc. This is one of the things that themes
            handle for you. Note that if theme
            is passed then this value will be overridden by the
            corresponding option of the theme.
        width: int (optional, default 800)
            The desired width of the plot in pixels.
        height: int (optional, default 800)
            The desired height of the plot in pixels
        sort: `str` (optional, default `raw`)
            The method to reorder data so that high values points will be on top of background points. Can be one of
            {'raw', 'abs'}, i.e. sorted by raw data or sort by absolute values.
        save_show_or_return: {'show', 'save', 'return'} (default: `return`)
            Whether to save, show or return the figure.
        save_kwargs: `dict` (default: `{}`)
            A dictionary that will passed to the save_fig function. By default it is an empty dictionary and the save_fig function
            will use the {"path": None, "prefix": 'connectivity_base', "dpi": None, "ext": 'pdf', "transparent": True, "close":
            True, "verbose": True} as its parameters. Otherwise you can provide a dictionary that properly modify those keys
            according to your needs.

    Returns
    -------
    result:
        Either return None or a matplotlib axis with the relevant plot displayed based on arguments.
        If you are using a notbooks and have ``%matplotlib inline`` set
        then this will simply display inline.
    """

    import matplotlib.pyplot as plt
    import datashader as ds
    import datashader.transfer_functions as tf
    import datashader.bundling as bd

    dpi = plt.rcParams["figure.dpi"]

    if theme is not None:
        cmap = _themes[theme]["cmap"]
        color_key_cmap = _themes[theme]["color_key_cmap"]
        edge_cmap = _themes[theme]["edge_cmap"]
        background = _themes[theme]["background"]

    points = np.array([x, y]).T
    point_df = pd.DataFrame(points, columns=("x", "y"))

    point_size = 500.0 / np.sqrt(points.shape[0])
    if point_size > 1:
        px_size = int(np.round(point_size))
    else:
        px_size = 1

    if show_points:
        edge_how = "log"
    else:
        edge_how = "eq_hist"

    extent = _get_extent(points)
    canvas = ds.Canvas(
        plot_width=int(figsize[0] * dpi),
        plot_height=int(figsize[1] * dpi),
        x_range=(extent[0], extent[1]),
        y_range=(extent[2], extent[3]),
    )

    if edge_bundling is None:
        edges = bd.directly_connect_edges(point_df, edge_df, weight="weight")
    elif edge_bundling == "hammer":
        warn("Hammer edge bundling is expensive for large graphs!\n" "This may take a long time to compute!")
        edges = bd.hammer_bundle(point_df, edge_df, weight="weight")
    else:
        raise ValueError("{} is not a recognised bundling method".format(edge_bundling))

    edge_img = tf.shade(
        canvas.line(edges, "x", "y", agg=ds.sum("weight")),
        cmap=plt.get_cmap(edge_cmap),
        how=edge_how,
    )
    edge_img = tf.set_background(edge_img, background)

    if show_points:
        point_img = _datashade_points(
            points,
            None,
            labels,
            values,
            highlights,
            cmap,
            color_key,
            color_key_cmap,
            None,
            figsize[0] * dpi,
            figsize[1] * dpi,
            True,
            sort=sort,
        )
        if px_size > 1:
            point_img = tf.dynspread(point_img, threshold=0.5, max_px=px_size)
        result = tf.stack(edge_img, point_img, how="over")
    else:
        result = edge_img

    if ax is None:
        fig = plt.figure(figsize=figsize)
        ax = fig.add_subplot(111)

    _embed_datashader_in_an_axis(result, ax)

    ax.set(xticks=[], yticks=[])

    if save_show_or_return == "save":
        s_kwargs = {
            "path": None,
            "prefix": "connectivity_base",
            "dpi": None,
            "ext": "pdf",
            "transparent": True,
            "close": True,
            "verbose": True,
        }
        s_kwargs = update_dict(s_kwargs, save_kwargs)

        save_fig(**s_kwargs)
    elif save_show_or_return == "show":
        plt.tight_layout()
        plt.show()
    elif save_show_or_return == "return":
        return ax


docstrings.delete_params("con_base.parameters", "edge_df", "save_show_or_return", "save_kwargs")


[docs]@docstrings.with_indent(4) def nneighbors( adata: AnnData, x: int = 0, y: int = 1, color: str = "ntr", basis: str = "umap", layer: str = "X", highlights: Union[list] = None, ncols: int = 1, edge_bundling: Optional[str] = None, edge_cmap: str = "gray_r", show_points: bool = True, labels: Optional[list] = None, values: Optional[list] = None, theme: Optional[str] = None, cmap: str = "Blues", color_key: Optional[Union[dict, list]] = None, color_key_cmap: str = "Spectral", background: str = "black", figsize: tuple = (6, 4), ax: Optional[Axes] = None, save_show_or_return: str = "return", save_kwargs: dict = {}, ) -> Union[None, Figure]: """Plot nearest neighbor graph of cells used to embed data into low dimension space. Parameters ---------- adata: :class:`~anndata.AnnData` an Annodata object that include the umap embedding and simplicial graph. x: `int` The first component of the embedding. y: `int` The second component of the embedding. color: `str` or list of `str` or None (default: 'ntr') Gene name(s) or cell annotation column(s) basis: `str` or list of `str` (default: `X`) Which low dimensional embedding will be used to visualize the cell. layer: `str` or list of `str` (default: `X`) The layers of data to represent the gene expression level. highlights: `list`, `list of list` or None (default: `None`) The list that cells will be restricted to. save_show_or_return: {'show', 'save', 'return'} (default: `show`) Whether to save, show or return the figure. save_kwargs: `dict` (default: `{}`) A dictionary that will passed to the save_fig function. By default it is an empty dictionary and the save_fig function will use the {"path": None, "prefix": 'nneighbors', "dpi": None, "ext": 'pdf', "transparent": True, "close": True, "verbose": True} as its parameters. Otherwise you can provide a dictionary that properly modify those keys according to your needs. %(con_base.parameters.no_edge_df|save_show_or_return|save_kwargs)s Returns ------- Nothing but plot the nearest neighbor graph. """ import matplotlib.pyplot as plt import seaborn as sns if type(x) is not int or type(y) is not int: raise Exception( "x, y have to be integers (components in the a particular embedding {}) for nneighbor " "function".format(basis) ) n_c, n_l, n_b = ( 0 if color is None else len(color), 0 if layer is None else len(layer), 0 if basis is None else len(basis), ) # c_is_gene_name = [is_gene_name(adata, i) for i in list(color)] if n_c > 0 else [False] * n_c # cnt, gene_num = 0, sum(c_is_gene_name) coo_graph = adata.uns["neighbors"]["connectivities"].tocoo() edge_df = pd.DataFrame( np.vstack([coo_graph.row, coo_graph.col, coo_graph.data]).T, columns=("source", "target", "weight"), ) edge_df["source"] = edge_df.source.astype(np.int32) edge_df["target"] = edge_df.target.astype(np.int32) total_panels, ncols = n_c * n_l * n_b, min(n_c, ncols) nrow, ncol = int(np.ceil(total_panels / ncols)), ncols if figsize is None: figsize = plt.rcParams["figsize"] font_color = _select_font_color(background) if background == "black": # https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/mpl-data/stylelib/dark_background.mplstyle sns.set( rc={ "axes.facecolor": background, "axes.edgecolor": background, "figure.facecolor": background, "figure.edgecolor": background, "axes.grid": False, "ytick.color": font_color, "xtick.color": font_color, "axes.labelcolor": font_color, "axes.edgecolor": font_color, "savefig.facecolor": "k", "savefig.edgecolor": "k", "grid.color": font_color, "text.color": font_color, "lines.color": font_color, "patch.edgecolor": font_color, "figure.edgecolor": font_color, } ) else: sns.set( rc={ "axes.facecolor": background, "figure.facecolor": background, "axes.grid": False, } ) if total_panels > 1: g = plt.figure(None, (figsize[0] * ncol, figsize[1] * nrow), facecolor=background) gs = plt.GridSpec(nrow, ncol, wspace=0.12) i = 0 for cur_b in basis: for cur_l in layer: prefix = cur_l + "_" if prefix + cur_b in adata.obsm.keys(): x_, y_ = ( adata.obsm[prefix + cur_b][:, int(x)], adata.obsm[prefix + cur_b][:, int(y)], ) else: continue for cur_c in color: _color = adata.obs_vector(cur_c, layer=cur_l) is_not_continous = _color.dtype.name == "category" if is_not_continous: labels = _color if theme is None: theme = "glasbey_dark" else: values = _color if theme is None: theme = "inferno" if cur_l != "velocity" else "div_blue_red" if total_panels > 1: ax = plt.subplot(gs[i]) i += 1 # if highligts is a list of lists - each list is relate to each color element if is_list_of_lists(highlights): _highlights = highlights[color.index(cur_c)] _highlights = _highlights if all([i in _color for i in _highlights]) else None else: _highlights = highlights if all([i in _color for i in highlights]) else None connectivity_base( x_, y_, edge_df, edge_bundling, edge_cmap, show_points, labels, values, _highlights, theme, cmap, color_key, color_key_cmap, background, figsize, ax, ) ax.set_xlabel( cur_b + "_1", ) ax.set_ylabel(cur_b + "_2") ax.set_title(cur_c) if save_show_or_return == "save": s_kwargs = { "path": None, "prefix": "nneighbors", "dpi": None, "ext": "pdf", "transparent": True, "close": True, "verbose": True, } s_kwargs = update_dict(s_kwargs, save_kwargs) save_fig(**s_kwargs) elif save_show_or_return == "show": plt.tight_layout() plt.show() elif save_show_or_return == "return": return g
def pgraph(): """Plot principal graph of cells that learnt from graph embedding algorithms. return: """ pass def cgroups(): """Plot transition matrix graph of groups of cells that produced from clustering or other grouping procedures. :return: """ pass def causal_net(): """Plot causal regulatory networks of genes learnt with Scribe (https://github.com/aristoteleo/Scribe-py). :return: """ pass