Skip to content

Where to run it

Registry Forge is plain Python, so it runs anywhere Python 3.10 or later runs: a laptop, a Jupyter server, Google Colab, Amazon Web Services (AWS) or another approved platform. The question to settle first is where the records are allowed to go, because that decides which of these environments can be used for real participant data and which are only for the invented cohort.

Confirm first · Your computer · Jupyter · Google Colab · AWS · Other platforms · Sources

Confirm before you start

An environment here means the computer or cloud service where the code runs and the records are stored while it runs: your own computer, an institutional server, a Jupyter server, Colab Enterprise, Amazon SageMaker AI or a Databricks workspace, for example. Work through this list with the registry's study team and information security office before any real record is copied into one. The invented cohort needs none of it.

Confirm Why
The protocol, the Institutional Review Board (IRB) determination and any data use agreement allow participant records to be processed in that environment The records are identified health information; the approvals say where they may be stored and processed
For a cloud service, the institution has a business associate agreement (BAA) with the provider and the specific service is on the provider's list of services the BAA covers A BAA covers listed services only; a service that is not listed is not covered even in the same account
The information security office has approved the environment for identified health data, including disk encryption and who can sign in Personal laptops and free notebook services are usually not approved
Python 3.10 or later is available, and packages can be installed from the internet, an internal mirror or wheels copied in run_all.py makes no network calls, but installing packages does
There is storage for the inputs and the outputs, and a decided place for each output folder: the run folder and restricted/ stay in the approved environment; reports/ is reviewed in full before anything leaves Decoded text and the outputs can be larger than the delivered files, and each folder has a different privacy level
The data cut-off date is chosen, and vital_status.csv is ready if deaths come from outside the records Survival figures need a fixed end date
A practice run on the invented cohort has been done in the same environment It shows every output and confirms the install before real records are touched

Back to top

Your own computer

Good for the sample data, the invented cohort and learning the outputs. Use it for real records only if the computer is approved for identified health data.

unzip RegistryForge.zip
cd RegistryForge
python -m pip install -r requirements.txt
python -m pytest -q tests                                   # confirms the install
python examples/make_synthetic_cohort.py --out practice_run
python pipeline/run_all.py --base-dir practice_run --cutoff 2026-10-31

On Windows, use py in place of python. Open pipeline/dashboard.html in a browser and load practice_run/dashboard_data.json to see the record viewer.

Back to top

Jupyter

Works the same in JupyterLab, Jupyter Notebook and an institutional JupyterHub.

  1. Unzip RegistryForge.zip where the notebook server can see it.
  2. Open notebooks/run_registry_forge.ipynb (also on the Downloads page).
  3. Check the settings cell. USE_INVENTED_COHORT = True runs the invented cohort; set it to False and RUN_DIR to your run folder for real records, once the environment is approved.
  4. Run the cells in order. The notebook checks the Python version, packages and free disk space, installs missing packages, runs everything and lists where each output went.

To run from a notebook without the run notebook, call the command line from a cell: !python pipeline/run_all.py --base-dir practice_run --cutoff 2026-10-31.

Back to top

Google Colab

The free Colab is a quick way to try the pipeline on the invented cohort with nothing installed on your computer. It is not for real participant records: the free Colab is a consumer service, and Google lists Colab Enterprise, not the free Colab, among the Google Cloud services its BAA covers (checked November 2026 on Google's HIPAA compliance page; see Sources).

  1. Download run_registry_forge.ipynb.
  2. Open colab.research.google.com, choose File, then Upload notebook, and pick the file.
  3. Run the cells in order. The notebook downloads the pipeline from this site; if the download is blocked, it asks you to upload RegistryForge.zip instead.
  4. Files in a Colab runtime are deleted when the session ends. Download any report you want to keep (the last cell shows how).

For real records on Google Cloud, Colab Enterprise in a project covered by the institution's Google Cloud BAA can run the same notebook, if the institution has approved it.

Back to top

Amazon Web Services

Run the pipeline in the AWS account that already holds the exports, so the records never leave it. AWS lists Amazon SageMaker AI and Amazon EC2 among its HIPAA eligible services; the account owner accepts the AWS BAA in AWS Artifact, and SageMaker Studio Lab is excluded from eligibility (checked November 2026; see Sources).

What to confirm in AWS first

  • The AWS BAA is accepted for the account, and the account is designated for protected health information under the institution's AWS policy.
  • An IAM role for the notebook or instance can read the exports in S3 and write to an encrypted output prefix, and nothing else.
  • Whether the environment has internet access. Without it, install packages from an internal mirror or from wheels copied into S3 (see Installation).

SageMaker AI (JupyterLab)

  1. Copy RegistryForge.zip into an S3 prefix the registry controls, then into the JupyterLab space: aws s3 cp s3://your-bucket/tools/RegistryForge.zip . and unzip it.
  2. Open notebooks/run_registry_forge.ipynb and run it once on the invented cohort.
  3. Copy the export into the working directory (for example aws s3 cp --recursive s3://your-bucket/registry-export/ run_2026_10/, so that run_2026_10/CCDA and FHIR data/ holds the chunk files and run_2026_10/uuid_mapping.csv the mapping), set USE_INVENTED_COHORT = False and RUN_DIR = 'run_2026_10', and run it again.
  4. Copy outputs back to the encrypted output prefix: aws s3 cp --recursive run_2026_10/ s3://your-bucket/registry-forge-runs/run_2026_10/. Keep restricted/ there; review reports/ in full before anything leaves.

EC2

The same steps from a terminal: copy and unzip the package, python3 -m pip install -r requirements.txt, run the practice cohort, then python3 pipeline/run_all.py --base-dir run_2026_10 --cutoff 2026-10-31 --vital-status run_2026_10/vital_status.csv. Use an encrypted volume for the run folder.

The Quickstart and Data extraction (Databricks) pages describe the working directory the pipeline reads.

Back to top

Other platforms

The same pattern works on any platform that runs Python 3.10 or later and that the institution has approved for identified health data: copy in the zip, install requirements.txt, run the invented cohort once, then run run_all.py or the notebook on a run folder.

Platform Notes
Microsoft Azure Machine Learning Run the notebook in a compute instance; keep the run folder on storage covered by the institution's agreement with Microsoft
Databricks The Databricks export writes the three CSV files the pipeline reads. To run the pipeline there too, copy them from a volume to the driver's local disk, run run_all.py with %sh or from the notebook, and copy outputs back; the pipeline reads ordinary files, not Spark tables
Posit Workbench, an institutional HPC cluster or a secure research enclave Use a Python 3.10 or later environment; on a cluster, run run_all.py as one job, since the pipeline runs on a single machine

Back to top

Sources

The service lists change; check them again before relying on them.

Back to top