Data Views

A data view is a structured query that collects fields from across the Flywheel container hierarchy and returns the result as tabular data. Instead of writing nested loops to gather subject demographics, session timestamps, and acquisition labels into a single table, you define a view once and execute it against a project or container. The result comes back as JSON, a pandas DataFrame, or a local CSV/TSV file.

When to Use Data Views

Direct hierarchy traversal works fine for small-scale inspection or when you need to act on containers rather than read from them. Data views are the better choice when:

• You need structured tabular output for downstream analysis or export.
• You are collecting fields from multiple hierarchy levels (project, subject, session, acquisition) in one operation.
• You want to pull columns out of CSV or JSON output files produced by analysis gears.
• You plan to reuse the same query across different projects.

See Core Concepts: Hierarchy for a description of the container levels data views operate across.

Discovering Available Columns

Before building a view, check which columns and column groups are available:

fw.print_view_columns()

This prints a list like:

project (group): All column aliases belonging to project
project.id (string): The project id
project.label (string): The project label
subject (group): All column aliases belonging to subject
subject.id (string): The subject id
subject.label (string): The subject label or code
subject.firstname (string): The subject first name
subject.lastname (string): The subject last name
subject.age (int): The subject age, in seconds
subject.sex (string): The subject sex
...

You can filter the output by passing a string: fw.print_view_columns(filter="subject").

Building a View

fw.View() — simple shorthand

fw.View() is a shorthand for flywheel.ViewBuilder(**kwargs).build(). Use it when you do not need file extraction or complex analysis filtering:

# Collect all built-in subject columns across a project
--8 < --"test_docs_core_concepts.py:view_shorthand"

ViewBuilder — full control

ViewBuilder is the underlying class. Use it when you need file extraction, analysis filtering, or any option not exposed by fw.View().

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

Key ViewBuilder constructor parameters:

Column Types

Individual columns

Columns follow the format <container>.<field>, for example subject.label, session.timestamp, acquisition.label. You can add them as a list in the constructor or call builder.column() individually:

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

builder.column() accepts optional parameters:

• dst — rename the column in the output.
• type — coerce values to int, float, string, or bool.

Column groups

Passing a container name as a column adds all pre-defined fields for that level:

# Adds all subject fields: id, label, firstname, lastname, age, sex, etc.
view = fw.View(columns=["subject", "session.label"])

Info columns

The info field on a container holds unstructured key-value metadata. To pull a specific key, use <container>.info.<key>:

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

Avoid adding subject.info as a bare column in CSV or TSV output. The view engine extracts columns from the first row it encounters, which produces inconsistent results when info fields differ across subjects. Always name the specific key you want. See Core Concepts: Metadata for more on the info field.

Executing a View

All execution methods accept a DataView object or a saved view ID string as the first argument.

Load as JSON

import json

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

To change the output format, pass format:

response = fw.read_view_data(view, project.id, format="csv")

Supported formats: json (default), json-row-column, json-flat, csv, tsv.

Load as a DataFrame

Requires the pandas package:

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

Save to a local file

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

Filter at execution time

Pass a filter keyword to any execution method to restrict which rows are returned without changing the view definition:

# Only rows where subject sex is male
--8 < --"test_docs_core_concepts.py:read_view_dataframe_filtered"

You can also paginate large results with skip and limit:

df = fw.read_view_dataframe(view, project.id, skip=0, limit=100)

Extracting File Data

Data views can read rows directly from CSV, TSV, or JSON files attached to containers or produced by analysis gears. Set container and filename to match the target files, then use file_column() to specify which columns to extract.

file_match — handling multiple matches

If more than one file matches the pattern on a given container, file_match controls which one is used:

file_column — extract specific columns

file_column(src, dst=None, type=None) adds a single column from the matched file:

• src — the column name in the CSV/TSV/JSON file.
• dst — rename the column in the output (defaults to src).
• type — coerce the value: float, int, string, bool.

Full example: AFQ tract metrics

This example reads diffusion metrics from the newest Mean_Diffusivity.csv output file produced by the afq gear, combined with subject and session labels from the hierarchy:

builder = flywheel.ViewBuilder(
    label="AFQ Tract Metrics",
    columns=["subject.label", "session.label"],
    container="session",
    filename="Mean_Diffusivity.csv",
    analysis_gear_name="afq",
)
builder.file_match("newest")
builder.file_column("Left_Thalamic_Radiation", type="float")
builder.file_column("Right_Thalamic_Radiation", type="float")
view = builder.build()

df = fw.read_view_dataframe(view, project.id)

The result is a DataFrame where each row corresponds to one session, with columns for subject.label, session.label, Left_Thalamic_Radiation, and Right_Thalamic_Radiation.

Matching files without analysis filters

To read from files attached directly to containers (not analysis output), omit the analysis_* parameters:

# Read all columns from files named behavioral_results_*.csv on each session
view = fw.View(container="session", filename="behavioral_results*.csv")
df = fw.read_view_dataframe(view, project.id)

Saving and Reusing Views

Saving a view stores its definition on your user account or on a project, so you can run it again without rebuilding it.

Save a view

fw.add_view(owner_id, view) saves the view definition and returns a view ID string:

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

To save to a project instead of your user account, pass the project ID:

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

Execute a saved view

Pass the view ID string in place of a DataView object:

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

You can execute a saved view against any container you have access to, not just the one it was saved on.

List saved views

fw.get_views(container_id) returns all views saved on a container (user account or project):

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

Load a view by ID

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

Ad-hoc vs. Saved Views

For one-off analysis during development, build views ad-hoc with ViewBuilder. When the query is stable and you need to run it repeatedly — or share it with other users via the Flywheel UI — save it.

Related

• Core Concepts: Hierarchy — container types and the hierarchy data views traverse.
• Core Concepts: Finders — alternative approach for finding and iterating containers.
• Core Concepts: Metadata — the info field and how custom metadata is stored on containers.