Add description of weighting schemes

Author: apragsdale

docs/stats.md

@@ -740,11 +740,33 @@ ld = ts.ld_matrix(sites=[[0, 1], [1, 2, 3]])
 print(ld)
 ```
 
-Because we implement two-locus statistics for multi-allelic data, we require
-a method for combining the statistical results from each pair of alleles into
-one summary for a pair of sites. There two methods for combining results from
-multiple alleles, `hap_weighted` and `total_weighted`, which are
-statistic-specific and not chosen by the user:
+Because we allow for two-locus statistics to be computed for multi-allelic
+data, we need to be able to combine statistical results from each pair of
+alleles into one summary for a pair of sites. We use two implementations for
+combining results from multiple alleles: `hap_weighted` and `total_weighted`.
+These are statistic-specific and not chosen by the user.
+
+Briefly, consider a pair of sites with {math}`n` alleles at the first locus and
+{math}`m` alleles at the second. Write {math}`f_{i,j}` as the statistic
+computed for focal alleles {math}`A_i` and {math}`B_j`, with haplotype weights
+{math}`(A_i B_j, A_i b_j, a_i B_j)`, where {math}`a_i` and {math}`b_j` are the
+collection of alleles that are not the focal alleles {math}`A_i` or
+{math}`B_j`, respectively. Then the weighting schemes are defined as:
+
+- `hap_weighted`: {math}`\sum_{i=1}^{n}\sum_{j=1}^{m}p(A_{i}B_{j})f_{ij}`,
+  where {math}`p(A_{i}B_{j})` is the frequency of haplotype {math}`A_{i}B_{j}`.
+  This method was first introduced in [Karlin
+  (1981)](https://doi.org/10.1111/j.1469-1809.1981.tb00308.x) and reviewed in
+  [Zhao (2007)](https://doi.org/10.1017/S0016672307008634).
+
+- `total_weighted`: {math}`\frac{1}{n m}\sum_{i=1}^{n}\sum_{j=1}^{m}f_{ij}`.
+  This method assigns equal weight to each of the possible pairs of focal
+  alleles at the two sites, taking the arithmetic mean of statistics over
+  focal haplotypes.
+
+Out of all of the available summary functions, only {math}`r^2` uses
+`hap_weighted` normalisation, with the remainder using uniform weighting
+(`total_weighted`).
 
 (sec_stats_two_locus_branch)=