Merge pull request #792 from rordenlab/development

version 2-February-2024

.appveyor.yml

@@ -78,8 +78,8 @@ for:
       - mkdir -p build/bin
       - lipo -create -output build/bin/dcm2niix intel/bin/dcm2niix apple/bin/dcm2niix
       - strip -Sx build/bin/*
-      - 7z a dcm2niix_macos.zip ./build/bin/* &>/dev/null
-      - appveyor PushArtifact dcm2niix_macos.zip
+      - 7z a dcm2niix_mac.zip ./build/bin/* &>/dev/null
+      - appveyor PushArtifact dcm2niix_mac.zip
 
 deploy:
   - provider: GitHub

BIDS/README.md

@@ -263,7 +263,7 @@ Note that [many of the fields listed by BIDS](https://bids-specification.readthe
 |---------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
 | ArterialSpinLabelingType        |                    | `PASL` or `PCASL`                                                                                                                                                                              | B          |
 | LabelOffset                     |                    | 2D pCASL [ep2d_pcasl](http://www.loft-lab.org)                                                                                                                                                 | D          |
-| PostLabelDelay                  | s                  | 2D pCASL [ep2d_pcasl](http://www.loft-lab.org), [FAIREST](https://pubmed.ncbi.nlm.nih.gov/11746944/) (`ep2d_fairest`)                                                                          | D          |
+| PostLabelingDelay               | s                  | 2D pCASL [ep2d_pcasl](http://www.loft-lab.org), [FAIREST](https://pubmed.ncbi.nlm.nih.gov/11746944/) (`ep2d_fairest`)                                                                          | B          |
 | PostInversionDelay              | s                  | 2D [FAIREST](https://pubmed.ncbi.nlm.nih.gov/11746944/) (`ep2d_fairest`)                                                                                                                       | D          |
 | NumRFBlocks                     |                    | 2D pCASL [ep2d_pcasl](http://www.loft-lab.org)                                                                                                                                                 | D          |
 | RFGap                           |                    | 2,3D pCASL [ep2d_pcasl, tgse_pcasl](http://www.loft-lab.org)                                                                                                                                   | D          |
@@ -334,7 +334,7 @@ Fields specific to [Siemens XA-series](https://github.com/rordenlab/dcm2niix/tre
 | ReceiveCoilActiveElements    |      | DICOM tag 0021,114F        | B          |
 | BandwidthPerPixelPhaseEncode | Hz   | DICOM tag 0021,1153        | D          |
 | ScanningSequence             |      | DICOM tag 0021,105a        | D          |
-| PostLabelDelay               | s    | DICOM tag 0018,9258        | D          |
+| PostLabelingDelay            | s    | DICOM tag 0018,9258        | B          |
 | NonlinearGradientCorrection  | b    | 0008,0008 or 0021,1175     | B          |
 | PhaseEncodingDirection       |      | polarity from 0021,111c    | B          |
 | SpoilingState                |      | 0021,105B                  | B          |
@@ -349,3 +349,7 @@ Fields specific to United Imaging Healthcare systems (e.g. uMR 770).
 |--------------------------------|------|--------------------------|------------|
 | BandwidthPerPixelPhaseEncode   | Hz   | DICOM tag 0019,1028      | B          |
 | ParallelReductionFactorInPlane |      | DICOM tag 0065,100D      | B          |
+
+### Notes
+
+ - Prior to v1.0.20230411, dcm2niix created the internal tag `PostLabelDelay`, subsequent versions use the newly introduced BIDS tag `PostLabelingDelay`

BidsGuess/README.md

@@ -0,0 +1,63 @@
+## About
+
+**The BidsGuess feature is intended for wrapper developers only and should not be used in isolation of a wrapper**
+
+dcm2niix version v1.0.20230731 and later will insert the field `BidsGuess` into the [BIDS](https://bids-specification.readthedocs.io/en/stable/) JSON sidecar files. This experimental feature is designed to aid wrappers that use dcm2niix to create BIDS compatible datasets. BIDS aids reproducible, reusable and automatic analysis of neuroimaging data.  This feature was inspired by the automatic BIDS conversion wrappers [niix2bids](https://github.com/benoitberanger/niix2bids) and [ezBIDS](https://brainlife.io/ezbids/). The `BidsGuess` field can be leveraged by wrappers to fully automate conversion (though this will likely require a ezBIDS style user validation) or to flag improbable naming from user configuration files.
+
+## Compiling the development branch
+
+The BidsGuess feature is currently only available in the development branch, so you will need to compile and run this version (v1.0.20230731 and later).
+
+```
+git clone --branch development https://github.com/rordenlab/dcm2niix.git
+cd dcm2niix/console
+make
+./dcm2niix
+```
+
+## A concrete example
+
+The BidsGuess feature is designed to be leveraged by dcm2niix wrappers, and not used to directly create BIDS format files. Specifically, bidsGuess converts each DICOM series in isolation, and has no information about the user intention. Therefore, it is unable to resolve fieldmap [IntendedFor](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#using-intendedfor-metadata), unable to distinguish fMRI tasks from resting state, BIDS subject ID, BIDS session number, or create meaningful [dataset_description](https://bids-specification.readthedocs.io/en/stable/glossary.html#dataset_description-files) or [readme](https://bids-specification.readthedocs.io/en/stable/glossary.html#readme-files) files.
+
+For the developers of wrappers, you can use the hazardous file naming argument (`-f $h`) to create a minimal BIDS structure for the [bids-validator](https://github.com/bids-standard/bids-validator). Note that this mode will always claim that the data is from `sub-1` and that data is only from a single session. Here is a simple example:
+
+```
+cd ~
+mkdir bids
+git clone [email protected]:neurolabusc/dcm_qa_pdt2.git
+dcm2niix -f %h -w 1 -i y -o ~/bids ~/dcm_qa_pdt2
+bids-validator ~/bids
+```
+You can see that the bids-validator is happy with the results and that the data appears organized correctly:
+
+![BidsGuess](BidsGuess.png)
+
+Inspecting the JSON files, we can see that dcm2niix has suggested a likely <[datatype](https://bids-specification.readthedocs.io/en/stable/schema/index.html#bids-filenames)> (`anat`) and <[entities](https://bids-specification.readthedocs.io/en/stable/schema/index.html#bids-filenames)>.
+
+```
+	"BidsGuess": ["anat","_acq-tse2_run-3_PDw"],
+	"BidsGuess": ["anat","_acq-tse2_run-3_T2w"],
+```
+
+Developers can use the `hazardous` file naming to validate and extend the modality detection. However, production quality wrappers should use the `BidsGuess` in the JSON file combined by a file naming scheme that avoids name clashes between different participants and sessions (e.g. one can segment data by datetime, series and protocol name with `-f %t/%s_%p`).
+
+## The acq entity
+
+The `BidsGuess` creates a meaningful [`_acq-` entity](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#acq) that can provide consistency across wrappers, minimizes the risk of naming clashes and allows users to quickly detect sequence details. The first part of this reveals the manufacturer's name for the sequence. For example, a Siemens 2D turbo spin-echo will report `tse2`, while a 2D echo-planar spin-echo will report `epse2` and a 3D turbo flash will report `tfl3`. If acceleration was used, this will be reported next. For example, a 2D echo-planar gradient-echo with x3 in-plane and x4 mult-iband acceleration would be reported as `epfid2p3m4`.
+
+## The run entity
+
+The `BidsGuess` will typically include a [`_run-` entity](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#run) that reports the DICOM series number of an image. This is often useful for determining the temporal order of images (e.g. if the first attempt to acquire the data was due to head motion). This entity also avoids naming clashes. Note that wrapper developers may want to remove this entity from the BIDS guess - it is redundant with the `SeriesNumber` stored in the sidecar JSON. Finally, dcm2niix will not append a `_run` entity for fieldmaps: the BIDS validation tool expects that the different images associated with a fieldmap have identical file names except the suffix (e.g. `magnitude1` and `phasediff`).
+
+## The dir entity
+
+The `BidsGuess` will typically include a [`_dir-` entity](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#dir) for modalities when required by the BIDS validator. This field is redundant with the JSON `PhaseEncodingDirection` field. Note that the JSON uses the values `j`, `j-`, `k` and `k-` to specify row versus column and polarity. In contrast, the BidsGuess will use the `AP`, `PA`, `LR`, and `RL` tags though note these tags will only be correct for axial acquisitions. Note that it is impossible to infer phase encoding polarity for Philips data, so this entity will not be populated leading to errors from the bids-validator.
+
+## Limitations
+
+This feature is very experimental, and is currently provided to get feedback from wrapper developers and to get community support to enhance the guessing accuracy.
+
+ - This feature currently only supports images from GE, Philips and Siemens MR scanners.
+ - Multi-Echo MP-RAGE where individual echos (rather than mean) are saved will include the [_echo](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#echo) entity to distinguish them, e.g. `_acq-tflme3p2_run-5_echo-2_T1w`, `_acq-tflme3p2_run-5_echo-1_T1w`. This will [cause issues](https://github.com/bids-standard/bids-specification/issues/654) with the current bids-validator.
+ - ASL datasets will generate errors with the bids-validator. The ASL BEP introduced many required tags for converted data without explaining how these are determined or even if they exist in the core DICOM images. The validation dataset [only provides the desired BIDS translation and not the source DICOMs](https://osf.io/yru2q/).
+ - Philips DICOMs are underspecified for BIDS conversion. Beyond the previously noted issue with phaseEncodingDirection, the `SliceTiming` is also unknown. This is a limitation of Philips DICOM, not dcm2niix.

CONTRIBUTE.md

@@ -7,7 +7,7 @@ Like the [Brain Imaging Data Structure](https://bids.neuroimaging.io/get_involve
 The easiest way to contribute to dcm2niix is to ask questions you have by [generating Github issues](https://github.com/rordenlab/dcm2niix/issues) or [asking a question on the NITRC forum](https://www.nitrc.org/forum/?group_id=880). 
 
 The code is open source, and you can share your improvements by [creating a pull request](https://github.com/rordenlab/dcm2niix/pulls).
-dcm2niix is a community project that has benefitted from many [contrbutors](https://github.com/rordenlab/dcm2niix/graphs/contributors). 
+dcm2niix is a community project that has benefitted from many [contributors](https://github.com/rordenlab/dcm2niix/graphs/contributors). 
 
 The INCF suggests indicating who is responsible for maintaining software for [stability and support](https://incf.org/incf-standards-review-criteria-v20). Therefore, below we indicate several active contributors and their primary domain of expertise. However, this list is not comprehensive, and it is noted that the project has been supported by contributions from many users. This list does not reflect magnitude of prior contributions, rather it is a non-exhaustive list of members who are actively maintaining the project.
 

FILENAMING.md

@@ -39,12 +39,13 @@ In general dcm2niix creates images with 3D dimensions, or 4 dimensions when the
  - _cNx.._cNz  where C* refers to the coil name (typically only seen for uncombined data, where a separate image is generated for each antenna)
  - _e1..eN echo number for multi-echo sequences
  - _Eq is commonly seen in [CT scans](https://github.com/neurolabusc/dcm_qa_ct). For example, CT scans of the brain often have many slices closely packed near the brain stem and only a few slices spread far apart near the top of the head. Variable between-slice spacing is rarer in MRI, and if you see this from a MRI sequence you should ensure that [all of the acquired slices have been provided to dcm2niix](https://neurostars.org/t/field-mapping-siemens-scanners-dcm2niix-output-2-bids/2075/7). NIfTI assumes all 2D slices that form a 3D stack are equidistant. Therefore, dcm2niix reslices the input data to generate an equidistant volume.
- - _ph phase map
- - _iN appended image number for non-parallel slices
+ - _i1..N appended image number for non-parallel slices
  - _imaginary imaginary component of complex image
  - _MoCo is appended to the ProtocolName if Image Type (0008,0008) includes the term 'MOCO'. This helps disambiguate Siemens fMRI runs where both motion corrected and raw data is stored for a single session.
- - _real real component of complex image
+ - _ph phase map
  - _phMag rare case where phase and magnitude are saved as the 4th dimension
+ - _r1..rN repetition number for sequences with multiple repetition times
+ - _real real component of complex image
  - _t  If the trigger delay time (0020,9153) or trigger time (0018,1060) is non-zero, it will be recorded in the file name. For example, the files "T1_t178.nii" and "T1_t511" suggests that the T1 scan was acquired with two cardiac trigger delays (178 and 511ms after the last R-peak).
  - _Tilt is specific to [CT scans](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Computed_Tomography_.28CT.2C_CAT.29). These scans can be acquired with a gantry tilt that causes a skew that can not be stored in a NIfTI qForm. Therefore, the slices are resampled to remove the effect of tilt.
 
@@ -69,7 +70,7 @@ dcm2niix will attempt to write your image using the naming scheme you specify wi
 
 ## Special Characters
 
-[Some characters are not permitted](https://stackoverflow.com/questions/1976007/what-characters-are-forbidden-in-windows-and-linux-directory-names) in file names. The following characters will be replaced with underscorces (`_`). Note that the forbidden characters vary between operating systems (Linux only forbids the forward slash, MacOS forbids forward slash and colon, while Windows forbids any of the characters listed below). To ensure that files can be easily copied between file systems, [dcm2niix restricts file names to characters allowed by Windows](https://github.com/rordenlab/dcm2niix/issues/237). While technically legal in all filesystems, the semicolon can wreak havoc in [Windows](https://stackoverflow.com/questions/3869594/semi-colons-in-windows-filenames) and [Linux](https://forums.plex.tv/t/linux-hates-semicolons-in-file-names/49098/2). 
+[Some characters are not permitted](https://stackoverflow.com/questions/1976007/what-characters-are-forbidden-in-windows-and-linux-directory-names) in file names. The following characters will be replaced with underscorces (`_`). Note that the forbidden characters vary between operating systems (Linux only forbids the forward slash, MacOS forbids forward slash and colon, while Windows forbids any of the characters listed below). To ensure that files can be easily copied between file systems, [dcm2niix restricts file names to characters allowed by Windows](https://github.com/rordenlab/dcm2niix/issues/237). While technically legal in all filesystems, the semicolon can wreak havoc in [Windows](https://stackoverflow.com/questions/3869594/semi-colons-in-windows-filenames) and [Linux](https://forums.plex.tv/t/linux-hates-semicolons-in-file-names/49098/2). Likewise, the [dollar sign can cause issues](https://github.com/rordenlab/dcm2niix/issues/749).
 
 ### List of Forbidden Characters
 ```
@@ -82,7 +83,8 @@ dcm2niix will attempt to write your image using the naming scheme you specify wi
 | (vertical bar or pipe)
 ? (question mark)
 * (asterisk)
-; (semicolon) 
+; (semicolon)
+$ (dollar sign)
 ```
 
 [Control characters](https://en.wikipedia.org/wiki/ASCII#Control_characters) like backspace and tab are also forbidden.