Data Model

Hierarchy

Data in a Flywheel system is organized in a tree-like hierarchy, as indicated in the following diagram.

• flywheel.models.user.User - An authorized entity, usually referenced by email address.

• flywheel.models.group.Group - A grouping of users and projects.

• flywheel.models.project.Project - A project represents a grouping of subjects and sessions, e.g. within a study.

• flywheel.models.subject.Subject - An individual under study.

• flywheel.models.session.Session - A grouping of acquired data, typically data acquired within a limited timeframe.

• flywheel.models.acquisition.Acquisition - A set of one or more files, typically acquired as part of the same process, at the same time.

• flywheel.models.analysis_output.AnalysisOutput - A set of one or more derivative files from analyzing files after they have been acquired.

Permissions

Permissions in Flywheel are managed at the Group and Project level. The management of permissions are different between the two.

For Groups, a user may be added with any one of three access levels: “admin”, “rw”, “ro”. The current level assigned to users can be found under the “permissions” field of a group.

Permissions under a group look like ``` {

“_id”: “dev@flywheel.io”, “access”: “admin”

permission = fw.get_project_user_permission(PROJECT_ID, USER_A_ID)
permission.id = USER_B_ID
project.add_permission(permission)

# Edit these values to match a real group id and a project label that belongs to that group
group_id = 'group_id'
project_label = 'project_label'

# These actions (read_only actions) are required for any new role definition
REQUIRED_ACTIONS = [
        'containers_view_metadata',
        'files_view_metadata',
        'tags_view',
        'notes_view',
        'project_permissions_view',
        'data_views_view',
        'session_templates_view',
        'gear_rules_view',
        'jobs_view'
]

# Add files_modify_metadata to list
action_list = REQUIRED_ACTIONS + ['files_modify_metadata']

# Create a dictionary defining label and actions
role_dict = {'label': 'role_a_d20', 'actions': action_list}

# Add the role to Flywheel
role_a_d20 = fw.add_role(role_dict)

# Add the role to a group
fw.add_role_to_group(group_id, {'_id': role_a_d20.id})

# Get a project
project = fw.lookup(f'{group_id}/{project_label}')

# Add role for a user not yet on the project (but has been added to the Flywheel instance)
# Replace new_user@example.com with an email address belonging to a real user
user_id = 'new_user@example.com'
project.add_permission({'_id': user_id, 'role_ids': [role_a_d20.id]})

# Add role for user with existing permissions on the project
# Add containers_modify_metadata to list
action_list = REQUIRED_ACTIONS + ['containers_modify_metadata']

# Create a dictionary defining label and actions
role_dict = {'label': 'barrel_role', 'actions': action_list}

# Add the role to flywheel
barrel_role = fw.add_role(role_dict)

# Add the role to a group
fw.add_role_to_group(group_id, barrel_role.id)

# Get the current permission dictionary for user
permission_dict = fw.get_project_user_permission(project.id, user_id)

# Add role id to the current list of role ids
permission_dict['role_ids'].append(barrel_role.id)

# Update the user's permissions with the modified permission_dict
project.update_permission(user_id, permission_dict)

# List all roles
fw.get_all_roles()

# List all group roles
fw.get_all_group_roles(group_id)

# We need to remove the permission that uses the role before removing the role from group
project.delete_permission(user_id)

# Delete the role from group
fw.remove_role_from_group(group_id, barrel_role.id)

# Delete the role
fw.delete_role(barrel_role.id)

Containers

Projects, Subjects, Sessions, Acquisitions and Analyses are all different types of Containers. Containers in Flywheel all support the following features:

Tags are concise labels that provide descriptive metadata that can be searched on. Available tags are managed on the Group.

# See tags on a session
session = fw.get(session_id)
print(', '.join(session.tags))

# Add a tag to a session
session.add_tag('Control')

# Remove a tag from a session
session.delete_tag('Analysis Required')

Notes are user-entered, human readable metadata attached to a container. They are timestamped and attributed to the user that entered them.

from pprint import pprint

# See notes on a session
session = fw.get(session_id)
pprint(session.notes)

# Add a note to a session
session.add_note('This is a note')

# Delete a note from a session
session.delete_note(session.notes[0].id)

Info is free-form JSON metadata associated with a container or file.

from pprint import pprint

# Print the info for an acquisition
acquisition = fw.get(acquisition_id)
pprint(acquisition.info)

# Replace the entire contents of acquisition info
acquisition.replace_info({ 'splines': 34 })

# Add additional fields to acquisition info
acquisition.update_info({ 'curve': 'bezier' })

# Delete fields from acquisition info
acquisition.delete_info('splines')

Files are a set of file attachments associated with a container. See also Dealing with Files.

from pprint import pprint

# List files on an acquisition
acquisition = fw.get(acquisition_id)

for f in acquisition.files:
  print('Name: %s, type: %s' % (f.name, f.type))

# Upload a file to an acquisition
acquisition.upload_file('/path/to/file.txt')

# Download a file to disk
acquisition.download_file('file.txt', '/path/to/file.txt')

# Files can also have metadata
pprint(acquisition.files[0].info)

acquisition.replace_file_info('file.txt', {'wordCount': 327})

Flywheel supports an extensible, multi-dimenstional classification scheme for files. Each dimension of classification is referred to as an aspect. The available aspects are determined by the file’s modality.

For example, the MR modality provides the Intent, Measurement and Features aspects. In addition, the Custom aspect is always available, regardless of modality.

from pprint import pprint

# Display the aspects defined in the MR modality
mr = fw.get_modality('MR')
pprint(mr)

# Replace a file's modality and classification
acquisition.replace_file_classification('file.txt', {
        'Intent': ['Structural'],
        'Measurement': ['T2']
}, modality='MR')

# Update a file's Custom classification, without changing
# existing values or modality
acquisition.update_file_classification('file.txt', {
        'Custom': ['value1', 'value2']
})

# Delete 'value1' from Custom classification
acquisition.delete_file_classification('file.txt', {
        'Custom': ['value1']
})

Objects with timestamps and created/modified dates provide helper accessors to get those dates in the local (system) timezone, as well as the original timezone in the case of acquisition and session timestamps.

For example:

# Acquisition Timestamp (tz=UTC)
print(acquisition.timestamp.isoformat())

# Acquisition Timestamp (tz=Local Timezone)
print(acquisition.local_timestamp.isoformat())

# Acquisition Timestamp (tz=Original Timezone)
print(session.original_timestamp.isoformat())

Sessions have a field for subject age at the time of the session, in seconds. There are also helper accessors to get age in years, months, weeks and days.

For example:

# Subject age in seconds
print('Subject was {} seconds old', session.age)

# Subject age in years
print('Subject was {} years old', session.age_years)