Skip to content

Commit

Permalink
Merge pull request rordenlab#624 from rordenlab/development
Browse files Browse the repository at this point in the history
New stable release
  • Loading branch information
neurolabusc authored Aug 4, 2022
2 parents 002ebcd + f2ceab6 commit bb3a6c3
Show file tree
Hide file tree
Showing 29 changed files with 5,051 additions and 251 deletions.
4 changes: 2 additions & 2 deletions BATCH.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ The configuration file should be in yaml format as shown in example `batch_confi
```yaml
Options:
isGz: false
isFlipY: true
isFlipY: false
isVerbose: false
isCreateBIDS: true
isCreateBIDS: false
isOnlySingleFile: false
Files:
-
Expand Down
27 changes: 18 additions & 9 deletions BIDS/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ The Defined By column uses:

The Unit column uses:

- b : boolean
- deg : degrees
- f : fraction
- kg : Kilogram
Expand Down Expand Up @@ -214,15 +215,19 @@ Data unique to [GE](https://github.com/rordenlab/dcm2niix/tree/master/GE). Deter
| PulseSequenceName | | `epi` or `epiRT` | D |
| InternalPulseSequenceName | | `EPI` or `EPI2` | D |
| PhaseEncodingPolarityGE | | `Unflipped` or `Flipped` | D |
| ASLContrastTechnique | | DICOM tag 0043,10A3 | D |
| ASLLabelingTechnique | | DICOM tag 0043,10A4 | D |
| LabelingDuration | s | DICOM tag 0043,10A5 | B |
| MultibandAccelerationFactor | | DICOM tag 0043,1083 | B |
| PostLabelingDelay | s | DICOM tag 0018,0082 (TI) | B |
| NumberOfPointsPerArm | | DICOM tag 0027,1060 | D |
| NumberOfArms | | DICOM tag 0027,1061 | D |
| NumberOfExcitations | | DICOM tag 0027,1062 | D |
| ShimSetting[0] | | DICOM tag 0043,1002 | D |
| ShimSetting[1] | | DICOM tag 0043,1003 | D |
| ShimSetting[2] | | DICOM tag 0043,1004 | D |
| ParallelReductionFactorInPlane | | DICOM tag 0043,1083 | B |
| PostLabelingDelay | s | DICOM tag 0018,0082 (TI) | B |
| PrescanReuseString | | DICOM tag 0043,1095 | D |
| MultibandAccelerationFactor | | DICOM tag 0043,1083 | B |
| ASLContrastTechnique | | DICOM tag 0043,10A3 | D |
| ASLLabelingTechnique | | DICOM tag 0043,10A4 | D |
| LabelingDuration | s | DICOM tag 0043,10A5 | B |

### Manufacturer Philips

Expand Down Expand Up @@ -312,15 +317,19 @@ Fields specific to Siemens V*-series (e.g. VB, VE) MRI systems (e.g. Verio, Trio
| DwellTime | | DICOM tag 0019,1018 | B |
| BandwidthPerPixelPhaseEncode | Hz | DICOM tag 0019,1028 | D |
| ImageOrientationText | | DICOM tag 0051,100E | D |
| NonlinearGradientCorrection | b | DICOM tag 0008,0008 | B |

### Manufacturer Siemens Magnetic Resonance Imaging (XA)

Fields specific to Siemens XA-series MRI systems (Sola, Vida).

| Field | Unit | Comments | Defined By |
|------------------------------|------|---------------------|------------|
| ReceiveCoilActiveElements | | DICOM tag 0021,114F | B |
| BandwidthPerPixelPhaseEncode | Hz | DICOM tag 0021,1153 | D |
| Field | Unit | Comments | Defined By |
|------------------------------|------|------------------------|------------|
| 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 |
| NonlinearGradientCorrection | b | 0008,0008 or 0021,1175 | B |

### Manufacturer UIH

Expand Down
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
cmake_minimum_required(VERSION 2.8.11)
cmake_minimum_required(VERSION 2.8.12)

if(COMMAND CMAKE_POLICY)
CMAKE_POLICY(SET CMP0003 NEW)
Expand Down
12 changes: 10 additions & 2 deletions Canon/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,26 @@ dcm2niix can convert Canon (né Toshiba) DICOM format images to NIfTI. This page

Users of Canon MRI equipment are strongly advised to export data from their scanners as enhanced DICOM (with all images from the series stored as a single file) rather than classic DICOM (each 2D slice stored as a separate file). Limitations of the Canon classic DICOMs are described [here](https://github.com/rordenlab/dcm2niix/issues/495) and [here](https://github.com/neurolabusc/dcm_qa_canon).

## Avoid Enhanced DICOM

Users of Canon MRI equipment are strongly advised to export data from their scanners as classic DICOM (with each slice from the series stored as a separate files) rather than enhanced DICOM. The enhanced 4D sequences such as fMRI incorrectly sets the public tag TemporalPositionIndex (0020,9128) as 1 for all volumes: both (0020,9157) and (0020,9128). This is a violation of the DICOM standard and interferes with attempts to sort data into the correct temporal order. Any software or user who assumes these tags are truthful will fail.

## The Enhanced versus Classic DICOM dilemma

The prior two sections provide conflicting advice, due to limitations in both the classic and enhanced datasets generated by Canon instruments. Users of Canon equipment should lobby the manufacturer to honor their DICOM conformance statement. DICOM data from Canon instruments may not be handled correctly by any software tool including dcm2niix. This reflects a limitation in the source DICOM data, not dcm2niix.

## Diffusion Weighted Imaging Notes

In contrast to several other vendors, Toshiba used public tags to report diffusion properties. Specifically, [DiffusionBValue (0018,9087)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,9087)) and [DiffusionGradientOrientation (0018,9089)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,9089)). Be aware that these tags are only populated for images where a diffusion gradient is applied. Consider a typical diffusion series where some volumes are acquired with B=0 while others have B=1000. In this case, only the volumes with B>0 will report a DiffusionBValue. These coordinates are with respect to the scanner bore, not image space.

Since the acquisition by Canon, these public tags are no longer populated for images saved in classic 2D DICOM format. The diffusion gradient directions are now stored in the ASCII Image Comments tag. Like GE (but unlike [Siemens, GE and Toshiba](https://www.na-mic.org/wiki/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI)), these directions are with respect to the image space, not the scanner bore. Further, gradient direction is not adjusted for phase encoding polarity, and it is impossible to determine phase encoding polarity. For detailed discussion and a validation dataset that exhibits these attributes please see [dcm_qa_canon](https://github.com/neurolabusc/dcm_qa_canon). A Canon classic DICOM DWI image may report:
Be aware that Canon software V6.0 stored diffusion directions in the ASCII Image Comments tag when exporting to classic DICOM. For detailed discussion and a validation dataset that exhibits these attributes please see [dcm_qa_canon](https://github.com/neurolabusc/dcm_qa_canon). A Canon classic DICOM DWI image may report:

```
(0018,9087) FD 1500 # 8, 1 DiffusionBValue
(0020,4000) LT [b=1500(0.445,0.000,0.895)] # 26, 1 ImageComments
```

In contrast, when exporting images as enhanced (4D) DICOM, information is stored in public tags and does appear to compensate for phase encode polarity. These coordinates are with respect to the scanner bore, not image space. A Canon classic DICOM DWI image may report:
In contrast, Canon software [V6.1](https://github.com/neurolabusc/dcm_qa_canon_61) uses pulbic tags for both classic and enhanced DICOMs. A Canon V6.1 DICOM DWI image may report:

```
(0018,9087) FD 1500 # 8, 1 DiffusionBValue
Expand Down
2 changes: 1 addition & 1 deletion Philips/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ The BIDS tag [PartialFourier](https://bids-specification.readthedocs.io/en/stabl

Philips DICOMs do not allow one to determine the temporal order of volumes for diffusion (DWI, DTI) and arterial spin labelling (ASL) sequences. This can hinder tools that attempt to model motion motion or T1 effects. For ASL data, dcm2niix will attempt to store volumes in the order phase < control/label < repeat. [For ASL examples and a table describing the ordering hierarchy, see this dataset](https://github.com/neurolabusc/dcm_qa_philips_asl). For diffusion images, dcm2niix may order Philips volumes differently depending on if the data is stored as classic or enhanced DICOM. For enhanced DICOM, dcm2niix follows the hierarchy specified by DimensionIndexValues (0020,9157). On the other hand, for classic DICOMs, volumes with identical b-value index (2005,1412) will be stored sequentially, with ties sorted based on gradient direction number (2005,1413). [For diffusion examples, see series 22 and 23 from this dataset](https://github.com/neurolabusc/dcm_qa_philips_enh). These two different sorting methods may not necessarily sort data identically.

[Slice timing correction](https://www.mccauslandcenter.sc.edu/crnl/tools/stc) can account for some variability in fMRI datasets. Unfortunately, Philips DICOM data [does not encode slice timing information](https://neurostars.org/t/heudiconv-no-extraction-of-slice-timing-data-based-on-philips-dicoms/2201/4). Therefore, dcm2niix is unable to populate the "SliceTiming" BIDS field. However, one can typically infer slice timing by recording the [mode and number of packages](https://en.wikibooks.org/w/index.php?title=SPM/Slice_Timing&stable=0#Philips_scanners) reported for the sequence on the scanner console or the [sequence PDF](http://adni.loni.usc.edu/wp-content/uploads/2017/09/ADNI-3-Basic-Philips-R5.pdf). For precise timing, it is also worth knowing if equidistant "temporal slice spacing" is set and whether "prospect. motion corr." is on or off (if on, a short delay occurs between volumes).
[Slice timing correction](https://www.mccauslandcenter.sc.edu/crnl/tools/stc) can account for some variability in fMRI datasets. Unfortunately, Philips DICOM data [does not explicitly encode slice timing information](https://neurostars.org/t/heudiconv-no-extraction-of-slice-timing-data-based-on-philips-dicoms/2201/4). Therefore, dcm2niix is unable to populate the "SliceTiming" BIDS field. Note, the [philips_order.py script](https://neurostars.org/t/how-dcm2niix-handles-different-imaging-types/22697/7) may be able to determine slice timing using an undocumented and unverified technique that works in some instances but certainly fails with others. Additionally, one can typically infer slice timing by recording the [mode and number of packages](https://en.wikibooks.org/w/index.php?title=SPM/Slice_Timing&stable=0#Philips_scanners) reported for the sequence on the scanner console or the [sequence PDF](http://adni.loni.usc.edu/wp-content/uploads/2017/09/ADNI-3-Basic-Philips-R5.pdf). For precise timing, it is also worth knowing if equidistant "temporal slice spacing" is set and whether "prospect. motion corr." is on or off (if on, a short delay occurs between volumes).

Likewise, the BIDS tag "PhaseEncodingDirection" allows tools like [eddy](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy) and [TOPUP](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup) to undistort images. While the Philips DICOM header distinguishes the phase encoding axis (e.g. anterior-posterior vs left-right) it does not encode the polarity (A->P vs P->A).

Expand Down
Loading

0 comments on commit bb3a6c3

Please sign in to comment.