pycea.tl.clades

Contents

pycea.tl.clades#

pycea.tl.clades(tdata, depth=None, depth_key='depth', clades=None, key_added='clade', update=False, dtype=<class 'str'>, tree=None, copy=False)#
Overloads:

  • tdata (td.TreeData), depth (float | None), depth_key (str), clades (Mapping[Any, Any] | None), key_added (str), update (bool), dtype (type | str), tree (str | Sequence[str] | None), copy (Literal[True, False]) → pd.DataFrame

  • tdata (td.TreeData), depth (float | None), depth_key (str), clades (Mapping[Any, Any] | None), key_added (str), update (bool), dtype (type | str), tree (str | Sequence[str] | None), copy (Literal[True, False]) → None

Marks clades in a tree.

A clade is defined by a ancestral node; all nodes and edges in the ancestral node’s descendant subtree inherit the same clade label. You can specify clades in two ways:

  • Depth-based:

    Given a depth threshold, all nodes that are extant at that depth are considered ancestral nodes. Each ancestral node and its descendants are assigned a unique clade label.

  • Explicit mapping:

    When clades, a dictionary mapping nodes to clade labels is provided, those nodes are considered ancestral nodes. Each such node and its descendants are assigned the corresponding clade label.

Parameters:

  • tdata (TreeData) – The TreeData object.

  • depth (float | None (default: None)) – Depth to cut tree at. Must be specified if clades is None.

  • depth_key (str (default: 'depth')) – Attribute of tdata.obst[tree].nodes where depth is stored.

  • clades (Mapping[Any, Any] | None (default: None)) – A dictionary mapping nodes to clades.

  • key_added (str (default: 'clade')) – Key to store clades in.

  • update (bool (default: False)) – If True, updates existing clades instead of overwriting.

  • dtype (type | str (default: <class 'str'>)) – Data type of clade names. One of str, int, or float.

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

  • copy (Literal[True, False] (default: False)) – If True, returns a DataFrame with clades.

Returns:

Returns None if copy=False, else returns a DataFrame.

Sets the following fields:

  • tdata.obs[key_added]Series (dtype Object)

    • Clade assignment for each observation.

  • tdata.obst[tree].nodes[key_added]Object

    • Clade assignment for each node.

Modifies the following fields:

  • tdata.uns[f"{key_added}_colors"]List

    • Removed if its length does not match the number of unique clades.

Examples

Mark clades at specified depth

>>> tdata = pycea.datasets.koblan25()
>>> pycea.tl.clades(tdata, depth=4, depth_key="time")

Highlight descendants of ‘node6’

>>> pycea.tl.clades(tdata, clades={"node6": "node6_descendants"}, key_added="highlight")
Contents