Add examples to Statistics page

[jeromekelleher]

trafficstars

It would be good to add an example of using at least some of the statistics on the Statistics page. It's a bit of a wall of text at the moment, and it's hard to get an intuitive feel for what, e.g., `allele_frequency_spectrum`` returns.

[hyanwong]

To avoid duplication we could point, for example, to https://tskit.dev/tutorials/analysing_tree_sequences.html#allele-frequency-spectra in that particular case. I'm not sure on the exact balance between examples in tutorials and in the docs. ISWYM about having a few examples there though.

[jeromekelleher]

It's tricky, I agree. We could try to draw the line between "explanatory" (tutorials) and "illustrative examples" (docs)?

[hyanwong]

It's tricky, I agree. We could try to draw the line between "explanatory" (tutorials) and "illustrative examples" (docs)?

Yes, a good distinction.I even wonder if we have an "examples" section up top (just after the "Available Statistic" section - and I want to move the "notes" to the end: I have a branch somewhere to PR with this) :

## Examples

:::{code-cell}
:"tags": ["hide-input"]
import msprime
ts = msprime.sim_ancestry(4, sequence_length=1000, recombination_rate=0.001, random_seed=1234)
ts = msprime.sim_mutations(ts, rate=0.001, random_seed=2)
print(
    "Example tree sequence has sequence length",
    int(ts.sequence_length),
    "with",
    ts.num_samples,
    "samples:",
    ts.num_trees,
    "trees &",
    ts.num_sites,
    "variable sites",
)
:::

:::{code-cell}
afs = ts.allele_frequency_spectrum(polarised=True, span_normalise=False)
print(afs) # afs[1] gives number of singletons, afs[2] doubletons, etc:::