MicrobiomeData

The MicrobiomeData class is the central data container in qdiv. It stores abundance tables, taxonomy, metadata, sequences, and phylogenetic trees, and provides methods for importing, manipulating, validating, and exporting microbiome datasets.

What is a data object?

A MicrobiomeData object may contain:

tab: abundance table (features × samples)
tax: taxonomy table
meta: metadata table
seq: sequence table
tree: phylogenetic tree dataframe
leaf_order: ordering of tree leaves

Methods

Creating objects

Create a new object or construct one from existing files, example datasets, or dictionaries.

`MicrobiomeData`	Container for microbiome data tables (abundance, taxonomy, metadata, sequences, tree).
`load`	Load microbiome data from files and return a MicrobiomeData object.
`load_example`	Load a MicrobiomeData object from packaged example files.
`from_dict`	Create a MicrobiomeData object from a dictionary.

Importing data

General file formats

`add_tab`	Add or update self.tab (and self.tax if included in the file).
`add_tax`	Add or update self.tax.
`add_meta`	Load meta data into a dictionary with a pandas DataFrame.
`add_seq_from_fasta`	Add or update self.seq.
`add_tree`	Load tree from a newick file into a dictionary with a pandas DataFrame.

External software formats

`add_tax_from_qiime`	Add or update taxonomy from a QIIME2-style taxonomy file.
`add_tax_from_sintax`	Add or update taxonomy from a SINTAX output file.
`add_tax_from_gtdbtk`	Add or update taxonomy from one or more GTDB-Tk summary files.
`add_tab_from_coverm`	Add a relative abundance table from a CoverM file.
`add_ebd_tab_from_singlem`	Add count data (tab) and taxonomic information (tax) from an EBD file generated with SingleM.

Exploring and exporting data

Inspect object contents, summarize datasets, and save data to disk.

`info`	Print summary information about the MicrobiomeData object.
`summarize_taxa`	Summarize the number of taxa at each taxonomic level per sample.
`save`	Save frequency table, taxonomy, metadata, sequences, and tree to disk.
`to_dict`	Return the data as a dictionary.
`copy`	Copy MicrobiomeData object.

Subsetting and filtering

Select samples, features, or taxa and perform rarefaction.

`subset_samples`	Subset samples in the MicrobiomeData object using io.subset_samples.
`subset_features`	Subset features (OTUs/ASVs/bins/MAGs) from a MicrobiomeData object using io.subset_features.
`subset_taxa`	Subset features (OTUs/ASVs/bins/MAGs) from the MicrobiomeData object based on taxonomic classification.
`subset_abundant`	Subset features (OTUs/ASVs/bins/MAGs) from a MicrobiomeData object using io.subset_abundant.
`rarefy`	Rarefy the abundance table to a fixed sequencing depth.

Sample aggregation

Combine samples based on metadata variables.

merge_samples

Merge samples in the MicrobiomeData object based on metadata grouping.

Taxonomy and feature utilities

Utilities for renaming features and standardizing taxonomy tables.

`rename_features`	Rename feature identifiers (row indices) based on their relative abundance or taxonomic order.
`tax_prefix`	Add or remove prefix (e.g. d__, p__) to taxonomic classifications.
`clean_tax`	Clean and standardize Greengenes2/GTDB taxonomy within a MicrobiomeData object.

Phylogenetic tree operations

Manipulate and synchronize phylogenetic trees with abundance data.

prune_tree

Prune the tree to retain only branches whose leaves intersect with a given feature set, plus always keep the root branch.

Complete API reference

class qdiv.MicrobiomeData(tab=None, tax=None, meta=None, seq=None, tree=None, leaf_order=None)

Bases: object

Container for microbiome data tables (abundance, taxonomy, metadata, sequences, tree).

Parameters:

tab (Optional[pd.DataFrame])
tax (Optional[pd.DataFrame])
meta (Optional[pd.DataFrame])
seq (Optional[pd.DataFrame])
tree (Optional[pd.DataFrame])
leaf_order (Optional[list])

