biocore/scikit-bio — pull request #657 by wasade (2014-09-03 19:14:04+00:00)
Title: Uneven subsample

This PR came about from needing a solution to the following problem:

- given demultiplexed sequences, where you do not know the number of sequences, samples or sequences per sample
- randomly keep up to `k` sequences (as opposed to exactly `k` sequences)

In other words, we want to randomly select up to `k` items from bin `n_i`, where `k` is the number of items, `n` is the number of bins, and `i` is the bin number. We need to allow for the case where bin `n_i` does not have `k` items, and still return it (which is the primary difference with `subsample`).

I don't know if `uneven_subsample` is the best name for this and would be curious to hear opinions. The method has been generalized from our need in qiita so it can be applied to arbitrary iterators.

This method takes a similar approach to Fisher-Yates in that each item can only be "swapped" a single time, and it should be assured that each sequence within each bin has an equal probability of being retained regardless of the number of sequences or the number of bins.