General Usage Guidelines

Before we implement a CuBIDS workflow, let’s define the terminology and take a look at some of the commands available in the software.

More definitions

Entity Set

A Entity Set is a unique set of BIDS key-value pairs, excluding identifiers such as subject and session. For example, the files:

bids-root/sub-1/ses-1/func/sub-1_ses-1_acq-mb_dir-PA_task-rest_bold.nii.gz
bids-root/sub-1/ses-2/func/sub-1_ses-2_acq-mb_dir_PA_task-rest_bold.nii.gz
bids-root/sub-2/ses-1/func/sub-2_ses-1_acq-mb_dir-PA_task-rest_bold.nii.gz

Would all share the same Entity Set. If these scans were all acquired as a part of the same study on the same scanner with exactly the same acquisition parameters, this naming convention would suffice.

However, in large multi-scanner, multi-site, or longitudinal studies where acquisition parameters change over time, it’s possible that the same Entity Set could contain scans that differ in important ways.

CuBIDS examines all acquisitions within a Entity Set to see if there are any images that differ in a set of important acquisition parameters. The subsets of consistent acquisition parameter sets within a Entity Set are called a Parameter Group.

Parameter Group

A Parameter Group is a subset of a Entity Set that contains images with the same acquisition parameters.

Even though two images may belong to the same Entity Set and are valid BIDS, they may have images with different acquisition parameters. There is nothing fundamentally wrong with this — the bids-validator will often simply flag these differences with a Warning, but not necessarily suggest changes. That being said, there can be detrimental consequences downstream if the different parameters cause the same preprocessing pipelines to configure differently to images of the same Entity Set.

Acquisition Group

We define an Acquisition Group as a collection of sessions across participants that contain the exact same set of Entity and Parameter Groups. Since Entity Sets are based on the BIDS filenames— and therefore both MRI image type and acquisition specific— each BIDS session directory contains images that belong to a set of Parameter Groups. CuBIDS assigns each session, or set of Parameter Groups, to an Acquisition Group such that all sessions in an Acquisition Group possesses an identical set of scan acquisitions and metadata parameters across all image modalities present in the dataset. We find Acquisition Groups to be a particularly useful categorization of BIDS data, as they identify homogeneous sets of sessions (not individual scans) in a large dataset. They are also useful for expediting the testing of pipelines; if a BIDS App runs successfully on a single subject from each Acquisition Group, one can be confident that it will handle all combinations of scanning parameters in the entire dataset.

The Acquisition Groups that subjects belong to are listed in _AcqGrouping.csv, while the Entity Sets and Parameter Groups that define each Acquisition Group are noted in _AcqGroupingInfo.txt.

The _summary.tsv File

This file contains all the detected Entity Sets and Parameter Groups. It provides an opportunity to evaluate your data and decide how to handle heterogeneity.

Below is an example _summary.tsv of the run-1 DWI Entity Set in the PNC [1]. This reflects the original data that has been converted to BIDS using a heuristic. It is similar to what you will see when you first use this functionality:

Pre Apply Groupings

Notes	ManualCheck	MergeInto	RenameEntitySet	KeyParamGroup	EntitySet	ParamGroup	Counts	Dim1Size	Dim2Size	Dim3Size	EchoTime	EffectiveEchoSpacing	FlipAngle	HasFieldmap	EntitySetCount	Modality	NSliceTimes	NumVolumes	Obliquity	ParallelReductionFactorInPlane	PartialFourier	PhaseEncodingDirection	RepetitionTime	TotalReadoutTime	UsedAsFieldmap	VoxelSizeDim1	VoxelSizeDim2	VoxelSizeDim3
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTNoFmap	datatype-dwi_run-1_suffix-dwi__2	datatype-dwi_run-1_suffix-dwi	2	25	128	128	70	0.082	0.000267	90	FALSE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime	datatype-dwi_run-1_suffix-dwi__3	datatype-dwi_run-1_suffix-dwi	3	6	128	128	70	0.082	0.000267	90	TRUE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	9.0	0.034	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime	datatype-dwi_run-1_suffix-dwi__4	datatype-dwi_run-1_suffix-dwi	4	3	128	128	70	0.082	0.000267	90	TRUE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	9.8	0.034	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTDim3SizeVoxelSizeDim3	datatype-dwi_run-1_suffix-dwi__5	datatype-dwi_run-1_suffix-dwi	5	2	128	128	46	0.082	0.000267	90	TRUE	1426	dwi	46	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	3.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTEchoTimeEffectiveEchoSpacingRepetitionTimeTotalReadoutTime	datatype-dwi_run-1_suffix-dwi__6	datatype-dwi_run-1_suffix-dwi	6	1	128	128	70	0.102	0.0008	90	TRUE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	12.3	0.102	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTObliquity	datatype-dwi_run-1_suffix-dwi__7	datatype-dwi_run-1_suffix-dwi	7	1	128	128	70	0.082	0.000267	90	TRUE	1426	dwi	70	35.0	TRUE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0

