Ingesting Data in BIDS Format using the CLI
Introduction
BIDS (Brain Imaging Data Structure) has become one of the standard ways for organizing and sharing neuroimaging data. If you have existing data that is in the BIDS format that you would like to migrate to Flywheel, you can use the Flywheel CLI. Because BIDS follows a standard structure, the Flywheel CLI is able to read the metadata and automatically place your files into the correct location in Flywheel.
This article explains how to use the Flywheel CLI to ingest BIDS data and includes a reference guide for the command.
Prefer videos?
We also have a collection of webinars on using BIDS and Flywheel.
Before You Begin
- Follow these instructions to download and install the Flywheel CLI. If you cannot download the Flywheel CLI to your computer, you can upload smaller batches of files using your web browser.
- Verify your data follows the BIDs format. If your data does not follow the BIDS format, see our other options for ingesting data.
Note: Currently, the Flywheel CLI supports ingesting the MR modality. To ingest other modalities into Flywheel (ex. EEG or MEG), use the browser upload.
Example BIDS Directory Structure
From the BIDS specification documentation, here are two examples of a single session and longitudinal and multi-site study.
Single Session Example
Longitudinal studies with multiple sessions (visits) example
Instruction Steps
To ingest BIDS data into Flywheel:
- Open Terminal or Windows Command Prompt.
- Note the location of the parent folder containing the BIDS data you are ingesting.
-
Find the group ID for the group where you want to ingest your data. To find the group ID in the Flywheel UI:
-
Open Chrome, and sign in to your Flywheel account
- From the menu on the left, select Groups.
- Note the group ID.
Tip: You must have read/write permission to ingest data to the group.
- In Terminal or Windows Command Prompt, enter the following command to ingest the folder:
For example: fw ingest bids ~/Documents/Study1 Ophthalmology
The Flywheel CLI displays the BIDS data it is processing and then shows if it is creating a new container in Flywheel or if it is adding the data to an existing container.
-
The ingest is complete once the Flywheel CLI stops showing data. If the Flywheel CLI is unable to ingest any data, an error occurs.
-
Sign in to Flywheel, and view your data.
-
In the left-hand navigation pane, select Projects
-
Your ingested data will be under a project that matches the name of the parent folder for your BIDS data.
If you used the --project
option in the command, your data will be under the project you specified in the command.
The Flywheel UI offers the option to view data in the BIDs directory structure. See our BIDS Overview article for more information.
Example: Ingest a Single Session
If you do not want to ingest all of your BIDS data, you can ingest a single subject or session folder to Flywheel. The --session
and --subject
options only upload folders matching the name you give in the command.
Below is a directory in the BIDS format. In this example, you want to upload session 01
for subject Control01
.
- Open Terminal or Windows Command Prompt.
- Note the location of the parent folder containing the BIDS data you are ingesting.
-
Find the group ID for the group where you want to ingest your data. To find the group ID in the Flywheel UI:
- Sign in to your Flywheel account
- From the menu on the left, select Groups.
- Note the group ID.
Tip: You must have read/write permission to ingest data to the group.
- Use the
--subject
and--session
options with theingest bids
command. Using the example directory above, the command to ingestses-01
for subjectcontrol01
would look like:
- The ingest is complete once the Flywheel CLI stops showing data. If the Flywheel CLI is unable to ingest data, an error occurs.
- Sign in to Flywheel, and view your data.
Tip: The Flywheel UI offers the option to view data in the BIDs directory structure. See our BIDS Overview article for more information.
Reference Guide
BIDS ingest will ingest a BIDS organized folder as a project within flywheel, under the provided group. Learn more about installing the Flywheel CLI.
Positional Arguments
Required argument | Description |
---|---|
folder | path to the folder with the BIDS data you would like to upload |
group | Flywheel group id |
Optional Arguments
Optional argument | Description |
---|---|
-h, --help | Show this help message and exit |
--config-file CONFIG_FILE, -C CONFIG_FILE | Specify configuration options via config file. Learn more about creating a config file for data upload. |
--no-config | Do NOT load the default configuration file |
-y, --yes | Assume the answer is yes to all prompts |
--ca-certs CA_CERTS | The file to use for SSL Certificate Validation |
--timezone TIMEZONE | Set the effective local timezone for ingests |
--debug | Turn on debug logging |
--quiet | Squelch log messages to the console |
--project \ | Label of Flywheel project to ingest into |
--subject SUBJECT | Only upload data from single subject folder (e.g. sub-01) |
--session SESSION | Only upload data from single session folder (e.g. ses-01) |