# Make `_jitter()` accept an optional `random_state` parameter

[khushthecoder]

Problem

_jitter() in util.py calls np.random.uniform() using the global RNG, meaning results are non-reproducible even when the user passes random_seed to the calling function. The random_seed parameter exists in the public API (e.g., cohort_diversity_stats) but is never threaded through to _jitter().

util.py:903

def _jitter(a, fraction):
    r = a.max() - a.min()
    return a + fraction * np.random.uniform(-r, r, a.shape)  # global RNG!

Proposed Fix

Add an optional random_state parameter defaulting to np.random. Called from pca.py lines 403–509.

Impact

Makes PCA plots reproducible when users set random_seed.

[khushthecoder]

Update: I'm currently working on a fix for this. Please check back before opening a PR — I'll post a link here once it's ready. Thanks!

[khushthecoder]

Hi @jonbrenas, I have opened a PR for this issue. Could you please review it? #1218

[jonbrenas]

Hi @khushthecoder, why would you want the results to be reproducible? If the points are scattered on the scatter plot, isn't that good enough?

[khushthecoder]

Hi @jonbrenas, great question! You're right that the primary purpose of jitter is just to spread out overlapping points, and for that, any random scatter works fine. However, there are a few practical reasons reproducibility is valuable:

1. Debugging & communication — When a researcher spots something unexpected in a PCA plot and shares it with a collaborator or opens an issue, the collaborator should be able to reproduce the exact same plot. With non-reproducible jitter, the point positions shift every time, making it harder to discuss specific observations.
2. Notebooks & reports — In Jupyter notebooks or automated reports, re-running cells currently produces visually different plots each time, even with random_seed set. Users expect random_seed to make the output deterministic — the current behavior breaks that expectation.
3. Testing — Deterministic output makes it possible to write reliable regression tests for plotting functions that use jitter.
4. No downside — The change is fully backward-compatible. When no random_state is passed, _jitter() defaults to np.random (the global RNG), so existing behavior is completely unchanged. It only becomes deterministic when the caller explicitly opts in by passing a seeded generator.

The core issue (#1217) is that plot_pca_coords already accepts a random_seed parameter, but the jitter step was ignoring it because _jitter() used np.random.uniform() directly instead of the seeded RNG. So this PR is really about making random_seed actually work as users would expect.

Happy to discuss further or adjust anything!

[jonbrenas]

Ok, fair enough! :)