DaT Parkinson's Prediction Challenge Runtime

Welcome to the runtime repository for the DaT Parkinson's Prediction Challenge!

This repository is the source of truth for the official competition runtime: the Docker image and Python environment your submission.zip runs in on the platform. It also includes tooling to build, test, and debug submissions locally before you upload them.

The repository includes:

1. Submission template (examples/template/) — function signatures to implement in your submission.
2. Example submissions — runnable demos that produce valid outputs:
   • examples/minimal/ — loads data, model assets, and writes submission.csv.
3. Runtime environment (runtime/) — the Docker image definition, entrypoint, and locked Python dependencies.

You can use this repository to:

🔧 Test your submission — Run your code in a locally running copy of the competition runtime to catch errors before submitting on the competition website.

📦 Check what packages are supported — Submissions do not have general internet access at execution time, so every dependency must be pre-installed in the official image. The specification of what packages are available during execution can be found in the runtime/ directory.

🏗️ Request changes to the official runtime — If you need a package that is not already available, open a pull request to this repository. Maintainers review proposed dependency changes here before they are published to the competition environment.

Changes to the repository are documented in CHANGELOG.md.

---

1. Quickstart

• Running a submission locally
• Prerequisites
• Data for testing

2. Additional submission guidance

• Code submission format
• Runtime network access
• Smoke tests

3. Requesting changes to the official runtime

• Runtime specification
• How to propose a new package

4. just commands

---

Quickstart

The key steps to running a submission locally, from pulling the image to producing submission.csv, are:

1. Install the prerequisites and set up testing data. We recommend downloading the smoke test data (smoke_test_data.tar.gz) from the data download page and placing its contents in the data-demo directory. Images should be in data-demo/niftis, and the submission_format.csv should be in data-demo/.

2. Open Docker. The following commands must be executed with Docker running

3. Download the official runtime image from Azure Container Registry:

   just pull

   To use a local image instead of the official image, run just build instead. A locally built image takes precedence over a pulled one. Set SUBMISSION_IMAGE in .env to force a specific image.

4. Build submission/submission.zip. To build a submission from the minimal example (examples/minimal), run:

   just pack-example minimal

   To build a submission from your own code, place your submission files (including main.py and any model assets) in submission_src/. Then run:

   just pack-submission

5. Run inference in the runtime container:

   just test-submission

   The entrypoint unzips submission/submission.zip into /code_execution/, runs python main.py, and copies the resulting submission.csv back to submission/submission.csv on your machine. Logs stream to the terminal and are written to submission/log.txt.

🎉 Congratulations! If everything worked, submission/submission.csv and submission/log.txt were created on your machine — you've completed a full local test run.

Prerequisites

To run submissions locally, you'll need:

• A clone of this repository
• Docker
• At least 21 GB of free disk space for the GPU runtime image
• just (command runner used throughout this repo)
• uv (for lockfile management and uvx tooling)

Additional requirements for GPU execution:

• NVIDIA drivers with CUDA 12
• NVIDIA Container Toolkit

Data for testing

Running just test-submission mounts a read-only data directory at /code_execution/data. On the official platform, the same path contains the competition test set.

By default, the data from data-demo/ is mounted and used, which you can populate by going to the data download page and downloading the smoke_test_data.tar.gz dataset. data-demo should have the following format:

data-demo/
├── submission_format.csv    # columns and responses expected in the final submission
└── niftis/
    └── <uid>.nii.gz     # nifti image for each observation in submission_format.csv

To test a submission using a different or larger dataset:

1. Add your data files to a folder. Your data directory must have the NifTI images in <path_to_your_data>/niftis and a submission format in <path_to_your_data>/submission_format.csv. Do not push any actual data to GitHub.
2. Point DATA_DIR to your folder when running just test-submission:

DATA_DIR=/path/to/your/data just test-submission

---

Additional submission guidance

The full details of how your submission should be structured are documented on the code submission format page. A few key tips are highlighted here.

Basic submission steps

When you make a submission on the DrivenData competition site, we run your submission inside a Docker container, a virtual operating system that allows for a consistent software environment across machines. The best way to make sure your submission to the site will run is to first run it successfully in the container on your local machine.

This is what a typical solution development flow looks like. You do all your work in /submission_src/ and then package that up testing it locally, with smoke tests, and then doing a full run.