The _files.tsv file

This file contains one row per imaging file in the BIDS directory. You won’t need to edit this file directly, but it keeps track of every file’s assignment to Entity and Parameter Groups.

Date/time anonymization before DataLad

Run cubids date-time-shift before your BIDS dataset is checked into DataLad. The command updates acquisition metadata in place, so running it before the first DataLad commit prevents identifiable dates and precise acquisition times from being recorded in the dataset history.

Start with a dry run:

$ cubids date-time-shift /path/to/bids --dry-run

To apply the anonymization, run:

$ cubids date-time-shift /path/to/bids

For larger datasets, use --n-cpus to read and plan independent file updates in parallel. Files are still written only after the preflight phase has completed successfully:

$ cubids date-time-shift /path/to/bids --n-cpus 4

For each subject, CuBIDS sets the earliest rounded acquisition date in subject-level or session-level *_scans.tsv files to 1800-01-01 and preserves calendar-day intervals between acquisitions. It rounds acq_time values in those tables and the following JSON fields to the nearest hour: AcquisitionTime, time.samples.AcquisitionTime, time.samples.ContentTime, global.const.PerformedProcedureStepStartTime, global.const.SeriesTime, and global.const.StudyTime. Thirty minutes rounds up, and times at 23:30 or later wrap to 00:00:00. No other metadata values are changed.

Date-bearing JSON fields such as AcquisitionDateTime and the dcmmeta global.const date fields (StudyDate, SeriesDate, AcquisitionDate, ContentDate) are not rewritten; the command reports them as warnings so they can be removed or de-identified before the dataset enters version control.

The command validates all readable scans tables and JSON files before writing any changes. It reports unparseable acquisition-time values as warnings and leaves those individual values unchanged. Use --dry-run to review every planned change before running the command without that option.

Modifying Entity and Parameter Group Assignments

Sometimes we see that there are important differences in acquisition parameters within a Entity Set. If these differences impact how a pipeline will process the data, it makes sense to assign the scans in that Parameter Group to a different Entity Set (i.e., assign them a different BIDS name). This can be accomplished by editing the empty columns in the _summary.csv file produced by cubids group.

Once the columns have been edited you can apply the changes to BIDS data using

$ cubids apply /bids/dir entityparam_edited new_entityparam_prefix

The changes in entityparam_edited_summary.csv will be applied to the BIDS data in /bids/dir and the new Entity and Parameter groups will be saved to csv files starting with new_entityparam_prefix. Note: every file collection is checked for compatible planned names. Fieldmaps with variant parameters are identified but are not renamed unless --fmap is passed to cubids apply.

The _AcqGrouping.tsv file

The _AcqGrouping.tsv file organizes the dataset by session and tags each one with its Acquisition Group number.

The _AcqGroupInfo.txt file

The _AcqGroupInfo.txt file lists all Entity Sets that belong to a given Acquisition Group along with the number of sessions each group possesses.

Visualizing and summarizing metadata heterogeneity

Use cubids group to generate your dataset’s Entity Sets and Parameter Groups:

$ cubids group FULL/PATH/TO/BIDS/DIR FULL/PATH/TO/v0

This will output four files, including the summary and files tsvs described above, prefixed by the second argument v0.

You can optionally specify additional BIDS entities to ignore when creating entity sets using the --ignore-entity flag. This is useful when you want to exclude certain entities from grouping, such as task, run, or direction. For example:

$ cubids group FULL/PATH/TO/BIDS/DIR FULL/PATH/TO/v0 --ignore-entity task run direction

This will exclude task, run, and direction entities from entity set names, in addition to the default excluded entities (subject, session, extension). Note that when using --acq-group-level session on longitudinal datasets, the session entity will be included in entity sets (and thus not ignored).

