Skip to content

Flywheel Data Hierarchy

Flywheel organizes all data in a strict tree-shaped hierarchy of containers. Every piece of data — a scan file, a derived result, a piece of metadata — belongs to exactly one location in this tree. Understanding the hierarchy is prerequisite to navigating the SDK, writing queries, or structuring automated workflows.

Why a Hierarchy

The hierarchy maps to how biomedical research data is actually collected: a research institute (Group) runs multiple studies (Projects), each study enrolls individual participants (Subjects), each participant attends one or more visits (Sessions), and each visit produces one or more acquisitions on a scanner (Acquisitions). This structure is rigid by design — the SDK enforces it and uses it to resolve paths, apply permissions, and scope searches.

Container Types

Flywheel defines six container types relevant to the SDK. Five form the strict parent-child hierarchy; one (Analysis) is a sub-container that can attach to most hierarchy levels.

Container Python class Primary ID field Label field Notable attributes
Group Group _id label permissions, tags, editions, providers
Project Project _id label group, description, files, analyses, templates, notes, info
Subject Subject _id label project, code, firstname, lastname, sex, species, strain, cohort, files, analyses, info
Session Session _id label subject, project, group, timestamp, operator, weight, age, files, analyses, info
Acquisition Acquisition _id label session, timestamp, uid, files, analyses, info
Analysis AnalysisOutput _id label files, inputs, job

Hierarchy Diagram

graph TD
    G[Group] --> P[Project]
    P --> S[Subject]
    S --> SE[Session]
    SE --> A[Acquisition]

    P --> PF[Files]
    P --> PA[Analyses]

    S --> SF[Files]
    S --> SA[Analyses]

    SE --> SEF[Files]
    SE --> SEA[Analyses]

    A --> AF[Files]
    A --> AA[Analyses]

Groups are the only container type that cannot hold files or analyses. Every other container in the hierarchy supports both.

Parent-Child Relationships

The hierarchy is strictly enforced: a Group can only contain Projects, Projects contain Subjects, Subjects contain Sessions, and Sessions contain Acquisitions. Skipping levels is not possible.

Group
└── Project
    └── Subject
        └── Session
            └── Acquisition

On each container object, attributes named after parent container types (project, subject, session, group) are references to the container's parent, not children. For example, session.subject returns the parent Subject, not a list of subjects belonging to the session.

Traversal

Child containers are accessed through Finder objects exposed as attributes. Call them like functions (with optional filter arguments) to retrieve a list.

Traverse the full hierarchy
project = fw.projects.find_first("label=MyStudy")

--8 < --"test_docs_core_concepts.py:traverse_hierarchy"

project.subjects(), subject.sessions(), and session.acquisitions() each return all direct children. See Core Concepts: Finders for filter syntax and pagination options.

IDs Versus Labels

Every container has both an _id (a system-assigned string such as "000123456789abcdefABCDEF") and a label (a human-readable string such as "Baseline MRI").

  • Use _id when you need a stable, unique reference. IDs do not change and are not reused.
  • Use label in path lookups or for display purposes. Labels can change and are not guaranteed unique within a container level.

Fetching by ID

Use the typed get_* methods on the client:

Fetch containers by ID
--8 < --"test_docs_core_concepts.py:fetch_by_id"

Fetching by Path

fw.lookup() resolves a slash-separated path through the hierarchy by label:

Fetch containers by path
--8 < --"test_docs_core_concepts.py:fetch_by_path"

Path components correspond to: group_id/project_label/subject_label/session_label/acquisition_label.

Note that the Group segment uses the Group's _id (short identifier), while Project, Subject, Session, and Acquisition segments use label. If any label in the path contains a slash, it must be URL-encoded.

Accessing Container Attributes

Once you hold a container object, access its attributes directly:

Access container attributes
--8 < --"test_docs_core_concepts.py:access_container_attributes"

To reload a container with the latest server state (for example after a modification), call session = session.reload().

Files

Files attach to any container except Group. A container's files attribute is a list of file metadata objects — it is populated when the container is fetched and reflects the state at that moment.

List files on a container
--8 < --"test_docs_core_concepts.py:list_files_on_container"

Files on an Acquisition correspond to the actual scan data visible in the Flywheel UI session view. Files on Project, Subject, or Session appear under the "Attachments" section in the UI.

For file upload, download, and metadata operations, see Core Concepts: Containers.

Analyses

An Analysis (Acquisition Data Analysis or ADA) is the output of running a gear or an ad hoc computation on existing files. Analyses can attach to a Project, Subject, Session, or Acquisition — but not to a Group.

Each container exposes its analyses through the analyses attribute (when the container is reloaded with full data) or through the .analyses() finder:

List analyses on a session
--8 < --"test_docs_core_concepts.py:list_analyses_on_session"

The same pattern applies to Project, Subject, and Acquisition.