tab

Abundance table (features x samples).

Type:: pd.DataFrame, optional

tax

Taxonomy table (features x taxonomy levels).

Type:: pd.DataFrame, optional

meta

Metadata table (samples x variables).

Type:: pd.DataFrame, optional

seq

Sequence table (features x sequence).

Type:: pd.DataFrame, optional

tree

Phylogenetic tree.

Type:: pd.DataFrame, optional

add_ebd_tab_from_singlem(filename, *, path='', first_sep=None, second_sep=' ')[source]

Add count data (tab) and taxonomic information (tax) from an EBD file generated with SingleM.

Parameters:

filename (str) – Path to the file (TSV).
path (str, default "") – Directory path (absolute or relative) containing file(s). Can be “” for CWD.
first_sep (str or None) – Separator used to find sample name in CoverM-file column headings. Defaults to None.
second_sep (str) – Separator used to find sample name in CoverM-file column headings. Defaults to None.

Returns:

The updated object (self).

Return type:

MicrobiomeData

add_meta(meta, *, path='', sep=',')[source]

Load meta data into a dictionary with a pandas DataFrame.

Parameters:

meta (str) – Name of the meta data file.
path (str, default "") – Directory path (absolute or relative) containing meta. Can be “” for CWD.
sep (str or None, default ",") – Column separator. If None, pandas will attempt to auto-detect (engine=’python’).

Returns:

The updated object (self).

Return type:

MicrobiomeData

Examples

>>> obj = MicrobiomeData.load()
>>> obj.add_meta(meta="metadata.csv")

add_seq_from_fasta(fasta, *, path='', name_splitter=None)[source]

Add or update self.seq.

Parameters:

fasta (str) – Name of the FASTA file with sequences of OTUs or ASVs (.fa, .fasta, optionally gzipped).
path (str, default "") – Directory path (absolute or relative) containing fasta. Can be “” for CWD.
name_splitter (str, optional) – If provided, splits sequence names on this delimiter and keeps the first part.

Raises:

ValueError – If fasta is missing or file cannot be read. If no sequences are found.

Returns:

The updated object (self).

Return type:

MicrobiomeData

Examples

>>> obj = MicrobiomeData.load()
>>> obj.add_seq_from_fasta(fasta="OTU_sequences.fasta")

add_tab(tab, *, path='', sep=None, taxonomy_levels=None)[source]

Add or update self.tab (and self.tax if included in the file).

Parameters:

tab (str) – File name of the frequency table (.csv/.tsv, optionally gzipped, e.g. .csv.gz). Feature names (OTU/ASV/bin/MAG) should be in the first column (index).
path (str, default "") – Directory path (absolute or relative) containing tab. Can be “” for CWD.
sep (str or None, default None) – Column separator. If None, pandas will attempt to auto-detect (engine=’python’).
taxonomy_levels (list of str, optional) – Case-insensitive taxonomy column names to extract. Defaults to a broad set.

Raises:

ValueError – If the file cannot be read or has invalid format.

Returns:

The updated object (self).

Return type:

MicrobiomeData

Examples

>>> obj = MicrobiomeData.load()
>>> obj.add_tab(tab="otu_table.csv")

add_tab_from_coverm(filename, *, path='', first_sep=None, second_sep=' ', ra_col='Relative Abundance', detection_threshold=None)[source]

Add a relative abundance table from a CoverM file.

Parameters:

filename (str) – Path to coverm .tsv or .csv file.
path (str, default "") – Directory path (absolute or relative) containing file(s). Can be “” for CWD.
first_sep (str, optional) – Separator to help extract sample names from column headings.
second_sep (str, optional) – Second separator to help extract sample names from column headings.
ra_col (str, default='Relative Abundance') – Column in CoverM output file used to calculate relative abundance.
detection_threshold (float, optional, default None) – If set, all relative abundances below this threshold are set to zero, but only if both ‘Covered Bases’ and ‘Length’ columns are available for the sample. The detection threshold is a fraction from 0 to 1.

