pycea.tl.fitch_count

Contents

pycea.tl.fitch_count#

pycea.tl.fitch_count(tdata, key, states=None, missing_state=None, root=None, tree=None, key_added='fitch_count', copy=True)#

Runs the FitchCount algorithm.

Performs the FitchCount algorithm for inferring the number of times that two states transition to one another across all equally-parsimonious solutions returned by the Fitch-Hartigan algorithm. The original algorithm was described in [QJO+21]. The output is an MxM count matrix, where the values indicate the number of times that m1 transitioned to m2 along an edge in a Fitch-Hartigan solution. To obtain probabilities P(m1 -> m2), divide each row by its row-sum.

This procedure will only work on categorical data.

Parameters:

  • tdata (TreeData) – TreeData object.

  • key (str) – An obs.keys() corresponding to a categorical variable.

  • states (Sequence[str] | None (default: None)) – State space that can be optionally provided by the user. If not provided, the unique non-missing values in tdata.obs[key] are used.

  • missing_state (str | None (default: None)) – The state to consider as missing data. Missing leaves are treated as wildcards (may take on any state in states).

  • root (str | None (default: None)) – Node to treat as the root. Only the subtree below this node is considered. Only valid when a single tree is used.

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

  • key_added (str (default: 'fitch_count')) – Key in tdata.uns where the count matrix is stored.

  • copy (Literal[True, False] (default: True)) – If True, returns the count matrix.

Return type:

DataFrame | None

Returns:

Returns None if copy=False. Otherwise returns an MxM DataFrame. When multiple trees are used, the per-tree count matrices are summed into a single matrix.

Sets the following fields:

  • tdata.uns[key_added]DataFrame

    • Count matrix, summed across all trees used.

Examples

Count state transitions across equally-parsimonious solutions:

>>> py.tl.fitch_count(tdata, key="tissue", copy=True)
Contents