Applying changes

The cubids apply program provides an easy way for users to manipulate their datasets. Specifically, cubids apply can rename files according to the users’ specification in a tracked and organized way. Here, the summary.tsv functions as an interface modifications; users can mark Parameter Groups they want to rename (or delete) in a dedicated column of the summary.tsv and pass that edited tsv as an argument to cubids apply.

Detecting Variant Groups

Additionally, cubids apply can automatically rename files in Variant Groups based on their scanning parameters that vary from those in their Entity Sets’ Dominant Parameter Groups. Renaming is automatically suggested when the summary.tsv is generated from a cubids group run, with the suggested new name listed in the tsv’s Rename Entity Set column. CuBIDS populates this column for all Variant Groups (e.g., every Parameter Group except the Dominant one).

Specifically, CuBIDS will suggest renaming all non-dominant Parameter Groups to include VARIANT* in their acquisition field where * indicates how the Parameter Group varies from the Dominant Group:

1. For clustered parameters (like EchoTime), the cluster number is used (e.g., VARIANTEchoTime2)

2. For regular parameters (like FlipAngle), the actual value is used (e.g., VARIANTFlipAngle75)

3. For special parameters: - HasFieldmap variations use NoFmap or HasFmap - UsedAsFieldmap variations use Unused or IsUsed

For example, when CuBIDS encounters a Parameter Group with a clustered EchoTime that varies from the one present in the Dominant Group, it will automatically suggest renaming all scans in that Variant Group to include acquisition-VARIANTEchoTime2 in their filenames (if the scan belongs to cluster 2).

When multiple parameters vary, their names are concatenated (e.g., VARIANTEchoTime2FlipAngle75). When the user runs cubids apply, non-fieldmap filenames get renamed according to the auto-generated names in the “Rename Entity Set” column in the summary.tsv.

Note

The above behavior is new as of version 1.2.0. Prior to this, the variant name was just VARIANT{parameter}.

File collection variants

A File Collection is a set of files from one acquisition that must be interpreted together. Examples include the echoes of a multi-echo BOLD acquisition, the magnitude and phase parts of a complex image, and the members of a field map. Each member still has its own row in the CuBIDS files table and is assigned independently to an Entity Set and a Parameter Group. The collection is an additional relationship that CuBIDS uses to keep those rows consistent when it groups, renames, or deletes files.

CuBIDS derives collection rules from its bundled BIDS schema. Members must have the same complete filename context, including subject, session, run, and every entity that does not distinguish members of that collection. Most collections are distinguished by one or more of echo, flip, inv, mt, or part. Field maps also use these special relationships:

• phase-difference, two-phase, and direct-fieldmap B0 collections are linked by suffix. These contain, respectively, a phase-difference map and magnitude image(s), two phase maps and two magnitude images, or a fieldmap and magnitude image.

• pepolar B0 collections are linked by phase-encoding direction. Their members are *_epi images or, for arterial spin labeling, *_m0scan images under fmap/.

• The BIDS RF field-mapping schemes are linked by the entities prescribed for each method. TB1DAM varies by flip angle, TB1EPI by echo and flip angle, and TB1SRGE by flip angle and inversion time. TB1AFI, TB1TFL, TB1RFM, and RB1COR use role prefixes in their acquisition labels. For example, acq-anatTest pairs with acq-fampTest, while the trailing Test keeps that collection separate from acq-anatRetest and acq-fampRetest.

cubids group performs this comparison for every file collection and writes one row per collection to <prefix>_file_collection_variant_report.tsv. A collection passes when its planned names remain compatible. If only the variant portion of the acquisition labels differs and CuBIDS can derive one consistent label, the report proposes that label and the corresponding RenameEntitySet values. Otherwise, it marks the collection for manual review.

For example, when inconsistent collections are found, group prints:

WARNING: 3 file collections have mismatched variants; review
v0_file_collection_variant_report.tsv.

Before applying changes, CuBIDS revalidates every affected collection against the planned names. An incomplete or mismatched collection stops the entire apply operation. Apply also prevents a partial collection deletion, whether deletion was requested with --remove-RenameEntitySet or with MergeInto set to 0. List every member to delete the whole collection; otherwise, apply stops before changing any files. Use cubids purge when intentionally deleting a single member.

Fieldmap-specific handling

