Small fixes and inconsistencies

Author: apragsdale

docs/stats.md

@@ -969,6 +969,12 @@ as input. Each of our summary functions has the signature
 and {math}`n_B = n_{AB} + n_{aB}`, with frequencies {math}`p` found by dividing
 by {math}`n`.
 
+Our convention is to use {math}`A,B` to denote derived alleles, and {math}`a,b`
+ancestral alleles (or other alleles, if the site is multi-allelic). For
+polarised statistics, we average statistics over all non-ancestral alleles. For
+unpolarised statistics, the labeling is arbitrary as we average over all
+alleles (derived and ancestral).
+
 `D`
 : {math}`f(n_{AB}, n_{Ab}, n_{aB}, n) = p_{AB}p_{ab} - p_{Ab}p_{aB} \, (=p_{AB} - p_A p_B)`
 

python/tskit/trees.py

@@ -10942,36 +10942,39 @@ def ld_matrix(
         :math:`r^2`) computed from sample allelic states or branch lengths.
         The resulting linkage disequilibrium (LD) matrix represents either the
         two-locus statistic as computed between all pairs of specified
-        ``sites`` ("site" mode, producing a num_sites-by-num_sites sized
-        matrix), or as computed from the branch structures at marginal trees
-        between pairs of trees at all specified ``positions`` ("branch" mode,
-        producing a num_positions-by-num_positions sized matrix).
+        ``sites`` (``"site"`` mode, producing a
+        ``len(sites)``-by-``len(sites)`` sized matrix), or as computed from the
+        branch structures at marginal trees between pairs of trees at all
+        specified ``positions`` (``"branch"`` mode, producing a
+        ``len(positions)``-by-``len(positions)`` sized matrix).
 
-        The sites considered for "site" mode defaults to all sites (which may
+        The sites considered for ``"site"`` mode defaults to all sites (which may
         result in a very large matrix!), but can be restricted using
-        the ``sites`` argument. Sites can be passed as a list of lists,
-        specifying the ``[[row_sites], [col_sites]]``, resulting in a
+        the ``sites`` argument. Sites must be passed as a list of lists,
+        specifying the ``[row_sites, col_sites]``, resulting in a
         rectangular matrix, or by specifying a single list of ``[sites]``, in
         which a square matrix will be produced (see
-        :ref:`sec_stats_two_locus_site` for examples).
+        :ref:`sec_stats_two_locus_site` for examples). Here, ``sites``,
+        ``row_sites``, and ``col_sites`` are each lists of site indexes.
 
-        Similarly, in the branch mode, the ``positions`` argument specifies
+        Similarly, in the ``"branch"`` mode, the ``positions`` argument specifies
         genomic coordinates at which the expectation for the two-locus statistic
         is computed, given the local tree structure.
         (See :ref:`sec_stats_two_locus_branch` for explanation of in what sense
         this is an expectation.) This defaults to computing
-        the LD for each pair of distinct trees, which is equivalent to passing in
-        the leftmost coordinates of each tree's span (since intervals are closed on
+        the LD for each pair of distinct trees (this is equivalent to passing in
+        the leftmost coordinates of each tree's span, since intervals are closed on
         the left and open on the right). Similar to the site mode, a nested list
         of row and column positions can be specified separately (resulting in a
         rectangular matrix) or a single list of a specified positions results
         in a square matrix (see :ref:`sec_stats_two_locus_branch` for
-        examples).
+        examples). Like ``sites``, the ``positions`` must be specified as a list
+        of lists.
 
-        Some LD statistics are defined for two sample sets as well as within a
-        single set of samples. If the ``indexes`` argument is specified, then
+        Some LD statistics are defined for both within a single set of samples
+        and for two sample sets. If the ``indexes`` argument is specified, then
         ``indexes`` specifies the indexes of the sample sets in the
-        ``sample_sets`` list between which to compute LD. For example, this
+        ``sample_sets`` list between which to compute LD. For instance, this
         results in a 3D array whose ``[k,:,:]``-th slice contains LD values
         between ``sample_sets[i]`` and ``sample_sets[j]``, where ``(i, j)`` is
         the ``k``-th element of ``indexes``.
@@ -11008,16 +11011,18 @@ def ld_matrix(
             computed. Defaults to "site", can be "site" or "branch".
         :param str stat: A string giving the selected two-locus statistic to
             compute. Defaults to "r2".
-        :param list sites: A list of sites over which to compute LD. Can be
-            specified as a list of lists to control the row and column sites.
-            Only applicable in site mode. Specify as
-            ``[[row_sites], [col_sites]]`` or ``[all_sites]``.
+        :param list sites: A list of lists of sites over which to compute an
+            LD matrix. Can be specified as a list of lists to control the row
+            and column sites. Only available in "site" mode. Specify as
+            ``[row_sites, col_sites]`` or ``[all_sites]``.
             Defaults to all sites.
-        :param list positions: A list of genomic positions where expected LD is
-            computed. Only applicable in branch mode. Can be specified as a list
-            of lists to control the row and column positions. Specify as
-            ``[[row_positions], [col_positions]]`` or ``[all_positions]``.
-            Defaults to the leftmost coordinates of all trees.
+        :param list positions: A list of lists of genomic positions where
+            expected LD is computed based on tree topologies and branch
+            lengths. Only applicable in "branch" mode. Specify as a list of
+            two lists to control the row and column positions, as
+            ``[row_positions, col_positions]``, or ``[all_positions]``.
+            Defaults to the leftmost coordinates of all trees and computes
+            LD between all pairs of trees.
         :param list indexes: A list of 2-tuples or a single 2-tuple, specifying
             the indexes of two sample sets over which to compute a two-way LD
             statistic. Only :math:`r^2`, :math:`D^2`, and :math:`\widehat{D^2}`