osprey (CBRAIN Tool Config ID: 9242)
Container: docker://dcanumn/osprey-bids:v4.2.1
Documentation: https://osprey-bids.readthedocs.io/en/latest/
Boutiques Descriptor: https://portal.cbrain.mcgill.ca/tool_configs/9242/boutiques_descriptor.json
name: OSPREY
description: Osprey is an all-in-one software suite for state-of-the art processing and quantitative analysis of in-vivo magnetic resonance spectroscopy (MRS) data.
External Requirements
These are file-based requirements, external to the pipeline, that must be satisfied for processing to occur. The “Argument IDs” field corresponds to input “id”s within the tool Boutiques Descriptor. “Value”s correspond to either specific configuration files (if there is a numeric value), or otherwise broader file types within CBRAIN (if the entry is text-based).
Argument ID |
Flag |
Value |
Description |
|---|---|---|---|
SubjectDirectory |
n/a |
BidsSubject |
The study-wide BIDS directory. In CBRAIN this is also referred to (and used) as the subject directory since a new BIDS dir will be made for the selected subject prior to processing. |
CabinetOutput |
–segmentation-dir |
BibsnetOutput |
The output folder from a previously computed CABINET run. This will provide OSPREY with a segmentation map to do partial volume correction. The pipeline will look for CabinetOutput/precomputed/sub*/ses*/anat/*_space-orig_desc-aseg_dseg.nii.gz) |
CabinetOutputJson |
n/a |
4322917 |
The JSON file that come with the output folder from a previously computed CABINET run. |
JSONConfig |
n/a |
The JSON file used to configure OSPREY processing. |
Ancestor Pipelines
This pipeline utilizes outputs from the following pipelines that are also ran in CBRAIN:
bibsnet
Other Processing Settings
These additional settings cover everything outside of files that are used as inputs during processing. The settings cover numeric values, flags, outputs directories, and other settings that are used to configure processing.
Argument ID |
Flag |
Value |
Description |
|---|---|---|---|
LocalizerRegistration |
–localizer_registration |
True |
Align the anatomical reference to a localizer scan. If this flag is used, processing will be skipped for sessions without a scan in the anat dir with *localizer* in the name. |
OSPREYOutputDirectoryName |
n/a |
output |
The name of the output directory to store outcomes of preprocessing and reports. When processing is ran via CBRAIN only subject-specific files/folders will be saved, so the naming of the output folder will not influence the final naming/destination of files/folders. |
LocSearchTerm |
–localizer_search_term |
*mrsLocAx*.nii* |
Search Term for Localizer Scan (‘i.e. *localizer*.nii) |
derivatives_prefix |
n/a |
Folders to put before the pipeline specific folder. By default this will look like DataProvider/derivatives/PipelineName, where pipeline name is specific to the current pipeline. The provided string must end in / |
|
TermsNotAllowedInAnat |
–terms_not_allowed_in_anat |
[‘mrs’, ‘Loc’] |
One or more terms, seperated by spaces, that have to be absent for a file to be considered an anatomical scan. Mainly useful for avoiding confusion between primary anat and localizer scans. |
PreferredAnatModality |
–preferred_anat_modality |
T2w |
The preferred modality to use for anatomical images (must be one of: T1w, T2w, none). If set to none, no anatomical information will be used in processing. This can be of interest for QC purposes. |
Pipeline Outputs
Following processing, a number of files and folders are identified as outputs that should be saved for future reference. In the following table the ‘Path Relative to Working Directory’ column specifies the location of files that should be saved (with ‘*’ denoting wildcards). The output location for these files in the final ‘DataProvider’ is specified in the ‘Path in Output Data Provider’ column. In the case of HBCD the [DERIVATIVES_PREFIX] entry is empty.
ID |
Path Relative to Working Directory |
Path in Output DataProvider |
Description |
|---|---|---|---|
OutputDirectory |
[OSPREYOutputDirectoryName]/[SubjectDirectory] |
[DERIVATIVES_PREFIX]osprey |
The output directory to store outcomes of preprocessing and reports |
Command Line Template
The following code-snippet highlights how the tool is referenced on the command-line. The code being displayed is executed within the tool’s container. Some of the directives may describe file manipulations to prepare for processing, and other directives will describe the primary processing command. At the time of processing, the text in brackets will be replaced by text that has been provided to configure processing.
true [DERIVATIVES_PREFIX]; true [SubjectDirectory] ; rm -f CbrainBidsSingleSubject/[SubjectDirectory] ; cp -p -R -L [SubjectDirectory] CbrainBidsSingleSubject/[SubjectDirectory] ; osprey CbrainBidsSingleSubject [OSPREYOutputDirectoryName] participant [JSONConfig] [ParticipantLabel] [SessionLabel] [CabinetOutput] [LocalizerRegistration] [LocSearchTerm] [PreferredAnatModality] [TermsNotAllowedInAnat] [RequireSUIDMatch]
File Selection For Processing
The first step of selecting a candidate for processing is determining whether the right files are present. In HBCD processing, pipelines are always run on one session worth of data at a time. With that in mind, we (mostly) query the contents of a subject’s session folder to determine if processing should occur and also which files should be included in processing. For every pipeline there will be at least one requirement group that determines what files are needed for processing to occur. Within a requirement group, there may be criteria that address multiple file (or modality) types, which are known as ‘File Groups’. For processing to occur, the minumum number of files surviving all Included/Excluded terms for a given ‘File Group’ must be satisfied.
To allow for more flexible selection of files for processing, there are often multiple ‘Requirement Groups’. The contents of each ‘File Group’ across ‘Requirement Groups’ must be the same, but which ‘File Groups’ are defined can be different. If multiple ‘Requirement Groups’ are present for the current pipeline, there will be multiple tables in this section. Only one ‘Requirement Group’ needs to be satisfied for processing to occur. If one requirement group is satisfied, then files from all ‘File Groups’ will be included in processing.
Beyond the files that are chosen from this procedure, other associated files defined via the table here will also be included in processing.
Requirement Group: osprey_1
File Group |
How Many To Keep |
Term |
Included (True)/Excluded (False) |
|---|---|---|---|
T1 |
1 |
T1w.nii.gz |
True |
rec-undistorted |
False |
||
acq-svslocalizer |
False |
||
acq-mrsLoc |
False |
||
_QALAS.nii.gz |
False |
||
T2 |
1 |
T2w.nii.gz |
True |
rec-undistorted |
False |
||
acq-svslocalizer |
False |
||
acq-mrsLoc |
False |
||
_QALAS.nii.gz |
False |
||
shortTE |
All |
acq-shortTE |
True |
HERCULES |
All |
acq-hercules |
True |
localizer |
All |
mrsLocCor |
False |
Loc |
True |
||
T2w.nii.gz |
True |
||
rec-undistorted |
False |
||
scans.tsv |
All |
scans.tsv |
True |
sessions.tsv |
All |
sessions.tsv |
True |
Requirement Group: osprey_2
File Group |
How Many To Keep |
Term |
Included (True)/Excluded (False) |
|---|---|---|---|
T2 |
1 |
T2w.nii.gz |
True |
rec-undistorted |
False |
||
acq-svslocalizer |
False |
||
acq-mrsLoc |
False |
||
_QALAS.nii.gz |
False |
||
shortTE |
All |
acq-shortTE |
True |
HERCULES |
All |
acq-hercules |
True |
localizer |
All |
mrsLocCor |
False |
Loc |
True |
||
T2w.nii.gz |
True |
||
rec-undistorted |
False |
||
scans.tsv |
All |
scans.tsv |
True |
sessions.tsv |
All |
sessions.tsv |
True |
Quality Control Selection Information
The previous section of this page highlighted how to look at a file’s name to determine whether it may belong to a specific ‘File Group’ (such as T2w images) that are needed for processing. Beyond this, it is often necessary to look at some QC criteria to determine whether a file should be included in processing. This section defines the QC criteria that is used to evaluate specific images. These QC criteria always operate on one file group at a time. If a file group uses QC criteria to select images, at least one table will be displayed below. Depending on the context, these criteria will be used to exclude certain images from processing, to find the best available image(s) within a specific category, or to exclude a session from processing. If sorting is the goal, the first row will be considered the most important criteria. In certain cases, not all images will have ratings for a specific QC field. In this case, a backup table (which will be displayed after the first table if available), will be used for that file group.
File Group: T1
Processing will look for best 1 file(s) to keep using the following criteria(s).
scans.tsv Field |
Operator |
Value |
|---|---|---|
QC |
equals |
1 |
QU_motion |
less_than |
2.01 |
aqc_motion |
less_than |
10000 |
brain_SNR |
greater_than |
-1000 |
scans.tsv Field |
Operator |
Value |
|---|---|---|
QC |
equals |
1 |
aqc_motion |
less_than |
10000 |
brain_SNR |
greater_than |
-1000 |
File Group: T2
Processing will look for best 1 file(s) to keep using the following criteria(s).
scans.tsv Field |
Operator |
Value |
|---|---|---|
QC |
equals |
1 |
QU_motion |
less_than |
2.01 |
aqc_motion |
less_than |
10000 |
brain_SNR |
greater_than |
-1000 |
scans.tsv Field |
Operator |
Value |
|---|---|---|
QC |
equals |
1 |
aqc_motion |
less_than |
10000 |
brain_SNR |
greater_than |
-1000 |