pycea.pl.tree

Contents

pycea.pl.tree#

pycea.pl.tree(tdata, keys=None, nodes=None, polar=False, extend_branches=False, angled_branches=False, angle_range=(0, 360), depth_key=None, branch_color='black', branch_linewidth=0.5, node_color='black', node_style='o', node_size=10, annotation_width=0.05, tree=None, legend=None, cmap='viridis', palette=None, vmax=None, vmin=None, share_cmap=False, ax=None, legend_kwargs=None)#

Plot a tree with branches, nodes, and annotations.

This function combines pycea.pl.branches(), pycea.pl.nodes(), and pycea.pl.annotation() to enable plotting a complete tree with branches, nodes, and leaf annotations in a single call. Each component (branches, nodes, annotations) can be customized independently using the respective parameters.

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() annotations.

  • nodes (str | Sequence[str] | None (default: None)) – Either “all”, “leaves”, “internal”, or a list of nodes to plot. Defaults to “internal” if node color, style, or size is set.

  • polar (bool (default: False)) – Whether to plot the tree in polar coordinates.

  • extend_branches (bool (default: False)) – Whether to extend branches so the tips are at the same depth.

  • angled_branches (bool (default: False)) – Whether to plot branches at an angle.

  • angle_range (tuple[float, float] (default: (0, 360))) – A (start, end) tuple in degrees specifying the arc span for polar plots. Defaults to (0, 360) for a full circle. Only used when polar=True.

  • depth_key (str | None (default: None)) – The key for the depth of the nodes.

  • branch_color (str (default: 'black')) – Either a color name, or a key for an attribute of the edges to color by.

  • branch_linewidth (float | str (default: 0.5)) – Either an numeric width, or a key for an attribute of the edges to set the linewidth.

  • node_color (str (default: 'black')) – Either a color name, or a key for an attribute of the nodes to color by.

  • node_style (str (default: 'o')) – Either a marker name, or a key for an attribute of the nodes to set the marker.

  • node_size (str | float (default: 10)) – Either an numeric size, or a key for an attribute of the nodes to set the size.

  • legend (bool | Mapping[str, bool] | None (default: None)) – Whether to show a legend. By default, a legend is added if there are <= 20 distinct categories. Can also be a dictionary with keys “branch”, “node”, and “annotation” to control the legend for each component separately.

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

  • 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 (default: 'viridis')) – 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.

  • 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().

Return type:

Axes

Returns:

ax - The axes that the plot was drawn on.

Notes

  • If ax is provided the coordinate system must match the polar setting.

  • Continuous color attributes use cmap with vmin/vmax normalization.

Examples

Plot a tree with nodes and leaves colored by “elt-2” expression:

>>> tdata = py.datasets.packer19()
>>> py.pl.tree(tdata, nodes="all", node_color="elt-2", keys="elt-2", depth_key="time")
Contents