pycea.tl.fitness

Contents

pycea.tl.fitness#

pycea.tl.fitness(tdata, depth_key='depth', key_added='fitness', method='sbd', method_kwargs=None, sample_n=200, tree=None, random_state=None, copy=False)#
Overloads:

  • tdata (td.TreeData), depth_key (str), key_added (str), method (Literal[‘sbd’, ‘lbi’]), method_kwargs (Mapping | None), sample_n (int), tree (str | list[str] | None), random_state (int | None), copy (Literal[True, False]) → pd.DataFrame

  • tdata (td.TreeData), depth_key (str), key_added (str), method (Literal[‘sbd’, ‘lbi’]), method_kwargs (Mapping | None), sample_n (int), tree (str | list[str] | None), random_state (int | None), copy (Literal[True, False]) → None

Estimates node fitness.

This function implements two algorithms proposed by [NRS14] for estimating relative fitness from the tree topology and branch lengths:

  • method="sbd"

    Selection-Biased Diffusion (SBD), a message-passing algorithm that propagates information up and down the tree to infer posterior distributions of fitness at each node. This corresponds to the probabilistic framework described by Neher et al. (2014) and yields posterior mean fitness values for the tree’s nodes.

  • method="lbi"

    Local Branching Index (LBI), a heuristic that measures node fitness based on the density of branching in its local neighborhood. Higher LBI values correspond to nodes with more prolific descendant lineages.

Parameters:

  • tdata (TreeData) – TreeData object.

  • tree (str | list[str] | None (default: None)) – Key identifying the tree in tdata.obst. If None use all trees.

  • depth_key (str (default: 'depth')) – Node attribute storing depth.

  • key_added (str (default: 'fitness')) – Attribute name to store inferred fitness.

  • method (Literal['sbd', 'lbi'] (default: 'sbd')) –

    Method to use for fitness inference.

    • 'sbd': Selection-Biased Diffusion.

    • 'lbi': Local Branching Index.

  • method_kwargs (Mapping | None (default: None)) –

    Additional keyword arguments passed to the selected method. For example:

    • gamma (float, default=0.2): Dimensionless diffusion constant (for SBD).

    • attach_posteriors (bool, default=False): If True, attach posterior distributions to nodes (for SBD).

    • tau (float, default=None): Time scale (for LBI).

  • sample_n (int (default: 200)) – Number of leaf pairs to use for time-scale estimation.

  • tree – The obst key or keys of the trees to use. If None, all trees are used.

  • random_state (int | None (default: None)) – Random seed.

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

Returns:

Returns None if copy=False, otherwise returns a pandas.DataFrame with fitness values.

Sets the following fields:

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

    • Inferred fitness values for each node.

  • tdata.obs[key_added]float

    • Inferred fitness values for each observed node. For tdata.alignment == "leaves", only leaf nodes are written. For "nodes" or "subset", all observed nodes (including internal nodes) are written.

Contents