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.  
Ah, I see. In that case, yes, it is the same but I believe you'd need to
unroll the generator.

On Mon, Nov 17, 2014 at 12:48 PM, Jorge Cañardo Alastuey <
notifications@github.com> wrote:

> In skbio/stats/_subsample.py:
>
> > +                     bin_f=None):
> > +    """Get a random subset of items per bin
> > +
> > +    Parameters
> > +    ----------
> > +    iter_ : Iterable
> > +        The iterable to walk over.
> > +    maximum : unsigned int
> > +        The maximum number of items per bin.
> > +    minimum : unsigned int, optional
> > +        The minimum number of items per bin. The default is 1.
> > +    random_buf_size : unsigned int, optional
> > +        The size of the random value buffer. The default is 100000.
> > +    bin_f : function, optional
> > +        Method to determine what bin an item is associated with. If None (the
> > +        default), then all items are considered to be part of the same bin.
>
> Right, so by default bin_f(anything) == True, so the variable result
> becomes {True: "heap with all items of at most maximum lenght ordered by
> a rand int"}, and then all items in the heap are yielded. I fail to see
> how this isn't equivalent to randomly choosing from iter_ directly. Am I
> misinterpreting the docs, the code?
>
> However, the items in iter_ may not all be associated with the same bin,
> in the case of walking over a demultiplexed sequence file, which is why
> this is exposed.
>
> And to do so you need to pass a binning function different from the
> default, no?
>
> —
> Reply to this email directly or view it on GitHub
> <https://github.com/biocore/scikit-bio/pull/657/files#r20459599>.
>