pycea.pl.branches

Contents

pycea.pl.branches#

pycea.pl.branches(tdata, polar=False, extend_branches=False, angled_branches=False, angle_range=(0, 360), color='black', linewidth=0.5, depth_key=None, legend=None, tree=None, cmap='viridis', palette=None, vmax=None, vmin=None, na_color='lightgrey', na_linewidth=1, linewidths=(0.1, 2), slot=None, ax=None, legend_kwargs=None, **kwargs)#

Plot the branches of a tree.

Plots the branches of one or more trees stored in tdata.obst as a matplotlib.collections.LineCollection. Branch appearance (color and linewidth) can be fixed scalars or set based on edge attributes (continuous or categorical). Coloring of continuous variables is based on a colormap (cmap), while categorical variables can be colored using a custom palette or a default categorical color set. Polar coordinates are used when polar is True.

Parameters:

  • tdata (TreeData) – The treedata.TreeData object.

  • 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. Use a smaller range (e.g. (0, 180)) to generate a “pie slice” shaped tree. Only used when polar=True.

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

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

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

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

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

  • na_linewidth (float (default: 1)) – The linewidth to use for edges with missing data.

  • slot (Optional[Literal['obst', 'obsp']] (default: None)) – Slot in TreeData object containing color and linewidth attributes. If None, searches obst when alignment='leaves', searches obst and obsp otherwise.

  • 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.collections.LineCollection.

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 tree branches:

>>> tdata = py.datasets.packer19()
>>> py.pl.branches(tdata, depth_key="time")

Plot tree branches in polar coordinates, colored by clade:

>>> py.pl.branches(tdata, depth_key="time", polar=True, color="clade")
Contents