Metadata: Info, Tags, and Notes

Flywheel containers support three distinct types of metadata: info, tags, and notes. Each serves a different purpose and has a different structure.

All three types are accessed through methods on the container object. You must retrieve a live container from the SDK (not a search result stub) before calling write methods.

acquisition.update_info(
    {
        "Measurements": {
            "MaxMotion": 0.42,
            "MaxHeartRate": 72,
            "MaxRespiration": 18,
        }
    }
)

Info

info is a free-form JSON dictionary attached to a container or file. Use it to store structured metadata that scripts or gears need to read back programmatically — for example, BIDS sidecar fields, pipeline parameters, or derived values.

Info supports arbitrary nesting. Keys that contain $ or . are sanitized by the SDK (replaced with - and _ respectively), so avoid those characters in key names.

Reading info

Access the current info via the .info attribute on the container object:

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

If the container was fetched via a finder or search, it may not include the full info payload. Call reload() to ensure you have the latest data:

session = session.reload()
print(session.info)

Adding and merging keys

update_info() merges the provided dict into the existing info. It does not remove keys that are not in the new dict:

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

This also works with nested structures:

acquisition.update_info({"header": {"nifti": {"dim": [3, 64, 64, 32]}}})

To avoid overwriting an unrelated nested key when merging into a nested structure, read the current value first:

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

Replacing all info

replace_info() overwrites the entire info dict. Any keys not included in the new dict are lost:

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

Use replace_info() when you want a clean slate, and update_info() when you want to add or update individual keys.

Removing keys

delete_info() removes one or more keys. Pass key names as positional arguments:

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

Container info method summary

File Info

Files also carry info. You can access and modify file info through the parent container using the filename, or directly on the file object if you have it.

Reading file info

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

Writing file info via the parent container

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

Writing file info directly on the file object

If you have a FileEntry object (from acquisition.files), it exposes the same methods without needing the filename:

file_entry = acquisition.files[0]
file_entry.update_info({"EchoTime": 0.03})
file_entry.replace_info({"EchoTime": 0.03})
file_entry.delete_info("EchoTime")

File info method summary

Tags

Tags are short string labels attached to containers. Use them to flag status, mark subsets for processing, or enable filtering in finder queries.

Available tags in a Flywheel instance are managed at the Group level. Adding a tag that does not exist in the group will create it.

Reading tags

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

Adding and removing tags

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

Filtering with tags

Tags are indexed and can be used in finder filter expressions. See Core Concepts: Finders for full filter syntax.

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

Tag method summary

Files also support tags through file.add_tag(), file.delete_tag(), and file.rename_tag().

Notes

Notes are timestamped, user-attributed free-text entries. Each note records who wrote it and when. Use notes to document decisions, flag issues for human review, or maintain an audit trail on a container.

Notes are stored as a list under container.notes. Each note object has an .id, a .text, a .created timestamp, and a .user field identifying the author.

Reading notes

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

Adding a note

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

Deleting a note

You need the note's .id to delete it. Retrieve the notes list and select the one you want to remove:

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

There is no update_note() method in the SDK. To edit a note, delete it and add a new one.

Note method summary

File Classification

Files also carry a classification field that organizes them into modality-specific dimensions called aspects. For the MR modality, the standard aspects include Intent, Measurement, and Features. The Custom aspect is always available regardless of modality.

Classification is separate from info — it is used by Flywheel to organize files and drive gear rule matching.

Classifications set on files should adhere to the classification schema. To learn how to view or modify your site's classification schema, see Admin Concepts: Modality and Classification Schema.

For more about data classification on Flywheel, including the default classification schema, consult the Flywheel product documentation.

Reading classification

file_entry = acquisition.files[0]
print(file_entry.classification)
# {'Intent': ['Structural'], 'Measurement': ['T1'], 'Custom': []}

Replacing classification

replace_file_classification() overwrites the entire classification and optionally sets the modality:

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

Adding to classification

update_file_classification() merges values into specific aspects without clearing others:

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

Removing classification values

delete_file_classification() removes specific values from specific aspects:

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

On a file object directly:

file_entry.replace_classification({"Intent": ["Functional"]}, modality="MR")
file_entry.update_classification({"Custom": ["processed"]})
file_entry.delete_classification({"Custom": ["processed"]})

Which Metadata Type to Use

• Use info for free-form information storage, structured but schema-less metadata data that isn't a first-class Flywheel field but needs to live with the container, stay queryable, and travel alongside it through copies, exports, and jobs. Examples: Header information, gear output.

• Use tags for flat list of short string labels attached to a container (or file). Tags are a set of identifier-like strings optimized for filtering and membership checks. Examples: status/workflow flags, cohort / study-arm membership, finder filters.

• Use notes for timestamped, user-attributed free-text entries attached to a container. Notes are prose written by humans for humans: a built-in comment thread on the container. Examples: Decision log, reviewer handoff, contextual narrative that does't fit a field.

Related

• Core Concepts: Containers — container types and their parent-child relationships
• Core Concepts: Finders — filter syntax for querying containers by tag and info fields
• Admin Concepts: Modality and Classification Schema - create, read, update, and delete modalities and classification schemas
• Data Classification product documentation - more information on Flywheel classification metadata