For PEPOLAR, the report verifies the actual PhaseEncodingDirection metadata instead of inferring polarity from labels such as dir-AP and dir-PA. Matching labels are a naming safeguard only: inspect reported differences before using the files with TOPUP or another distortion-correction tool.

A parametric map under fmap/, such as a TB1map or RB1map, is a standalone image and is left out of the report. A fieldmap acquired in a single phase-encoding direction is recorded as a passing single-direction epi or single-direction m0scan: it is valid BIDS and has no partner whose label it must match. Conversely, a magnitude image whose phasediff, phase, or fieldmap counterpart is absent is reported as orphan-magnitude for manual review.

Members that an acquisition label tells apart keep that label when they are renamed: an rf-field-map collection gets the same variant appended to each member’s own label, such as acq-anatVARIANTEchoTime alongside acq-fampVARIANTEchoTime.

By default, cubids apply excludes every file under fmap/ from renaming. After reviewing the report, use --fmap (or --allow-fmap-renames) to allow fieldmap renames. A standalone fieldmap is renamed like any other image once fieldmap renames are enabled. Matching labels do not guarantee compatibility with downstream pipelines; for example, an AP/PA EPI pair with different dimensions may not be compatible with TOPUP.

Renaming a fieldmap EPI also renames its JSON sidecar and any matching .bval and .bvec companions. Every apply rename updates matching filename entries in subject- or session-level *_scans.tsv tables.

Changing planned entity sets from the command line

cubids apply can rename or remove the collections listed in the RenameEntitySet column of the loaded summary, without hand-editing the table. Both options match a row on its planned entity set: the value in RenameEntitySet when that cell is filled in, and the value in EntitySet when it is empty. Copy the value exactly as the summary writes it.

To rename a collection, supply --change-RenameEntitySet OLD=NEW once for each mapping, where OLD and NEW are complete entity sets, or pass a CSV or TSV file with the columns old_entity_set and new_entity_set, one mapping per row. You can combine the two forms and repeat the option. CuBIDS never modifies the input summary. When using --change-RenameEntitySet or --remove-RenameEntitySet, provide --write-edited-summary to specify where to write the derived, edited summary. That file is written only once the whole request has passed validation, so a rejected apply leaves nothing behind.

For example, to give two verbose variant collections one short shared name while allowing reviewed fmap renames:

$ cubids apply /data/bids v0_summary.tsv v0_files.tsv v1 \
    --change-RenameEntitySet acquisition-VARIANTEchoTimeC1TotalReadoutTimeC1_datatype-dwi_direction-AP_run-01_suffix-dwi=acquisition-VARIANTVar1_datatype-dwi_direction-AP_run-01_suffix-dwi \
    --change-RenameEntitySet acquisition-VARIANTEchoTimeC2TotalReadoutTimeC2_datatype-dwi_direction-AP_run-01_suffix-dwi=acquisition-VARIANTVar1_datatype-dwi_direction-AP_run-01_suffix-dwi \
    --write-edited-summary v0_edited_summary.tsv \
    --fmap

Mappings are exact entity set substitutions, never substring replacements.

For example, the mappings above can instead be stored in entity_set_changes.tsv:

old_entity_set    new_entity_set
acquisition-VARIANTEchoTimeC1TotalReadoutTimeC1_datatype-dwi_direction-AP_run-01_suffix-dwi    acquisition-VARIANTVar1_datatype-dwi_direction-AP_run-01_suffix-dwi
acquisition-VARIANTEchoTimeC2TotalReadoutTimeC2_datatype-dwi_direction-AP_run-01_suffix-dwi    acquisition-VARIANTVar1_datatype-dwi_direction-AP_run-01_suffix-dwi

Pass the file with --change-RenameEntitySet entity_set_changes.tsv --write-edited-summary v0_edited_summary.tsv.

When reviewing summary.tsv, you may find a collection in the RenameEntitySet column that you want to discard, such as an incomplete acquisition. Use --remove-RenameEntitySet with that collection’s entity set. CuBIDS writes 0 to MergeInto in the derived summary and then uses the normal apply deletion path. That path deletes the matching image and, when present, its standard BIDS companions, including JSON sidecars and modality-specific files. It also removes the image from applicable *_scans.tsv tables and every IntendedFor list that references it.

When you combine the two options, the substitutions run first, so name a collection here by the entity set --change-RenameEntitySet leaves it with, not the one the summary started with. For example:

