biotapy.tl.alpha

Contents

biotapy.tl.alpha#

biotapy.tl.alpha(adata, *, metrics=('observed_features', 'shannon', 'simpson', 'chao1'), inplace=False)#

Alpha diversity of every sample.

Parameters:

  • adata (AnnData) – Samples x features. "faith_pd" needs a TreeData with vart['phylo'].

  • metrics (Sequence[Literal['observed_features', 'shannon', 'simpson', 'chao1', 'faith_pd']] (default: ('observed_features', 'shannon', 'simpson', 'chao1'))) – Any of "observed_features", "shannon" (natural log), "simpson" (Gini-Simpson, 1 - sum(p**2)), "chao1" (bias-corrected) and "faith_pd".

  • inplace (bool (default: False)) – Write obs['alpha_<metric>'] for every metric and return None.

Return type:

DataFrame | None

Returns:

pandas.DataFrame or None One row per sample (index obs_names) and one column per metric, in the order given. An all-zero sample gets 0 for observed_features, chao1 and faith_pd and NaN for shannon and simpson.

Raises:

  • TypeError – metrics is a string, or "faith_pd" is asked of an AnnData that is not a TreeData.

  • ValueError – metrics is empty, names an unknown metric or repeats one, or "observed_features" or "chao1" is asked of data that is not raw counts (x_kind "counts" and whole numbers).

  • KeyError – "faith_pd" is asked of a TreeData without vart['phylo'].

Notes

R equivalent: phyloseq::estimate_richness, picante::pd Guide: Diversity

scikit-bio needs dense input, so rows are densified in chunks of at most 2**20 values (8 MiB of float64), plus an 8 MiB int64 presence copy per chunk when faith_pd is asked. Faith PD includes the root, as picante::pd(include.root = TRUE); a root with more than two children first gets a zero-length split, which changes no root-to-tip distance. Faith PD depends on presence only, so it is computed on presence/absence and runs on any abundance: scikit-bio’s tree code casts abundances to integers, which truncates proportions to 0. For an all-zero sample phyloseq reports Shannon 0 and Simpson 1; biotapy returns NaN.

References

Shannon CE (1948) A mathematical theory of communication. Bell System Technical Journal 27:379-423.

Simpson EH (1949) Measurement of diversity. Nature 163:688.

Chao A (1984) Nonparametric estimation of the number of classes in a population. Scandinavian Journal of Statistics 11:265-270.

Faith DP (1992) Conservation evaluation and phylogenetic diversity. Biological Conservation 61:1-10.

Examples

>>> import biotapy as bt
>>> out = bt.tl.alpha(bt.datasets.toy(), metrics=["observed_features", "shannon"])
>>> out.loc["s1"].round(3).tolist()
[6.0, 1.361]
Contents