Returns:

The updated object (self).

Return type:

MicrobiomeData

add_tax(tax, *, path='', sep=None, add_taxon_prefix=True)[source]

Add or update self.tax.

Parameters:

tax (str) – File name of the taxonomy table (.csv/.tsv, optionally gzipped, e.g. .csv.gz). Feature names (OTU/ASV/bin/MAG) should be in the first column (index).
path (str, default "") – Directory path (absolute or relative) containing tab. Can be “” for CWD.
sep (str or None, default ",") – Column separator. If None, pandas will attempt to auto-detect (engine=’python’).
add_taxon_prefix (bool, default True) – If True, add letters and two underscores before taxon names to indicate taxonomic level.

Returns:

The updated object (self).

Return type:

MicrobiomeData

Examples

>>> obj = MicrobiomeData.load()
>>> obj.add_tax(tax="taxonomy_table.csv")

add_tax_from_gtdbtk(filenames, *, path='')[source]

Add or update taxonomy from one or more GTDB-Tk summary files.

Parameters:

filenames (str or list of str) – Path(s) to GTDB-Tk summary .tsv file(s).
path (str, default "") – Directory path (absolute or relative) containing file(s). Can be “” for CWD.

Returns:

The updated object (self).

Return type:

MicrobiomeData

add_tax_from_qiime(filename, *, path='')[source]

Add or update taxonomy from a QIIME2-style taxonomy file.

Parameters:

filename (str) – File name of the taxonomy table (.tsv, e.g. from QIIME2 export).
path (str, default "") – Directory path (absolute or relative) containing tax. Can be “” for CWD.

Returns:

The updated object (self).

Return type:

MicrobiomeData

add_tax_from_sintax(filename, *, path='')[source]

Add or update taxonomy from a SINTAX output file.

Parameters:

filename (str) – Path to the SINTAX output file.
path (str, default "") – Directory path (absolute or relative) containing sintax_file. Can be “” for CWD.

Returns:

The updated object (self).

Return type:

MicrobiomeData

add_tree(tree, *, path='')[source]

Load tree from a newick file into a dictionary with a pandas DataFrame.

Parameters:

tree (str) – Name of the newick file with the tree.
path (str, default "") – Directory path (absolute or relative) containing tree. Can be “” for CWD.

Returns:

The updated object (self).

Return type:

MicrobiomeData

Examples

>>> obj = MicrobiomeData.load()
>>> obj.add_tree(tree="Phylogenetic_tree.nwk")

clean_tax(inplace=False)[source]

Clean and standardize Greengenes2/GTDB taxonomy within a MicrobiomeData object.

This function processes taxonomy derived from Greengenes2 or GTDB. It normalizes missing or ambiguous labels, preserves GTDB letter suffixes (e.g., _A, _B), and removes GTDB numeric node identifiers (e.g., _368345) at all taxonomic ranks.

Parameters:: inplace (bool, default=False) – If True, modify object in place.
Returns:: The updated object. If inplace=True, returns self; otherwise, a new instance.
Return type:: MicrobiomeData

Notes

Unknown or unassigned labels (e.g., “Unknown”, “None”, “unclassified”) are normalized to NA.
The function add prefixes such as d__, p__ by default. These can later be removed by the tax_prefix function if needed.

copy()[source]

Copy MicrobiomeData object.

Returns:: A copy of the object.
Return type:: MicrobiomeData

Examples

>>> obj_copy = obj.copy()

classmethod from_dict(data)[source]

Create a MicrobiomeData object from a dictionary.

Parameters:

data (dict) –

Dictionary with keys:

’tab’ : pd.DataFrame, optional
’tax’ : pd.DataFrame, optional
’meta’ : pd.DataFrame, optional
’seq’ : pd.DataFrame, optional
’tree’ : pd.DataFrame, optional
’leaf_order’ : list, optional