$ cubids apply /data/bids v0_summary.tsv v0_files.tsv v1 \
    --remove-RenameEntitySet acquisition-VARIANTVar1_datatype-dwi_direction-AP_run-01_suffix-dwi \
    --write-edited-summary v0_edited_summary.tsv

Repeat the option for each collection to delete, or list the entity sets in a CSV or TSV file with an entity_set column, one entity set per row, and pass that file instead:

entity_set
datatype-fmap_direction-AP_fmap-epi_suffix-epi
datatype-fmap_direction-PA_fmap-epi_suffix-epi

As described under File collection variants, list every member of a file collection. If the request would split a collection, apply stops and names the entity sets that still need to be included.

Deleting a mistake

To remove files in a Parameter Group from your BIDS data, you simply set the MergeInto value to 0. We see in our data that there is a strange scan that has a RepetitionTime of 12.3 seconds and is also variant with respect to EffectiveEchoSpacing and EchoTime. We elect to remove this scan from our dataset because we do not want these parameters to affect our analyses. To remove these files from your BIDS data, add a 0 to MergeInto and save the new tsv as v0_edited_summary.tsv

Note

The file collection safeguards described under File collection variants also apply to deletions requested by editing MergeInto.

Pre Apply Groupings with Deletion Requested

Notes	ManualCheck	MergeInto	RenameEntitySet	KeyParamGroup	EntitySet	ParamGroup	Counts	Dim1Size	Dim2Size	Dim3Size	EchoTime	EffectiveEchoSpacing	FlipAngle	HasFieldmap	EntitySetCount	Modality	NSliceTimes	NumVolumes	Obliquity	ParallelReductionFactorInPlane	PartialFourier	PhaseEncodingDirection	RepetitionTime	TotalReadoutTime	UsedAsFieldmap	VoxelSizeDim1	VoxelSizeDim2	VoxelSizeDim3
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTNoFmap	datatype-dwi_run-1_suffix-dwi__2	datatype-dwi_run-1_suffix-dwi	2	25	128	128	70	0.082	0.000267	90	FALSE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime	datatype-dwi_run-1_suffix-dwi__3	datatype-dwi_run-1_suffix-dwi	3	6	128	128	70	0.082	0.000267	90	TRUE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	9.0	0.034	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime	datatype-dwi_run-1_suffix-dwi__4	datatype-dwi_run-1_suffix-dwi	4	3	128	128	70	0.082	0.000267	90	TRUE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	9.8	0.034	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTDim3SizeVoxelSizeDim3	datatype-dwi_run-1_suffix-dwi__5	datatype-dwi_run-1_suffix-dwi	5	2	128	128	46	0.082	0.000267	90	TRUE	1426	dwi	46	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	3.0
		0	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTEchoTimeEffectiveEchoSpacingRepetitionTimeTotalReadoutTime	datatype-dwi_run-1_suffix-dwi__6	datatype-dwi_run-1_suffix-dwi	6	1	128	128	70	0.102	0.0008	90	TRUE	1426	dwi	70	35.0	FALSE	3.0	0.75	j-	12.3	0.102	FALSE	1.875	1.875	2.0
			datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTObliquity	datatype-dwi_run-1_suffix-dwi__7	datatype-dwi_run-1_suffix-dwi	7	1	128	128	70	0.082	0.000267	90	TRUE	1426	dwi	70	35.0	TRUE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0

In this example, users can apply the changes to BIDS data using the following command:

$ cubids apply FULL/PATH/TO/BIDS/DIR FULL/PATH/TO/v0_edited_summary.tsv FULL/PATH/TO/v0_files.tsv FULL/PATH/TO/v1

The changes in v0_edited_summary.tsv will be applied to the BIDS data and the new Entity and Parameter Groups will be saved to tsv files starting with v1.

Applying these changes we would see:

Post Apply Groupings

