Datasets

Bundled datasets, see Datasets.

list_datasets

list_datasets() -> list[str]

Names of the bundled datasets.

The datasets were exported from the R package metadat (https://wviechtb.github.io/metadat/): every data frame it provided when they were exported, plus the data of Moura et al. (2021) and its phylogenetic tree. A few datasets listed on the metadat site are not bundled, and the list can include dat.berkey1998r, which is not in the site index.

Returns:

Type	Description
list[str]	The sorted names, each with the dat. prefix, for example 'dat.bcg'. Pass them to load. The name
list[str]	'dat.moura2021.tree' is a tree, not a data frame; read it with load_tree.

load

load(name: str) -> DataFrame

Load a bundled metadat dataset.

Datasets that metadat stores as escalc objects (for example dat.konstantopoulos2011) carry the attributes of such a frame in DataFrame.attrs, as escalc stores them, so that rma takes the effect size measure and the sample sizes from them, as in R.

Parameters:

Name	Type	Description	Default
name	str	name of the dataset, with or without the dat. prefix ('dat.bcg' and 'bcg' are the same). See list_datasets.	required

Returns:

Type	Description
DataFrame	A new data frame with the columns of the R dataset (a copy that can be changed freely).

Raises:

Type	Description
NotFoundError	there is no dataset of that name.

load_tree

load_tree(name: str) -> PhyloTree

Load a bundled phylogenetic tree by dataset name, for example load_tree('moura2021').

Parameters:

Name	Type	Description	Default
name	str	name of the dataset the tree belongs to, with or without the dat. prefix.	required

Returns:

Type	Description
PhyloTree	The tree as a PhyloTree.

Raises:

Type	Description
NotFoundError	there is no such tree.

PhyloTree dataclass

PhyloTree(edges: DataFrame)

A rooted tree stored as an edge table, like the phylo class of the R package ape.

Tips are the nodes that are never a parent; the tips are taken in the order of their node ids (as in ape, and as in the bundled tree, the tips have the ids 1 to the number of tips).

Attributes:

Name	Type	Description
edges	DataFrame	data frame with one row per edge and the columns parent and child (node ids), length (edge length) and child_label (label of the child node).

tip_labels property

tip_labels: tuple[str, ...]

Labels of the tips, in the order of their node ids.

vcv

vcv(corr: bool = False) -> DataFrame

Variance-covariance matrix of a Brownian-motion trait along the tree (ape::vcv.phylo).

Entry (i, j) is the summed edge length shared by the root-to-tip paths of tips i and j.

Parameters:

Name	Type	Description	Default
corr	bool	whether to return the correlation matrix instead (default False).	False

Returns:

Type	Description
DataFrame	Square data frame with the tip labels as index and columns.

Raises:

Type	Description
InputError	the edge table does not describe a tree (a node has two parents, or a cycle can be reached from a tip).