qdiv.sequences.merge_objects

qdiv.sequences.merge_objects(objlist, *, already_aligned=False, different_lengths=False, name_type='OTU', return_type='auto')[source]

Merge multiple microbiome objects and retain all features (OTUs/ASVs/etc).

This function aligns features across all input objects (unless already_aligned=True), concatenates abundance tables (columns are sample names; they are suffix-annotated per input object to avoid collisions), and concatenates sequences and taxonomy tables while removing duplicates. Feature rows are re-ordered by total abundance and renamed using name_type + rank (e.g., “OTU1”, “OTU2”, …).

Parameters:

  • objlist (list of dict or MicrobiomeData) –

    List of input objects to merge. Each item must contain:

    • ’tab’ : pd.DataFrame (features × samples abundance table)

    • ’seq’ : pd.DataFrame (sequences, indexed by feature IDs)

    Optionally may contain:

    • ’tax’ : pd.DataFrame (taxonomy annotations

    • ’meta’: pd.DataFrame (sample metadata, indexed by sample names)

    Items can be plain dicts or MicrobiomeData instances.

  • already_aligned (bool, default False) – If True, assumes align has already been applied to the objects and feature names/sequences are harmonized. If False, calls align(…).

  • different_lengths (bool, default False) – If True, allows alignment of features with different sequence lengths (substring matching). Passed to align when alignment is performed.

  • name_type (str, default 'OTU') – Prefix for renaming merged features in descending order of total abundance (e.g., “OTU1”, “OTU2”, …).

  • return_type ({'auto', 'dict', 'microbiome'}, default 'auto') –

    Determines the type of object returned:

    • ’microbiome’: return a MicrobiomeData object.

    • ’dict’ : return a dict.

    • ’auto’ : if any input in objlist is a MicrobiomeData, return MicrobiomeData, otherwise return dict.

Returns:

out – The merged object containing:

  • ’tab’ : merged abundance table

  • ’seq’ : merged sequence table

  • ’tax’ : merged taxonomy table (if present)

  • ’meta’: merged metadata table (if present)

Return type depends on return_type (see above).

Return type:

dict or MicrobiomeData

Notes

  • Sample names in the merged ‘tab’ and ‘meta’ are suffixed with _i where i is the index of the source object in objlist, to avoid collisions.

  • Features are sorted by total abundance (sum across all samples) and then renamed using name_type and their new rank.

  • Sequences/taxonomy are de-duplicated with drop_duplicates() after concatenation.

  • The merged output does not include a phylogenetic tree.

Examples

>>> out = merge_objects([obj1, obj2])