Platform R: Flywheel

Platform R has access to two Flywheel services:

• UW Health's (used by Radiology and others)
• WRC's Flywheel's cloud instance

Contact your lab manager or project lead for the Flywheel URL for your project.

• Command Line Interface
• Software Development Kit
• Troubleshooting Flywheel File Download
  • Recommended Approach
  • Example: Download via Direct HTTPS
  • Additional Notes
• Related Documentation

Command Line Interface

The installer for the newest version of the Flywheel command line interface (CLI) talks to several websites to which Platform R does not have access. The Platform R team will continue to look into options for installing the new CLI in a secure and air gapped environment.

The legacy version of the CLI is deprecated by Flywheel due to compliance concerns and will eventually be replaced by the new version. It can still be downloaded following the instructions on the Flywheel website. Download the file to your Restricted Research Drive, then unpack and run into your Platform R group space.

Software Development Kit

The Flywheel SDK is available in Python, though not through conda directly:

conda create --name flywheel-example python=3.14
conda activate flywheel-example
pip3 install flywheel-sdk

Then within this Python you can import flywheel.

Troubleshooting Flywheel File Download

The Flywheel Python SDK provides two separate capabilities:

• Navigation — looking up projects, subjects, sessions, acquisitions, and file metadata
• File transfer — downloading and uploading files

The Flywheel SDK's file transfer methods can fail with timeout errors on certain Flywheel instances, even when project navigation and metadata calls work without issue. This is caused by how the network proxy handles download tickets in those environments.

Some symptoms of proxy problems are:

• SDK f.download() raises a timeout exception.
• Downloaded files are unexpectedly small (e.g. tens of bytes) instead of the expected image size.
• SDK listing and metadata calls succeed, but file transfer fails.
• Behavior is inconsistent across runs or only affects certain files.

Note: If a failed download left a small/corrupt file on disk, re-running the script will silently skip it because the file already exists. Delete suspect files before retrying.

Recommended Approach

Use the Flywheel SDK only for authentication and hierarchy traversal. Replace SDK file transfer calls with a direct HTTPS request using your API key in the authorization header.

This approach uses only standard public libraries (requests, flywheel-sdk) and works reliably across Platform R environments.

Example: Download via Direct HTTPS

Copy and adapt the following script. Update GROUP, PROJECT_LABEL, and OUT_DIR before running, as well as SUBJECT_LABEL, SESSION_LABEL, ACQ_LABEL, and FILE_NAME seen halfway through the script.

import os
import requests
import flywheel

# Set your API key as an environment variable before running:
# export FLYWHEEL_API_KEY="flywheelaz.uwhealth.org:your-key-here"
API_KEY = os.environ["FLYWHEEL_API_KEY"]
fw = flywheel.Client(API_KEY, request_timeout=1000)

GROUP         = "your_group_id"    # Flywheel group ID
PROJECT_LABEL = "your_project"     # Project label
OUT_DIR       = "./downloads"      # Local destination folder


def _get_url_and_headers(fw_client, file_entry):
    """Build a direct download URL and auth headers from SDK metadata."""
    host    = fw_client.get_config()["site"]["api_url"]
    api_key = fw_client._fw.api_client.configuration.api_key.get("Authorization", "")
    headers = {"Authorization": f"scitran-user {api_key}"}
    url     = f"{host}/{file_entry.parent_ref['type']}s/{file_entry.parent_ref['id']}/files/{file_entry.name}"
    return url, headers


def download_file(fw_client, file_entry, local_path):
    """Download a single file using direct HTTPS instead of the SDK transfer method."""
    url, headers = _get_url_and_headers(fw_client, file_entry)
    with requests.get(url, headers=headers, stream=True, timeout=(10, 1000)) as r:
        r.raise_for_status()
        with open(local_path, "wb") as out:
            for chunk in r.iter_content(chunk_size=8 * 1024 * 1024):
                if chunk:
                    out.write(chunk)


# --- Sample download: fetches one specific file by name ---
SUBJECT_LABEL = "your_subject"
SESSION_LABEL = "your_session"
ACQ_LABEL     = "your_acquisition"
FILE_NAME     = "your_file.nii.gz"

project    = fw.lookup(f"{GROUP}/{PROJECT_LABEL}")
fw_path    = f"{GROUP}/{PROJECT_LABEL}/{SUBJECT_LABEL}/{SESSION_LABEL}/{ACQ_LABEL}/{FILE_NAME}"
file_entry = fw.resolve(fw_path)["path"][-1]
os.makedirs(OUT_DIR, exist_ok=True)

dest = os.path.join(OUT_DIR, FILE_NAME)
print(f"Downloading: {fw_path}")
try:
    download_file(fw, file_entry, dest)
    print(f"Saved: {dest}")
except Exception as e:
    print(f"Failed: {file_entry.name} — {e}")

Additional Notes

• API key security: Never hardcode your API key in the script. Always pass it through an environment variable as shown above.
• If you run into other problems with the Flywheel SDK please let us know.

Related Documentation

• Flywheel SDK Documentation