Notes	ManualCheck	MergeInto	RenameEntitySet	KeyParamGroup	EntitySet	ParamGroup	Counts	Dim1Size	Dim2Size	Dim3Size	EchoTime	EffectiveEchoSpacing	FlipAngle	HasFieldmap	EntitySetCount	Modality	NSliceTimes	NumVolumes	Obliquity	ParallelReductionFactorInPlane	PartialFourier	PhaseEncodingDirection	RepetitionTime	TotalReadoutTime	UsedAsFieldmap	VoxelSizeDim1	VoxelSizeDim2	VoxelSizeDim3
				datatype-dwi_run-1_suffix-dwi__1	datatype-dwi_run-1_suffix-dwi	1	1388	128	128	70	0.082	0.000267	90	TRUE	1388	dwi	70	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0
				datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTNoFmap__1	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTNoFmap	1	25	128	128	70	0.082	0.000267	90	FALSE	25	dwi	70	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0
				datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime__1	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime	1	6	128	128	70	0.082	0.000267	90	TRUE	9	dwi	70	35.0	FALSE	3.0	0.75	j-	9.0	0.034	FALSE	1.875	1.875	2.0
				datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime__2	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTRepetitionTime	2	3	128	128	70	0.082	0.000267	90	TRUE	9	dwi	70	35.0	FALSE	3.0	0.75	j-	9.8	0.034	FALSE	1.875	1.875	2.0
				datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTDim3SizeVoxelSizeDim3__1	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTDim3SizeVoxelSizeDim3	1	2	128	128	46	0.082	0.000267	90	TRUE	2	dwi	46	35.0	FALSE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	3.0
				datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTEchoTimeEffectiveEchoSpacingRepetitionTimeTotalReadoutTime__1	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTEchoTimeEffectiveEchoSpacingRepetitionTimeTotalReadoutTime	1	1	128	128	70	0.102	0.0008	90	TRUE	1	dwi	70	35.0	FALSE	3.0	0.75	j-	12.3	0.102	FALSE	1.875	1.875	2.0
				datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTObliquity__1	datatype-dwi_run-1_suffix-dwi_acquisition-VARIANTObliquity	1	1	128	128	70	0.082	0.000267	90	TRUE	1	dwi	70	35.0	TRUE	3.0	0.75	j-	8.1	0.034	FALSE	1.875	1.875	2.0

Customizable configuration

CuBIDS also features an optional, customizable, MRI image type-specific configuration file. This file can be passed as an argument to cubids group and cubids apply using the --config flag and allows users to customize grouping settings based on MRI image type and parameter. Each Entity Set is associated with one (and only one) MRI image type, as BIDS filenames include MRI image type-specific values as their suffixes.

This easy-to-modify configuration file provides several benefits to curation. First, it allows users to add and remove metadata parameters from the set that determines groupings. This can be very useful if a user deems a specific metadata parameter irrelevant and wishes to collapse variation based on that parameter into a single Parameter Group. Second, the configuration file allows users to apply tolerances for parameters with numerical values. This functionality allows users to avoid very small differences in scanning parameters (i.e., a TR of 3.0s vs 3.0001s) being split into different Parameter Groups. Third, the configuration file allows users to determine which scanning parameters are listed in the acquisition field when auto-renaming is applied to Variant Groups.

Exemplar testing

In addition to facilitating curation of large, heterogeneous BIDS datasets, CuBIDS also prepares datasets for testing BIDS Apps. This portion of the CuBIDS workflow relies on the concept of the Acquisition Group: a set of sessions that have identical scan types and metadata across all imaging modalities present in the session set. Specifically, cubids copy-exemplars copies one subject from each Acquisition Group into a separate directory, which we call an Exemplar Dataset. Since the Exemplar Dataset contains one randomly selected subject from each unique Acquisition Group in the dataset, it will be a valid BIDS dataset that spans the entire metadata parameter space of the full study. If users run cubids copy-exemplars with the --use-datalad flag, the program will ensure that the Exemplar Dataset is tracked and saved in DataLad. If the user chooses to forgo this flag, the Exemplar Dataset will be a standard directory located on the filesystem. Once the Exemplar Dataset has been created, a user can test it with a BIDS App (e.g., fMRIPrep or QSIPrep) to ensure that each unique set of scanning parameters will pass through the pipelines successfully. Because BIDS Apps auto-configure workflows based on the metadata encountered, they will process all scans in each Acquisition Group in the same way. By first verifying that BIDS Apps perform as intended on the small sub-sample of participants present in the Exemplar Dataset (that spans the full variation of the metadata), users can confidently move forward processing the data of the complete BIDS dataset.

In the next section, we’ll introduce DataLad and walk through a real example.

Footnotes

[1]

PNC: The Philadelphia Developmental Cohort.