Returns:

A new MicrobiomeData object initialized from the dictionary.

Return type:

MicrobiomeData

Examples

>>> my_dict = {
...     "tab": pd.DataFrame(...),
...     "tax": pd.DataFrame(...),
...     "meta": pd.DataFrame(...)
... }
>>> obj = MicrobiomeData.from_dict(my_dict)

info(preview_rows=1)[source]

Print summary information about the MicrobiomeData object.

Parameters:: preview_rows (int, optional) – Number of rows to preview from metadata (default: 1).
Return type:: None

Examples

>>> obj.info()

classmethod load(**kwargs)[source]

Load microbiome data from files and return a MicrobiomeData object.

Parameters:: kwargs (dict) – Arguments for file paths and parsing options, passed to the loader.
Returns:: Loaded data object.
Return type:: MicrobiomeData

Examples

>>> data = MicrobiomeData.load(tab="otu_table.csv", meta="metadata.csv")

classmethod load_example(example_name='Modin_et_al_2025')[source]

Load a MicrobiomeData object from packaged example files.

Parameters:

example_name (str) –

Name of the example to load. Options:

”Modin2025”: Uses CoverM and GTDB-Tk output files from the Modin et al. study https://doi.org/10.1111/1751-7915.70238.
”Saheb-Alam2019_DADA2”: Uses qiime2-dada2 output files from the Saheb-Alam et al. study https://doi.org/10.1111/1751-7915.13449.
”Saheb-Alam2019_Deblur”: Uses qiime2-deblur output files from the Saheb-Alam et al. study https://doi.org/10.1111/1751-7915.13449.

Returns:

An instance loaded with example data.

Return type:

MicrobiomeData

Raises:

ValueError – If the example_name is not recognized.

merge_samples(*, by, values=None, method='sum', weight=None, keep_absent=False, inplace=False)[source]

Merge samples in the MicrobiomeData object based on metadata grouping.

Parameters:

by (str or list) – Column(s) in metadata used for grouping samples.
values (list, optional) – Metadata values to keep. If None, all unique values in by are used.
method ({'sum', 'mean'}, default 'sum') – Aggregation method used when weight=None. If weight is provided, samples are merged using a weighted average based on the specified metadata column.
weight (str, optional, default None) – Name of a numeric metadata column used for weighted merging. Within each group, weights are normalized to sum to 1 and used to calculate a weighted average of feature abundances. If None, samples are merged using the specified method (‘sum’ or ‘mean’). keep_absent : bool, default False If False, remove features with zero counts after merging.
inplace (bool, default False) – If True, modify this object in place; if False, return a new object.
keep_absent (bool)

Returns:

Object with merged samples. Returns self if inplace=True, otherwise a new MicrobiomeData instance.

Return type:

MicrobiomeData

Raises:

ValueError – If metadata or the specified column is missing, or if no samples match the specified values.

Examples

>>> obj.merge_samples(by="Treatment", method="sum", inplace=True)

prune_tree(featurelist=None, reroot=False, inplace=False)[source]

Prune the tree to retain only branches whose leaves intersect with a given feature set, plus always keep the root branch.

Parameters:

featurelist (list of str or set of str or iterable of str, optional) – A collection of feature names to match against the leaves of each branch. If None, the method will attempt to use self.tab.index.tolist().
reroot (bool, default False) – If True, reroot the pruned tree at midpoint.
inplace (bool, default False) – If True, modify this object in place; if False, return a new object.

Returns:

The object with pruned tree. Returns self if inplace=True, otherwise a new MicrobiomeData instance.

Return type:

MicrobiomeData

rarefy(*, depth='min', random_state=None, replacement=False, inplace=False, **kwargs)[source]

Rarefy the abundance table to a fixed sequencing depth.

