pycea.tl.n_extant

Contents

pycea.tl.n_extant#

pycea.tl.n_extant(tdata, depth_key='depth', groupby=None, bins=20, tree=None, key_added='n_extant', extend_branches=False, dropna=False, slot='obst', copy=False)#
Overloads:

  • tdata (td.TreeData), depth_key (str), groupby (Sequence[str] | str | None), bins (int | Sequence[float]), tree (str | Sequence[str] | None), key_added (str), extend_branches (bool), dropna (bool), slot (Literal[‘obst’, ‘obs’]), copy (Literal[True, False]) → pd.DataFrame

  • tdata (td.TreeData), depth_key (str), groupby (Sequence[str] | str | None), bins (int | Sequence[float]), tree (str | Sequence[str] | None), key_added (str), extend_branches (bool), dropna (bool), slot (Literal[‘obst’, ‘obs’]), copy (Literal[True, False]) → None

Counts extant branches over time.

This function computes the number of lineages that are alive (extant) at each depth bin. Lineages are counted by sweeping along each edge (parent → child): a lineage is present from the parent’s depth (inclusive) up to the child’s depth (exclusive), unless extend_branches=True and the child is a leaf, in which case the lineage extends to the maximum depth bin.

Grouping is supported by one or more node attributes (groupby); counts are computed separately per unique group combination.

Parameters:

  • tdata (TreeData) – TreeData object.

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

  • groupby (Sequence[str] | str | None (default: None)) – Attribute of tdata.obst[tree].nodes storing grouping variable(s). If None, counts across all branches.

  • bins (int | Sequence[float] (default: 20)) – Number of histogram bins or explicit bin edges.

  • tree (str | Sequence[str] | None (default: None)) – The obst key or keys of trees to use. If None, number of extant branches is computed for all trees in obst.

  • key_added (str (default: 'n_extant')) – Key under which to store results in tdata.uns.

  • extend_branches (bool (default: False)) – If True, leaf branches are extended to the maximum depth of the tree.

  • dropna (bool (default: False)) – If True, drop rows with NaN values in grouping variables.

  • slot (Literal['obst', 'obs'] (default: 'obst')) – Slot in TreeData object containing the depth and grouping keys.

  • copy (Literal[True, False] (default: False)) – If True, return a DataFrame with extant counts.

Returns:

Returns None if copy=False, else returns a DataFrame <pandas.DataFrame>`.

Sets the following fields:

  • tdata.uns[key_added]DataFrame with columns

    depth_key, n_extant, grouping variables, and tree.

Examples

Calculate number cells in each clade over time:

>>> tdata = py.datasets.koblan25()
>>> py.tl.n_extant(tdata, depth_key="time", groupby="clade", bins=10)
Contents