[andrewkern]

Fixes #322.

A pair of samples with no site called in both has no distance. Before this PR, these functions gave such a pair 0.0, which reads as "identical" (or, for IBS, as "share nothing"):

• pairwise_diffs_haploid and pairwise_diffs_diploid;
• decomposition.pairwise_distance;
• relatedness.ibs.

The distance moments and pcoa then used the false value. This PR gives these pairs NaN, the convention of #321. Each consumer skips the NaN pairs or raises an error.

Behavior changes

• Distances: a pair with no jointly called site is NaN in the four functions above. For ibs, this applies to the eager, streaming and empty-source paths. The diagonal stays 1.
• dist_var, dist_skew, dist_kurt (scalar and windowed dist_* columns) skip the NaN pairs. A moment needs 2, 3 or 4 defined pairs. With fewer, the moment is NaN when missing data caused the shortage, and 0.0 when the sample itself is too small (the rule before this PR).
• pcoa raises ValueError on a NaN distance. The message counts the NaN pairs and rows and names the two sources of NaN (pairwise_distance, pc_dist).
• lostruct leaves out of the MDS each window that pc_dist cannot compare (too few variants, or no variation when normalize is set), and gives that window a NaN mds row. Before, such a window made pcoa fail with LinAlgError. lostruct raises ValueError when fewer than two windows can be compared, or when corners are requested and the MDS has fewer than two dimensions. corners now gets the first two MDS axes, so n_components other than 2 works.
• pairwise_diffs_diploid (and so dist_moments on a GenotypeMatrix) accepts a population given as a list of rows. Before, this raised TypeError.

Refactors with no change in value

• _pairwise_diffs_matrix_gpu holds the NaN rule in one place. Its 'normalize' mode serves both pairwise_diffs functions. A new 'scale' mode serves pairwise_distance and divergence.pairwise_distance_matrix, which had their own copies of the scaling. The return_joint_valid parameter is gone, because no caller needs it now.
• For pairs with at least one jointly called site, all values are the same as before.

Left as they are, on purpose

• The pc_dist to pcoa snippet in quickstart.rst and examples/local_pca.py. Their SNP windows always have enough variants, so a NaN row cannot occur there.
• dist_moments still computes on the host with NumPy. That is dist_moments computes the distance moments with NumPy on the host #336.

Docs

The changelog, missing_data.rst, features.rst and the local PCA tutorial describe the NaN rule. The tutorial now filters the NaN mds rows before it plots, and its corner indices count all windows, as lostruct's do.

Tests

tests/test_undefined_pair_distances.py covers:

• haploid and diploid distances;
• the moments, against a SciPy reference;
• pairwise_distance for each metric, and the pcoa errors;
• the fused and chunked windowed paths;
• eager and streaming IBS, including missing_data='exclude';
• lostruct on three engine paths, including the jackknife, and its guards.

Each new test fails on main. Test references that used 0.0 for an undefined pair now use NaN.

Full suite: 2034 passed, 81 skipped, 15 xfailed. ruff check pg_gpu/ tests/ examples/ passes.

[nspope]

This looks good to me; pulled it down and don't see any issues in practice.