pycea.pl.annotation

Contents

pycea.pl.annotation#

pycea.pl.annotation(tdata, keys=None, width=0.05, gap=0.03, label=True, layer=None, border_width=0, legend=None, tree=None, cmap=None, palette=None, vmax=None, vmin=None, share_cmap=False, na_color='white', slot=None, ax=None, legend_kwargs=None, **kwargs)#

Plot leaf annotations for a tree.

Plots one or more leaf annotations (small heatmap-like bars) next to the tree’s leaves, preserving the leaf order/layout used by pycea.pl.branches(). Each key can be continuous (colored via a colormap) or categorical (colored via a palette). Multiple keys are stacked horizontally (or radially if your tree plot is polar).

Parameters:

  • tdata (TreeData) – The TreeData object.

  • keys (str | Sequence[str] | None (default: None)) – One or more obs.keys(), var_names, obsm.keys(), or obsp.keys() to plot.

  • width (float (default: 0.05)) – The width of the annotation bar relative to the tree.

  • gap (float (default: 0.03)) – The gap between the annotation bar and the tree relative to the tree.

  • label (bool | str | Sequence[str] | None (default: True)) – Annotation labels. If True, the keys are used as labels. If a string or a sequence of strings, the strings are used as labels.

  • layer (str | None (default: None)) – Name of the TreeData object layer to use. If None, tdata.X is plotted.

  • border_width (float (default: 0)) – The width of the border around the annotation bar.

  • legend (bool | None (default: None)) – Whether to add a legend to the plot. By default, a legend is added if there are <= 20 distinct categories.

  • tree (str | Sequence[str] | None (default: None)) – The obst key or keys of the trees to plot. If None, all trees are plotted.

  • cmap (str | Colormap | None (default: None)) – Color map to use for continous variables. Can be a name or a Colormap instance (e.g. "magma”, "viridis" or mpl.cm.cividis), see get_cmap(). If None, the value of mpl.rcParams["image.cmap"] is used. The default cmap can be set using set_figure_params().

  • palette (Cycler | ListedColormap | Sequence[str] | Mapping[Any, str] | None (default: None)) – Colors to use for plotting categorical annotation groups. The palette can be a valid ListedColormap name ('Set2', 'tab20', …), a Cycler object, a dict mapping categories to colors, or a sequence of colors. Colors must be valid to matplotlib. (see is_color_like()). If None, mpl.rcParams["axes.prop_cycle"] is used unless the categorical variable already has colors stored in tdata.uns["{var}_colors"]. If provided, values of tdata.uns["{var}_colors"] will be set.

  • vmax (float | str | None (default: None)) – The maximum value for the colormap. Use 'p99' to set the maximum to the 99th percentile of the data.

  • vmin (float | str | None (default: None)) – The minimum value for the colormap. Use 'p1' to set the minimum to the 1st percentile of the data.

  • share_cmap (bool (default: False)) – If True, all numeric keys will share the same colormap.

  • na_color (str (default: 'white')) – The color to use for annotations with missing data.

  • slot (Optional[Literal['obs', 'obsm', 'obsp', 'X']] (default: None)) – Slot in TreeData object containing keys. If None, searches obs, X, obsm, and obsp in that order.

  • ax (Axes | None (default: None)) – A matplotlib axes object. If None, a new figure and axes will be created.

  • legend_kwargs (dict[str, Any] | None (default: None)) – Additional keyword arguments passed to matplotlib.pyplot.legend().

  • kwargs – Additional keyword arguments passed to matplotlib.pyplot.pcolormesh().

Return type:

Axes

Returns:

ax - The axes that the plot was drawn on.

Notes

Examples

Plot leaf annotations for “elt-2” and “pal-1” expression:

>>> tdata = py.datasets.packer19(tree = "observed")
>>> py.pl.branches(tdata, depth_key="time")
>>> py.pl.annotation(tdata, keys=["elt-2", "pal-1"])

Plot leaf annotation for spatial distance between leaves:

>>> py.tl.distance(tdata, key = "spatial")
>>> py.pl.branches(tdata, depth_key="time")
>>> py.pl.annotation(tdata, keys="spatial_distances", cmap="magma")
Contents