Document reproducibility guarantees

Following up on the discussion here, it would be good to document how to get reproducible results with UMAP.

I think we should consider changing random_state in the UMAP constructor to a seed (e.g. 42, like the new transform_seed default) so that UMAP is reproducible by default.

We should document that users can set random_state to None to get faster results at the expense of reproducibility. In this mode there is no seed that would produce the same output due to the multithreading. (This was introduced in #294.)

[lmcinnes]

@tomwhite I agree with that statement, but I do believe there was some confusion (I think, in the end, I phrased the question badly). I am planning on putting together a notebook to go in the tutorial documentation that documents this clearly, and gives the justification for the choice made.

[lmcinnes]

I haven’t looked at it closely again to be sure, but my understanding is that parallel=True is essentially going to be non-deterministic due to race conditions on updating the embedding. This is, I believe, the unknown behaviour you are thinking of. In practice everything is sparse and for large datasets the odds of race conditions causing actual issues are very low. This is essentially the benefit of the SGD rather than a standard GD.