sample frequency spectrum

Add support for site frequency spectrum. Needs a specific C algorithm for efficiency.

I think we should call it the “sample_frequency_spectrum”, since it’s counting samples. site_frequency_spectrum is actively misleading I think, as well as leading to absurd function names like site_site_frequency_spectrum and branch_site_frequency_spectrum. I’m open to other names though.

See also #196.

[petrelharp]

with n pops, there are n ways of folding (and the various folded spectra are not equivalent)

Uh-oh, you are right. I didn’t think about this hard enough, and suggested above a folding method that collapses [i1,i2] + [n1-i1, i2] + [i1, n2-i2] + [n1-i1, n2-i2]; but this is not correct, because (for instance) [i,i] and [n1-i, i] are clearly different, since the two pops agree in the first case but disagree in the second.

But, about nonequivalence: if we don’t know the ancestral allele, all that can be said is that we can’t distinguish [i1, i2, ..., ik] from [n1-i1, n2-i2, ..., nk-ik]; so isn’t the right thing to do to return a “lower triangular” array, e.g. with the upper triangle zeroed? I.e., the output has out[i1, ..., ik] = 0 if i1 + ... + ik > (n1 + ... + nk)/2? (need to check that)

Thanks for catching this, @KLohse!

[KLohse]

I agree that both the 0th and the nth need to be included for consistency; both categories become relevant for the general case of the AFS for multiple pops. Thinking about implementing the folding of the AFS in the most general way; it seems that one would have to specify a ref population with respect to which ASF the folding happens. In other words, with n pops, there are n ways of folding (and the various folded spectra are not equivalent).