qdiv.stats.dbrda

qdiv.stats.dbrda(dis=None, meta=None, *, by=None, condition=None, n_axes=2, scale='site', perm_n=999, perm_seed=42, pcoa_fn=<function pcoa_lingoes>, per_var_perm=False, interactions=None, drop_first=True)[source]

Distance‑based Redundancy Analysis (db‑RDA).

This function performs constrained ordination on a distance matrix by:

  1. Converting the distance matrix into principal coordinates (PCoA) using the specified PCoA function (default: Lingoes correction).

  2. Regressing the PCoA coordinates onto explanatory variables.

  3. Extracting constrained axes, biplot scores, and variance components.

  4. Performing a global permutation test (Freedman–Lane).

  5. Optionally computing per‑variable permutation p‑values.

  6. Optionally including categorical interaction terms.

Parameters:

  • dis (pandas.DataFrame) – Square distance matrix (samples × samples). Must have matching row/column labels.

  • meta (pandas.DataFrame) – Metadata table containing explanatory variables (rows = samples).

  • 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) – Conditioning variables for partial db‑RDA. Must align with meta.

  • n_axes (int, default=2) – Number of constrained axes to return.

  • scale ({'site', 'species'}, default='site') – Scaling for biplot scores.

  • perm_n (int, default=999) – Number of permutations for the global test.

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

  • pcoa_fn (callable, default=pcoa_lingoes) – Function used to compute PCoA. Must return a dict with ‘site_scores’ and ‘eigenvalues’.

  • per_var_perm (bool, default=False) – If True, compute permutation p‑values for each predictor.

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

  • drop_first (bool, default=True) – Whether to drop the first dummy level when encoding categorical variables.

Returns:

{

‘site_scores’ : pandas.DataFrame, ‘biplot_scores’ : pandas.DataFrame, ‘variable_contributions’ : pandas.DataFrame, ‘eigenvalues’ : numpy.ndarray, ‘explained_ratio’ : numpy.ndarray, ‘total_inertia’ : float, ‘constrained_inertia’ : float, ‘unconstrained_inertia’ : float, ‘F_global’ : float, ‘p_global’ : float

}

Return type:

dict

Notes

  • The global permutation test uses the Freedman–Lane procedure.

  • Partial db‑RDA is performed by residualizing both the response coordinates and the design matrix against the conditioning variables.

  • Interaction terms are constructed before dummy encoding.