qdiv.stats.pcoa_lingoes

qdiv.stats.pcoa_lingoes(dis)[source]

Perform Principal Coordinates Analysis (PCoA) using the Lingoes correction.

The Lingoes correction transforms a non‑Euclidean distance matrix into a Euclidean one by adding a constant to all squared distances, ensuring that all eigenvalues are non‑negative. PCoA is then performed on the corrected matrix to obtain principal coordinate axes.

Parameters:

dis (pandas.DataFrame) – Square distance matrix (rows and columns represent samples). Values must be non‑negative and the matrix must be symmetric.

Returns:

  • coords_df (pandas.DataFrame) – Principal coordinate scores (samples × axes), ordered by decreasing eigenvalue magnitude.

  • eigvals (pandas.Series) – Eigenvalues associated with each axis (only the positive eigenvalues after Lingoes correction).

  • pct_explained (pandas.Series) – Percentage of total variance explained by each axis (positive eigenvalues only).

  • total_variance (float) – Sum of all positive eigenvalues after correction.

Return type:

DataFrame

Notes

  • The Lingoes correction is applied only if negative eigenvalues are detected.

  • The output coordinates are centered and scaled according to standard PCoA conventions.