Analyses

An analysis is a container that records the inputs, outputs, and log of the gear that produced a set of results. Analyses are first-class members of the Flywheel hierarchy — they attach to a Project, Subject, Session, or Acquisition and preserve the provenance trail that separates a meaningful result from a plain file upload.

This page covers reading existing analyses, creating ad-hoc analyses for results computed off-platform, and finding analyses across the hierarchy. To launch an analysis from a gear, see Gears. To monitor the backing job, see Jobs.

Ad-hoc vs job-backed analyses

Analyses come from one of two sources. They share the same data shape; only the job field is populated for job-backed analyses.

Type	How it's created	When to use
Ad-hoc	`fw.add_<container>_analysis(id, AdhocAnalysisInput(...))`	Recording results computed outside Flywheel — the caller uploads inputs and outputs.
Job-backed	`gear.run(analysis_label=..., destination=container, ...)`	Running an analysis gear on Flywheel data — the gear records inputs and writes outputs.

Where analyses live

Any container except a file and group can host analyses. The list is exposed as a plain attribute on the parent container.

List analyses on a session

session_id = "000123456789abcdefABCDEF"

session = fw.get_session(session_id)
for analysis in session.analyses:
    print(f"{analysis.label} ({analysis.id})")

Note

container.analyses is a plain list, not a Finder. For filtered, paginated, or async queries that span containers, use the fw.analyses finder described under Finding analyses.

Reading an analysis

fw.get_analysis(id) returns a single analysis container. Like other containers, analysis.reload() refetches its state — call it after uploading outputs or modifying fields to see the updated values.

Get an analysis by ID

analysis_id = "000123456789abcdefABCDEF"

analysis = fw.get_analysis(analysis_id)
print(f"{analysis.label} (parent session: {analysis.parents.session})")

An analysis exposes its inputs and outputs as two separate collections:

Attribute	Contains
`analysis.inputs`	List of `FileReference` — what the analysis ran on
`analysis.files`	Files attached to the analysis — its outputs
`analysis.job`	The backing job, populated only for job-backed analyses
`analysis.gear_info`	Gear name, version, and category, populated only for job-backed analyses

List analysis inputs and output files

analysis = fw.get_analysis(analysis_id).reload()

print("Inputs:")
for inp in analysis.inputs:
    print(f"  {inp.name} (from {inp.type} {inp.id})")

print("Outputs:")
for output in analysis.files:
    print(f"  {output.name} ({output.size} bytes)")

Creating an ad-hoc analysis

An ad-hoc analysis records results that were not produced by a gear on the Flywheel instance — typically results from external pipelines. The caller supplies the input file references; outputs are uploaded after the analysis is created. If you want the ad-hoc analysis container to reference which files it used as input, those files must exist on the Flywheel platform, somewhere in the same project that you're attaching the analysis to. The outputs will get uploaded to Flywheel when you specify them in the SDK call. A typical ad-hoc workflow would be:

Download relevant files from Flywheel
Process locally
Package results
Create ad-hoc analysis, referencing the downloaded files as input
Upload analysis results as output

Create an ad-hoc analysis

session_id = "000123456789abcdefABCDEF"
acquisition_id = "000123456789abcdefABCDEF"
analysis_label = "Off-platform AFQ run 2026-05-27"

inputs = [
    flywheel.FileReference(
        type="acquisition",
        id=acquisition_id,
        name="scan.txt",
    )
]
body = flywheel.AdhocAnalysisInput(
    label=analysis_label,
    description="Results from off-platform analysis of scan.txt",
    inputs=inputs,
)
analysis_id = fw.add_session_analysis(session_id, body)

FileReference requires type (the parent container type — acquisition, session, subject, or project), id (the parent container ID), and name (the file's name on that container). Add version=<int> to pin to a specific revision.

The matching method varies by parent container: fw.add_project_analysis, fw.add_subject_analysis, fw.add_session_analysis, or fw.add_acquisition_analysis. Each accepts the same AdhocAnalysisInput body.

After the analysis exists, upload each output file:

Upload an output file to an analysis

analysis = fw.get_analysis(analysis_id)
analysis.upload_output(flywheel.FileSpec("summary.csv", "metric,value\nf1,0.88"))

Tip

Ad-hoc analyses are the right tool for ingesting derived data from non-Flywheel pipelines while keeping provenance. Recording the original Flywheel files as inputs lets downstream queries trace every output back to the source files, even though no gear ran on the instance.

Finding analyses

fw.analyses is a Finder, so the standard find / find_first / iter / iter_find methods all apply.

The most useful filter keys:

Key	Example
`label`	`label=AFQ 2026-05-27`
`parents.session`	`parents.session=000123456789abcdefABCDEF`
`parents.subject`	`parents.subject=000123456789abcdefABCDEF`
`parents.project`	`parents.project=000123456789abcdefABCDEF`
`job`	`job=000123456789abcdefABCDEF`
`gear_info.name`	`gear_info.name=afq`

Find all analyses on a session

session_id = "000123456789abcdefABCDEF"

analyses = list(fw.analyses.iter_find(f"parents.session={session_id}"))
for analysis in analyses:
    print(f"{analysis.label} ({analysis.id})")

Downloading analysis outputs

Output files live on analysis.files and download with the same download_file method used for any other container's files.

Download an output file from an analysis

analysis = fw.get_analysis(analysis_id)
analysis.download_file("result.csv", dest_path)

For bulk transfer of all outputs at once, see File upload and download.