Reproducibility

Clinical trials require that randomization sequences can be reproduced for auditing and regulatory review. This page explains how the system achieves deterministic, reproducible assignments.

Random Number Generator

The system uses NumPy’s PCG64 generator, a modern, statistically robust pseudorandom number generator. The generator is seeded once at study initialization using the starting_seed parameter in the configuration file.

"My Clinical Trial":
    starting_seed: 100
    # ...

Given the same seed, the same sequence of urn draws (and therefore treatment assignments) will occur, provided participants arrive in the same order with the same factor levels.

What Determines the Sequence

The assignment for participant n depends on:

  1. The seed — set once in config.yaml.

  2. The order of arrivals — participant n consumes the n-th random draw from the generator.

  3. The factor levels — these determine which urn is selected, and therefore which ball composition drives the draw.

  4. The urn state — which reflects all prior assignments (balls added via alpha and beta after each draw).

If any of these differ between two runs, the sequences will diverge from that point onward.

Reproducing a Study

To reproduce the exact assignment sequence from a completed study:

  1. Use the same config.yaml (same seed, treatments, factors, urn parameters).

  2. Re-enter participants in the same order with the same factor levels.

  3. Ensure no plugin modifies assignments differently.

The system stores every assignment in the database with a timestamp, participant ID, factor levels, treatment arm, and the user or plugin that triggered it. This audit trail can be exported via the CLI:

urn -s "My Clinical Trial" export --output assignments.csv

Or via the REST API:

curl "http://localhost:5000/study_participants?api_key=YOUR_KEY&study=My+Clinical+Trial"

Seed Selection

Choose a seed that is:

  • Documented — record it in your study protocol before enrollment begins.

  • Unpredictable — do not use simple values like 0 or 1. A large arbitrary integer (e.g., 839217) is sufficient.

  • Fixed — never change the seed after enrollment starts. Doing so would break the reproducibility of all subsequent assignments.

Warning

Changing the seed, urn parameters (alpha, beta, w), or the imbalance measure (D) mid-study will alter the assignment probabilities for all future participants and break reproducibility of the sequence.