qdiv.plot.dissimilarity_contributions

qdiv.plot.dissimilarity_contributions(obj, *, by=None, q=1.0, div_type='naive', index='local', n=20, levels=None, from_file=None, figsize=(7.086614173228346, 5.511811023622047), fontsize=10, savename=None)[source]

Plot contributions of taxa to observed dissimilarity within categories.

This function visualizes how individual taxa contribute to dissimilarity (e.g., Bray-Curtis or Hill-based) across sample groups defined by metadata.

Parameters:

  • obj (dict or MicrobiomeData) –

    Input data containing at least:
    • ’tab’: pandas.DataFrame

      Abundance table (features x samples).

    • ’tax’: pandas.DataFrame

      Taxonomy table (features x taxonomic levels).

    • meta (pandas.DataFrame): metadata table.

  • by (str, optional) – Metadata column used to categorize samples. Dissimilarity is calculated within each category.

  • q (float, default=1.0) – Diversity order (Hill number).

  • div_type ({'naive', 'phyl'}, default='naive') – Diversity type: - ‘naive’: taxonomic dissimilarity. - ‘phyl’: phylogenetic dissimilarity.

  • index ({'local', 'regional'}, default='local') – Index type for dissimilarity calculation.

  • n (int, default=20) – Number of top taxa to include in the plot.

  • levels (list of str, optional) – Taxonomic levels to include in y-axis labels (e.g., [‘Genus’]).

  • from_file (str, optional) – Path to a CSV file with precomputed dissimilarity contributions. If None, contributions are computed from obj.

  • figsize (tuple of float, default=(18/2.54, 14/2.54)) – Figure size in inches.

  • fontsize (int, default=10) – Font size for plot text.

  • savename (str, optional) – If provided, save the figure to this path and also as PDF.

Returns:

  • fig (matplotlib.figure.Figure)

  • df (pandas.DataFrame) – DataFrame of contributions for plotted taxa and categories. Returns None if computation or plotting fails.

Return type:

Tuple[plt.figure.Figure, pd.DataFrame]

Notes

  • If from_file is provided, the function reads contributions from that file.

  • If levels is provided and div_type=’naive’, taxonomy names are appended to feature IDs.

  • For phylogenetic diversity, node names or feature sets are used for labeling.

Examples

>>> df = dissimilarity_contributions(obj, by='Treatment', q=1, div_type='naive', levels=['Genus'])
>>> print(df.head())