This method performs random subsampling (with or without replacement) to equalize sequencing depth across samples, then drops features and samples that become zero.

Parameters:

depth (int or 'min', default 'min') – Target sequencing depth per sample. If ‘min’, the minimum depth across samples is used.
random_state (int | numpy.random.Generator, optional) – Random seed or Generator for reproducibility.
replacement (bool, default False) – If True, sample with replacement; otherwise samplewithout replacement.
inplace (bool, default False) – If True, modify this object in place; if False, return a new object.

Returns:

The rarefied object. Returns self if inplace=True, otherwise a new MicrobiomeData instance.

Return type:

MicrobiomeData

Notes

Rarefaction reduces sequencing depth variance across samples to facilitate certain diversity and dissimilarity analyses.

Examples

>>> obj.rarefy(depth=10000, random_state=42, inplace=True)
>>> rarefied_obj = obj.rarefy(depth='min', replacement=True)

rename_features(name_type='OTU', name_dict=None, inplace=False)[source]

Rename feature identifiers (row indices) based on their relative abundance or taxonomic order.

The renaming is done either based on the rank of the feature after sorting based on relative abundance or based on a dictionary containing existing names as keys and new names as values. If ‘name_dict’ is None, the features are renamed according in the format {name_type}{i}, and sorted: - By mean relative abundance if tab (abundance table) is present. - By taxonomic order if tax is present and tab is absent.

Parameters:

name_type (str, default='OTU') – Prefix for new feature names, e.g., ‘OTU’, ‘ASV’ (used is name_dict is None).
name_dict (dict, default=None) – Dictionary with feature name {‘Old_name’: ‘New:name’, …}.
inplace (bool, default=False) – If True, modify object in place.

Returns:

The updated object. If inplace=True, returns self; otherwise, a new instance.

Return type:

MicrobiomeData

save(path='', savename='output', sep=',')[source]

Save frequency table, taxonomy, metadata, sequences, and tree to disk.

Parameters:

path (str, optional) – Directory path where files will be saved. Defaults to the current directory.
savename (str, optional) – Base name for output files. Defaults to “output”.
sep (str, optional) – Field separator for CSV files. Defaults to “,”.

Returns:

List of file paths that were saved.

Return type:

list of str

Examples

>>> obj.save(savename="mydata")

subset_abundant(*, n=25, method='mean', cutoff=None, exclude=False, inplace=False)[source]

Subset features (OTUs/ASVs/bins/MAGs) from a MicrobiomeData object using io.subset_abundant.

Parameters:

n (int, default 25) – Number of top features to keep (or exclude if exclude=True). Values outside [0, n_features] are clamped to the valid range.
method ({'sum','mean','frequency'}, default 'mean') – Reduction across samples of relative abundance per feature. - ‘sum’ : total relative abundance across samples - ‘mean’ : mean relative abundance across samples - ‘max’ : max relative abundance in a sample - ‘frequency’ : proportion of samples in which the feature is detected
cutoff (float, default None) – If cutoff is specific as a percentage (from 0 to 100%), all features with a ‘sum’ or ‘mean’ relative abundance or ‘frequency’ of detection above this value will be kept, and the parameter n will be ignored.
exclude (bool, default False) – If False (default), keep the top features. If True, exclude the top features (keep the rest).
inplace (bool, default False) – Only relevant for MicrobiomeData input. If True, mutate the object and return it; otherwise, return a new object.

Returns:

The filtered object (self if inplace=True, otherwise a new object).

Return type:

MicrobiomeData

subset_features(*, featurelist=None, exclude=False, inplace=False)[source]

Subset features (OTUs/ASVs/bins/MAGs) from a MicrobiomeData object using io.subset_features.

Parameters:

featurelist (list) – List of feature (OTU/ASV/bin) identifiers to keep or exclude.
exclude (bool, default False) – If True, exclude values in featurelist instead of including them.
inplace (bool, default False) – If True, mutate and return the same object. If False, return a new object.

