qdiv.stats.summarize_dbrda

qdiv.stats.summarize_dbrda(dis, meta, *, by=None, condition=None, interactions=None, pcoa_fn=<function pcoa_lingoes>, perm_n=999, perm_seed=42, drop_first=True, include_interpretation=True, include_alone=True)[source]

Summarize db‑RDA (global model + marginal factor tests).

This function:

  1. Runs dbRDA once (global model).

  2. Runs marginal (partial) permutation tests per factor (Freedman–Lane).

  3. Aggregates % explained by original factors (from the full model).

  4. Computes R² and adjusted R².

  5. Returns a tidy DataFrame, optionally with textual interpretation.

Parameters:

  • dist (pandas.DataFrame) – Square distance matrix (rows/cols = samples). Index must match columns.

  • meta (pandas.DataFrame) – Metadata indexed by sample IDs.

  • by (str or list of str, optional) – Subset of metadata columns to use as explanatory variables. If None, all columns in meta are used.

  • condition (pandas.DataFrame, optional) – Covariates to partial out (same index as meta).

  • interactions (list of str, optional) – Variables for which interaction terms should be generated.

  • pcoa_fn (callable, default=pcoa_lingoes) – Function for the PCoA step; must return ‘site_scores’ and ‘eigenvalues’.

  • perm_n (int, default=999) – Number of permutations for marginal tests.

  • perm_seed (int, default=42) – Random seed for permutations.

  • drop_first (bool, default=True) – Drop first level in categorical encoding (reference coding).

  • include_interpretation (bool, default=True) – If True, adds a textual interpretation column.

  • include_alone (bool, default=True) – If True, keeps “alone” diagnostics (factor-alone %-explained, p-alone).

  • dis (DataFrame)

Returns:

Columns (by default):

  • Factor

  • pct_explained (full model)

  • df_added

  • delta_inertia

  • pct_explained (marginal)

  • F

  • p-marginal

  • inertia_alone

  • pct_explained (alone)

  • p-alone

  • Interpretation (optional)

Attributes (df.attrs):

  • ’R²’ : float

  • ’Adjusted R²’ : float

  • ’F_global’ : float

  • ’p_global’ : float

  • ’Total inertia’ : float

  • ’Constrained inertia’ : float

  • ’Unconstrained inertia’ : float

  • ’n’ : int (samples)

  • ’df_model’ : int (approx. number of fitted parameters)

Return type:

pandas.DataFrame