Running Multiple Studies

Running Multiple Studies

A single installation can host multiple independent studies. Each study has its own configuration, database tables, urns, and randomization history.

Defining Multiple Studies

Add multiple top-level keys to your config.yaml:

db: sqlite:///urn-randomization.db

"Diabetes Prevention Trial":
    starting_seed: 42
    treatments:
        - Metformin
        - Placebo
    factors:
        bmi_category:
            ["Normal", "Overweight", "Obese"]
        age_group:
            ["30-50", "51-70"]

"Heart Failure RCT":
    starting_seed: 100
    target_enrollment: 300
    treatments:
        - Drug A
        - Drug B
        - Standard Care
    factors:
        nyha_class:
            ["II", "III", "IV"]
        sex:
            ["Male", "Female"]
        ejection_fraction:
            ["<40%", "40-55%"]

Each study creates its own pair of database tables ({name}_config and {name}_history), so they are completely independent.

Selecting a Study

Web Application

The Flask app serves one study at a time, controlled by the URAND_STUDY_NAME environment variable:

export URAND_STUDY_NAME="Diabetes Prevention Trial"
flask run

To switch studies, change the variable and restart the server.

CLI

The CLI accepts a study name with the -s flag:

# Randomize in the diabetes study
urn -s "Diabetes Prevention Trial" randomize --id P001 --user admin

# Export from the heart failure study
urn -s "Heart Failure RCT" export hf_data.csv

REST API

The API accepts the study name as a query parameter:

# Query the diabetes study
curl "http://localhost:5000/study_config?api_key=KEY&study=Diabetes+Prevention+Trial"

# Randomize in the heart failure study
curl -X POST "http://localhost:5000/study_participants?\
api_key=KEY&study=Heart+Failure+RCT&id=HF001&nyha_class=III&sex=Male&ejection_fraction=<40%25"

Running Multiple Web Instances

If you need simultaneous web access to different studies, run multiple Flask instances on different ports:

# Terminal 1
URAND_STUDY_NAME="Diabetes Prevention Trial" flask run --port 5000

# Terminal 2
URAND_STUDY_NAME="Heart Failure RCT" flask run --port 5001

Or use a reverse proxy (Nginx, Caddy) to route different URL paths to different instances.

Shared vs. Separate Databases

Shared database (default)

All studies use the same SQLite file. Tables are namespaced by study name, so there's no collision. This is simpler to manage.

db: sqlite:///urn-randomization.db

Separate databases

For stronger isolation (e.g., different access controls per study), use separate database files:

# config-diabetes.yaml
db: sqlite:///diabetes.db
"Diabetes Prevention Trial":
    ...

# config-heartfailure.yaml
db: sqlite:///heartfailure.db
"Heart Failure RCT":
    ...

Run each instance with its own config:

URAND_CONFIG_FILE=config-diabetes.yaml URAND_STUDY_NAME="Diabetes Prevention Trial" flask run --port 5000
URAND_CONFIG_FILE=config-heartfailure.yaml URAND_STUDY_NAME="Heart Failure RCT" flask run --port 5001

User Management Across Studies

Users are shared across all studies in the same Flask database. A user registered with flask add_user can access any study served by that instance. The user_to_study association table exists for future per-study access control but is not currently enforced.

Tips

• Use different seeds for each study to ensure independent randomization sequences.
• Back up per-study — if using separate databases, each .db file can be backed up independently.
• Monitor independently — each study's dashboard shows only its own enrollment and assignments.