Unifying stat method desc and linking to math summary

[gregorgorjanc]

I was working through the stats tutorial at https://tskit.dev/tutorials/analysing_tree_sequences.html (incoming PR) and thought that linking stats/math summaries (https://tskit.dev/tskit/docs/stable/stats.html#summary-functions) to method docs would be very useful.

I also followed a style from the diversity method doc (what is the stat, then links to sample_sets, windows, ...).

@petrelharp can you have a look at this PR?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.82%. Comparing base (bc5a73c) to head (6371edc).
Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3005      +/-   ##
==========================================
+ Coverage   89.81%   89.82%   +0.01%     
==========================================
  Files          29       29              
  Lines       31979    31995      +16     
  Branches     6190     6195       +5     
==========================================
+ Hits        28721    28739      +18     
+ Misses       1861     1859       -2     
  Partials     1397     1397              

Flag	Coverage Δ
c-tests	86.69% <ø> (ø)
lwt-tests	80.78% <ø> (ø)
python-c-tests	89.05% <ø> (ø)
python-tests	99.04% <100.00%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/tskit/trees.py	98.80% <100.00%> (ø)

... and 1 file with indirect coverage changes

[petrelharp]

Suggested change

	Please see the :ref:`summary functions <sec_stats_summary_functions>`
	See the :ref:`summary functions <sec_stats_summary_functions>`

For consistency.

[petrelharp]

I don't actually think the "summary function" is a good place to refer people to here. That is a definition, but it only makes sense if someone understands How It All Works. The approach we've taken in other statistics is to provide a more plain (but equivalent) definition. I think here the thing to do is to just refer to the docs for genetic_relatedness, because this function's notion of genetic relatedness is the same as that one.

[petrelharp]

In general I like the rearrangments, but I don't think we should add "please see summary functions for a precise definition". Instead, we should make what's said there in the documentation precise enough, if it isn't already? I am pretty sure that what's there for diversity, for instance, is precise - did you find it ambiguous? The 'summary function' definition is nice and concrete once you understand it, but most readers won't be on board with this. Some other way of referring to the summary functions could be helpful but more like "if you want the computational details, see XXX"?

[gregorgorjanc]

@petrelharp I followed your suggestions in the last commit.

I thought adding the link to computational/mathematical definition would be useful to provide concrete/mathematical detail of what is calculated. This makes things concrete, but since it's only a link, it does not overwhelm a user (I agree that simple descriptive text should be preferred). Also, you have written these math details for some stats, so adding these links exposes/leverages that part of the doc (most users will only look at function docs and won't go over the whole stats doc to find math detail).

Happy to iterate.