Returns:

The filtered object (self if inplace=True, otherwise a new object).

Return type:

MicrobiomeData

Examples

>>> obj_sub = obj.subset_samples(featurelist=['OTU1', 'OTU2', 'OTU3'])
>>> obj_sub = obj.subset_samples(featurelist=['OTU1', 'OTU2', 'OTU3'], exclude=True)

subset_samples(*, by='index', values=None, exclude=False, keep_absent=False, inplace=False)[source]

Subset samples in the MicrobiomeData object using io.subset_samples.

Parameters:

by (str, default "index") – How to select samples: “index” for sample names, or a column name in meta.
values (list or scalar, optional) – Values to include (or exclude if exclude=True). If None and by != “index”, all unique values of meta[by] are used, exluding nan.
exclude (bool, default False) – If True, exclude samples that match values.
keep_absent (bool, default False) – If False, drop features (rows) with zero counts after subsetting.
inplace (bool, default False) – If True, modify the object in place. If False, return a new object.

Returns:

The filtered object (self if inplace=True, otherwise a new object).

Return type:

MicrobiomeData

Examples

>>> obj_sub = obj.subset_samples(by='Metadata_column_header', values='Treatment_A')

subset_taxa(*, subset_levels=None, subset_patterns=None, exclude=False, case=False, regex=False, na=False, match_type='contains', inplace=False)[source]

Subset features (OTUs/ASVs/bins/MAGs) from the MicrobiomeData object based on taxonomic classification.

Parameters:

subset_levels (str or sequence of str, optional) – Taxonomic column(s) in which to search for patterns. If None, all columns in tax are used.
subset_patterns (str or sequence of str) – Text patterns to identify taxa to keep. If a single string is passed, it is used as the only pattern.
exclude (bool, default False) – If True, return taxa that do NOT match the given patterns (i.e., complement).
case (bool, default False) – If True, pattern matching is case-sensitive.
regex (bool, default False) – If True, patterns are treated as regex. If False, patterns are escaped (literal match).
na (bool, default False) – If True, na are treated as matches. If False, na are treated as non-matches. Empty or whitespace-only taxonomy entries are treated as missing (NA) during subsetting.
match_type ({'contains','fullmatch','startswith','endswith'}, default 'contains') – Matching behavior applied to the strings in selected columns.
inplace (bool, default False) – If True, mutate and return the same object. If False, return a new object.

Returns:

Filtered object with updated ‘tab’, ‘tax’, and ‘seq’. ‘meta’, ‘tree’, and ‘leaf_order’ are passed through.

Return type:

MicrobiomeData

Examples

>>> obj.subset_taxa(subset_levels="Genus", subset_patterns="Bacteroides", inplace=True)
>>> filtered_obj = obj.subset_taxa(subset_patterns=["Bacteroides", "Clostridium"], exclude=True)

summarize_taxa(savename=None, *, path='')[source]

Summarize the number of taxa at each taxonomic level per sample.

Parameters:

savename (str or None, default=None) – If provided, save the output table as CSV in the given path.
path (str)

Returns:

Summary table with:

number of features per sample

total reads per sample

number of unique taxa at each taxonomic level

Return type:

pandas.DataFrame

tax_prefix(add=True, inplace=False, custom_prefix=None)[source]

Add or remove prefix (e.g. d__, p__) to taxonomic classifications.

Parameters:

add (bool, default=True) – If True, add prefix. If False, remove prefix.
inplace (bool, default=False) – If True, modify object in place.
custom_prefix (dict, default=None) – A dictionary with taxonomic levels as keys and prefix as values.

Returns:

The updated object. If inplace=True, returns self; otherwise, a new instance.

Return type:

MicrobiomeData

to_dict()[source]

Return the data as a dictionary.

Returns:: Dictionary with keys: ‘tab’, ‘tax’, ‘meta’, ‘seq’, ‘tree’.
Return type:: dict