qdiv.model.beta_ntiq

qdiv.model.beta_ntiq(obj, distmat, *, q=1.0, iterations=999, include_conspecifics=False, randomization='features', use_tqdm=True, random_state=None, **kwargs)[source]

Computes beta-MNTD_q (mean nearest-taxon distance with q-weighted abundances) for all sample pairs, then contrasts the observed matrix against a null distribution generated by randomization:

  • randomization=”features”: permute feature identities (rows) identically across samples

  • randomization=”abundances”: shuffle abundances within each sample (column-wise)

The null distribution is aggregated online using Welford updates, yielding per-pair null mean, null std, tie-aware p-index, and standardized effect size.

Parameters:

  • obj (MicrobiomeData | dict | Any) – Input with at least an abundance table under key ‘tab’.

  • distmat (pandas.DataFrame) – Square distance matrix (features × features) whose index/columns include tab.index.

  • q (float, default=1.0) – Diversity order used to weight relative abundances (applied only to strictly positive entries).

  • iterations (int, default=999) – Number of randomization iterations used to build the null distribution.

  • include_conspecifics (bool, default=False) – Determines whether conspecifics (identical features shared between samples) are allowed to contribute zero-distance matches in the nearest-taxon calculation.

  • randomization ({"features", "abundances"}, default="features") –

    Randomization strategy for the null model:

    • ”features”: permute feature identities identically for all samples (tip-label permutation).

    • ”abundances”: shuffle abundances within each sample (column-wise permutation).

  • use_tqdm (bool, default=True) – Use tqdm for progress bars (a lightweight stub is used if tqdm is unavailable).

  • random_state (int | numpy.random.Generator, optional) – Random seed or Generator for reproducibility.

Returns:

Full (samples × samples) matrices:

  • ’beta_MNTDq’ : observed beta-MNTD_q

  • ’null_mean’ : mean of null beta-MNTD_q

  • ’null_std’ : std of null beta-MNTD_q

  • ’p’ : (count(null < observed) + 0.5 * ties) / iterations

  • ’ses’ : (null_mean - observed) / null_std

Diagonal entries are set to NaN.

Return type:

dict of pandas.DataFrame

Notes

  • Returns a dataframe with observed beta_MNTDq if iterations=0, otherwise a dictionary is returned

  • A p value close to zero means that the observed MNTD between samples is lower than the null expectation

  • A p value close to one means that the observed MNTD between samples is higher than the null expectation

  • A positive ses means that the observed MNTD between samples is lower than the null expectation

  • A negative ses means that the observed MNTD between samples is higher than the null expectation

References

Webb et al. (2002) American Naturalist. Stegen et al. (2013) ISME Journal.