flowchart TB
  %% --- Style tokens (DrivenData palette) ---
  classDef action fill:#C5D8F3,stroke:#17344A,stroke-width:1.5px,color:#17344A;
  classDef artifact fill:#F2F2F2,stroke:#617182,stroke-width:1.5px,color:#17344A;

  develop(Develop inference script<br/><code>submission_src/main.py</code>):::action
  pack(Package submission<br/><code>just pack-submission</code>):::action
  zip[[Create<br/><code>submission/submission.zip</code>]]:::artifact

  run(Test locally<br/><code>just test-submission</code>):::action

  smoke(Recommended: submit smoke test to platform):::action
  submit(Submit normal submission to platform):::action

  develop --> pack --> zip --> run --> smoke --> submit

Loading

Code submission format

Your code submission is a ZIP archive (for example, submission.zip) containing main.py at the root. A template is at examples/template/main.py.

just pack-submission and just pack-example use uvx rpzip to create deterministic archives. Validate the archive with just check-submission.

When you're ready to submit to the competition, upload the submission.zip you packaged (not the generated submission.csv) to the submissions page. Before you make a full competition submission, you should (1) test your submission locally using the steps above, and (2) make a smoke test submission to the platform.

Runtime network access

In the real competition runtime, all internet access is blocked. By default, the justfile commands similarly disable internet access from the container. Set BLOCK_INTERNET=false in .env or the environment to allow network access during local runs.

Smoke tests

When submitting on the platform, you will have the ability to submit "smoke tests". Smoke tests run on a small portion of the training set that is set up to emulate the test set in order to run quickly. They will not be considered for prize evaluation and are intended to let you test your code for correctness.

---

Requesting changes to the official runtime

This section is for competitors and collaborators who need to change what ships in the official competition environment — not just test a personal submission. The workflow on DrivenData's code execution platform uses the Docker image built from this repository. When that image is updated and published, new package versions become available to all competitors on the platform.

Because submissions run without general internet access, you cannot pip install at inference time. If your solution needs a library that is not already importable in the runtime, you must request it here.

Runtime specification

Documentation of currently available packages can be found in the runtime/ directory.

• Abstract Python dependencies are declared in pyproject.toml
• The uv lockfile specifying the Python environment is at uv.lock
• The test harness script is entrypoint.sh. This is what the container runs that calls your submitted code.
• The Docker image specification is given by Dockerfile

Before starting a pull request

• Confirm the package is not already available — run just build-tests and just interact-tests, then try import <package> in the test container, or check runtime/pyproject.toml.
• Prefer widely used, well-maintained packages with clear licensing.
• Be prepared to explain why the dependency is needed for the competition task.

How to propose a new package

Dependencies are managed with uv in runtime/pyproject.toml. The official runtime uses Python 3.12.

If you're new to contributing on GitHub, see GitHub's guide to contributing to projects.

1. Fork this repository and create a branch for your change.

2. Add the dependency to runtime/pyproject.toml under [project] dependencies (or the appropriate optional/dev group if it is only needed for tests).

3. Update the lockfile:

   just update-lockfile

4. Verify the lockfile is in sync:

   just check-lock

5. Build and test locally before pushing:

   just build-tests
   just run-tests
   just build

   just run-tests exercises imports and GPU-related checks in runtime/tests. If you added a package competitors will rely on, consider adding a test that imports it.

6. Commit the updated runtime/pyproject.toml and runtime/uv.lock.

7. Open a pull request to the main branch of this repository. In the PR description, explain what package you are adding and why competitors need it.

What happens after you open a PR

CI (see .github/workflows/ci.yml) will:

1. Run just check-lock to ensure the lockfile matches pyproject.toml.
2. Build the test image and run just run-tests.
3. Build the runtime Docker image.

For security reasons, administrators may need to approve the workflow run on your pull request before CI starts. Builds can take up to 30 minutes and may queue behind other jobs.

A DrivenData maintainer will review your PR. You may be asked to revise the change if tests fail, if the dependency is too heavy for the shared runtime, or if there are version-conflict concerns. Pull requests are merged only after CI passes and the team approves the change.

Once merged to main and published, the updated image becomes the basis for the official competition runtime. Competitors can then just pull to test against the same environment locally.

just commands

Run just or just help to see available images and commands. Groups from just --list:

Group	Commands
test submission locally	pull, pack-example, pack-submission, check-submission, test-submission, interact-container
development	build, update-lockfile, check-lock, debug, clean, format
tests	build-tests, run-tests, interact-tests

Use just debug to print resolved settings (data_dir, submission_image, network flags, etc.).