Merge pull request #551 from rordenlab/development

New stable release ( v1.0.20211006)

BIDS/extract_units.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python
+"""extract_units.py - extract BIDS/README.md's units as json
+
+Usage:
+  extract_units.py [-e EXISTING -o OUT] [MD]
+  extract_units.py (-h|--help|--version)
+
+Arguments:
+  MD:      A Markdown input file including tables with Field and Unit as the
+           first two columns.
+           [default: README.md]
+
+Options:
+  -h --help                     Show this message and exit.
+  --version                     Show version and exit.
+  -e EXISTING --ex=EXISTING     Extract units for all the fields, and only the
+                                fields in EXISTING, a BIDS file, and write the
+                                output to
+                                EXISTING.replace('.json', '_units.json')
+                                instead of stdout.
+  -o OUT --out=OUT              If given, save the output to this filename.
+                                (Overrides the implicit destination of -e.)
+"""
+from __future__ import print_function
+try:
+    import json_tricks as json
+except ImportError:
+    try:
+        import simplejson as json
+    except ImportError:
+        # Not really compatible with json_tricks because it does not support
+        # primitives=True
+        import json
+import sys
+
+# Please use semantic versioning (API.feature.bugfix), http://semver.org/
+__version__ = '0.0.0'
+
+
+def extract_units(mdfn):
+    units = {}
+    intable = False
+    with open(mdfn) as md:
+        for line in md:
+            if line.startswith('|'):
+                parts = [s.strip() for s in line.split('|')[1:-1]]
+                if parts[:2] == ['Field', 'Unit']:
+                    intable = True
+                elif intable and parts[1] and not parts[1].startswith('-'):
+                    units[parts[0]] = parts[1]
+            else:
+                intable = False
+    return units
+
+
+def main(mdfn, existing=None, outfn=None):
+    units = extract_units(mdfn)
+    if existing:
+        with open(existing) as f:  # Can't count on having json_tricks.
+            used = json.load(f)
+        units = {k: v for k, v in units.items() if k in used}
+        if not outfn:
+            outfn = existing.replace('.json', '_units.json')
+    outtext = json.dumps(units, indent=2, sort_keys=True,
+                         separators=(', ', ': '))
+    if outfn:
+        with open(outfn, 'w') as outf:
+            outf.write(outtext + "\n")
+    else:
+        print(outtext)
+    return units
+
+
+if __name__ == '__main__':
+    from docopt import docopt
+
+    args = docopt(__doc__, version=__version__)
+
+    # https://github.com/docopt/docopt/issues/214 has been open for
+    # almost 7 years, so it looks like docopt isn't getting default
+    # positional args.
+    output = main(args['MD'] or 'README.md',
+                  args.get('--ex'), args.get('--out'))
+    sys.exit(0)

COMPILE.md

@@ -159,4 +159,3 @@ Once the installation is completed, you can revert these changes:
 git config --global --unset-all url.https://github.com/.insteadof
 git config --global --unset-all url.https://.insteadof
 ```
-

CONTRIBUTE.md

@@ -0,0 +1,29 @@
+#### Introduction
+
+dcm2niix is a community effort
+
+Like the [Brain Imaging Data Structure](https://bids.neuroimaging.io/get_involved.html), which it supports, dcm2niix is developed by the community for the community and everybody can become a part of the community.
+
+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). 
+
+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.
+
+ - Jon Clayden: (@jonclayden): [R Deployment](https://github.com/jonclayden/divest)
+ - Ningfei Li : (@ningfei) CMake, AppVeyor, Travis
+ - Yaroslav O. Halchenko: (@yarikoptic) Debian distributions
+ - Taylor Hanayik (@hanayik): FSL integration
+ - Michael Harms (@mharms): Advanced modalities
+ - Roger D Newman-Norlund (@rogiedodgie): User support
+ - Rob Reid (@captainnova): Clinical modalities
+ - Chris Rorden (@neurolabusc): General development, user support
+
+#### Style Guide
+
+dcm2niix is written in C. Different programmers prefer different styles of indentation. Feel free to contribute code without being concerned about matching the style of the rest of the code. Once in a while, the code base will be automatically reformatted to make it appear more consistent for all users. This is done automatically with clang-format:
+
+```
+clang-format -i -style="{BasedOnStyle: LLVM, IndentWidth: 4, IndentCaseLabels: false, TabWidth: 4, UseTab: Always, ColumnLimit: 0}" *.cpp *.h
+```

Canon/README.md

@@ -17,7 +17,7 @@ Since the acquisition by Canon, these public tags are no longer populated for im
  (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, 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:
 
 ```
 (0018,9087) FD 1500                                     #   8, 1 DiffusionBValue
@@ -36,4 +36,4 @@ The [BIDS format](https://bids.neuroimaging.io) can record several sequence prop
 
  - [Toshiba Aquilion](https://www.aliza-dicom-viewer.com/download/datasets).
  - [Toshiba 3T Galan Diffusion Dataset](https://github.com/neurolabusc/dcm_qa_toshiba).
- - [Canon 3T Galan Diffusion Dataset](https://github.com/neurolabusc/dcm_qa_canon).
+ - [Canon 3T Galan Diffusion Dataset](https://github.com/neurolabusc/dcm_qa_canon).

ERRORS.md

@@ -26,4 +26,3 @@ Below is a list of possible return values from running dcm2niix.
 | 7           | Unable to write to output folder (check file permissions)   |
 | 8           | Converted some but not all of the input DICOMs              |
 | 9           | Unable to rename files (result of `dcm2niix -r y ~/in`)     |
-

FILENAMING.md

@@ -24,7 +24,7 @@ You request the output file name with the `-f` argument. For example, consider y
  - %r=instance number (from 0020,0013)*
  - %s=series number (from 0020,0011)
  - %t=time of study (from 0008,0020 and 0008,0030)
- - %u=acquisition number (from 0020,0012)
+ - %u=acquisition number (from 0020,0012). This option is recommended for [DICOM renaming](RENAMING.md). It is [not recommended](https://github.com/rordenlab/dcm2niix/issues/526) for DICOM to NIfTI conversion (as [BIDS compatible](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html) 4D datasets collapses multiple acquisitions to a single file). 
  - %v=vendor long name (from 0008,0070: GE, Philips, Siemens, Toshiba, UIH, NA)
  - %x=study ID (from 0020,0010)
  - %y=youth in series: GE RawDataRunNumber ([0019,10A2](https://github.com/rordenlab/dcm2niix/issues/359)) else TemporalPosition ([0020,0100](https://github.com/rordenlab/dcm2niix/issues/357))*
@@ -38,7 +38,7 @@ 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 asumes all 2D slices that form a 3D stack are equidistant. Therefore, dcm2niix reslices the input data to generate an equidistant volume.
+ - _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
  - _imaginary imaginary component of complex image
@@ -87,4 +87,4 @@ dcm2niix will attempt to write your image using the naming scheme you specify wi
 
 [Control characters](https://en.wikipedia.org/wiki/ASCII#Control_characters) like backspace and tab are also forbidden.
 
-Be warned that dcm2niix will copy all allowed characters verbatim, which can cause problems for some other tools. Consider this [sample dataset](https://github.com/neurolabusc/dcm_qa_nih/tree/master/In/20180918GE/mr_0004) where the DICOM Protocol Name (0018,1030) is 'Axial_EPI-FMRI_(Interleaved_I_to_S)'. The parentheses ("round brackets") may cause other tools issues. Consider converting this series with the command 'dcm2niix -f %s_%p ~/DICOM' to create the file '4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii'.If you now run the command 'fslhd 4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii' you will get the error '-bash: syntax error near unexpected token `(''. Therefore, it is often a good idea to use double quotes to specify the names of files. In this example 'fslhd "4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii"' will work correctly.
+Be warned that dcm2niix will copy all allowed characters verbatim, which can cause problems for some other tools. Consider this [sample dataset](https://github.com/neurolabusc/dcm_qa_nih/tree/master/In/20180918GE/mr_0004) where the DICOM Protocol Name (0018,1030) is 'Axial_EPI-FMRI_(Interleaved_I_to_S)'. The parentheses ("round brackets") may cause other tools issues. Consider converting this series with the command 'dcm2niix -f %s_%p ~/DICOM' to create the file '4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii'.If you now run the command 'fslhd 4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii' you will get the error '-bash: syntax error near unexpected token `(''. Therefore, it is often a good idea to use double quotes to specify the names of files. In this example 'fslhd "4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii"' will work correctly.

GE/README.md

@@ -2,6 +2,22 @@
 
 dcm2niix attempts to convert GE DICOM format images to NIfTI. The current generation DICOM files generated by GE equipment is quite impoverished relative to other vendors. Therefore, the amount of information dcm2niix is able to extract is relatively limited. Hopefully, in the future GE will provide more details that are critical for brain scientists.
 
+## Arterial Spin Labeling
+
+As noted by David Shin (GE), the GE product ASL sequence sequence produces two 3D volumes. The Perfusion Weighted (PW) first pass acquires ASL tag/control spirals in interleaved fashion over many volumes (TRs), and does the subtraction and averaging in k-space. Therefore, the result is a single 3D volume. The second pass acquires a Proton Density (PD) reference volume. The PW and PD images can be combined offline to generate quantified Cerebral Blood Flow(CBF) map. [Stanford](https://cni.stanford.edu/wiki/Data_Processing) includes useful notes on this sequence. Note that Number of Excitations (NEX) is needed for CBF quantification. The sequence specific details are listed in the table. 
+
+| DICOM Tag | Pass 1 (PW)                        | Pass 2 (PD)                        |
+|-----------|------------------------------------|------------------------------------|
+| 0043,10A3 | PSEUDOCONTINUOUS                   | CONTINUOUS                         |
+| 0043,10A4 | 3D pulsed continuous ASL technique | 3D continuous ASL technique        |
+| 0043,10A5 | Label Duration (ms)                | Label Duration (ms)                |
+| 0018,0082 | Post Label Delay (ms)              | NA                                 |
+| 0027,1060 | Number of Points per Arm           | Number of Points per Arm           |
+| 0027,1061 | Number of Arms                     | Number of Arms                     |
+| 0027,1062 | Number of Excitations              | Number of Excitations              |
+
+The GE product ASL sequence is optimized for clinical diagnosis with emphasis on 3D acquisition and multi-shot interleaving for high spatial resolution. For 4D type acquisition (time resolved single-shot acquisition), GE researchers can leverage the [multi-band ASL/BOLD sequence](https://journals.plos.org/plosone/article/authors?id=10.1371/journal.pone.0190427).
+
 ## Diffusion Tensor Notes
 
 The [NA-MIC Wiki](https://www.na-mic.org/wiki/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI#Private_vendor:_GE) provides a nice description of the GE diffusion tags. In brief, the B-value is stored as the first element in the array of 0043,1039. The DICOM elements 0019,10bb, 0019,10bc and 0019,10bd provide the gradient direction relative to the frequency, phase and slice. As noted by Jaemin Shin (GE), the GE convention for reported diffusion gradient direction has always been in “MR physics” logical coordinate, i.e Freq (X), Phase (Y), Slice (Z). Note that this is neither “with reference to the scanner bore” (like Siemens or Philips) nor “with reference to the imaging plane” (as expected by FSL tools). This is the main source of confusion. This explains why the dcm2niix function geCorrectBvecs() checks whether the DICOM tag In-plane Phase Encoding Direction (0018,1312) is 'ROW' or 'COL'. In addition, it will generate the warning 'reorienting for ROW phase-encoding untested' if you acquire DTI data with the phase encoding in the ROW direction. If you do test this feature, please report your findings as a Github issue. Assuming you have COL phase encoding, dcm2niix should provide [FSL format](http://justinblaber.org/brief-introduction-to-dwmri/) [bvec files](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/FAQ#What_conventions_do_the_bvecs_use.3F).
@@ -94,4 +110,5 @@ Anatomical localizers (e.g. scout images) are quick-and-dirty scans used to posi
  - [Slice Timing and Phase Encoding examples](https://github.com/jannikadon/cc-dcm2bids-wrapper/tree/main/dicom-qa-examples)
  - [Slice timing validation](https://github.com/neurolabusc/dcm_qa_stc) for different varieties of GE EPI sequences.
  - [Examples of phase encoding polarity, slice timing and diffusion gradients](https://github.com/neurolabusc/dcm_qa_ge).
- - The dcm2niix [wiki](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage) includes examples of diffusion data, slice timing, and other variations.
+ - The dcm2niix [wiki](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage) includes examples of diffusion data, slice timing, and other variations.
+

Mediso/README.md

@@ -0,0 +1,9 @@
+## About
+
+dcm2niix attempts to convert all DICOM images to NIfTI. However, different manufacturers handle the format differently. [Mediso](https://mediso.com/usa/en/) is a manufacturer that supports preclinical tools for PET, MRI, SPECT and CT.
+
+In general, this manufacturer uses public tags and generates simple DICOM headers. While these files do not contain the rich meta data available from other manufacturers, they are simple to parse.
+
+## Sample Datasets
+
+ - The [ftp://medical.nema.org/MEDICAL](ftp://medical.nema.org/MEDICAL)  server provides reference images in Dicom/Datasets/WG30/Mediso

PARREC/README.md

@@ -1,9 +1,9 @@
 ## About
 
-dcm2niix attempts to convert Philips PAR/REC format images to NIfTI. While this format remains popular with users, it is slowly being superceded by Philips enhanced DICOM format, an XML/REC format as well as the direct NIfTI export. Note that dcm2niix does not support the XML/REC format.
+dcm2niix attempts to convert Philips PAR/REC format images to NIfTI. While this format remains popular with users, it is slowly being superseded by Philips enhanced DICOM format, an XML/REC format as well as the direct NIfTI export. Note that dcm2niix does not support the XML/REC format.
 
 
-According to [Matthew Clemence](https://www.nitrc.org/forum/forum.php?thread_id=9319&forum_id=4703) DICOM (classic and enhanced) and XML/REC are supported in the base product, NIFTI forms part of a Neuroscience commercial option from release 5 onwards. PAR/REC requires a research agreement to obtain. For the two formats XML/REC and PAR/REC, the "REC" part is identical but instead of a plain text file of the "par" format, the same information is now available as an XML file. This descision has been taken to allow the information to be more easily extended as the PAR file was getting increasingly limited.
+According to [Matthew Clemence](https://www.nitrc.org/forum/forum.php?thread_id=9319&forum_id=4703) DICOM (classic and enhanced) and XML/REC are supported in the base product, NIFTI forms part of a Neuroscience commercial option from release 5 onwards. PAR/REC requires a research agreement to obtain. For the two formats XML/REC and PAR/REC, the "REC" part is identical but instead of a plain text file of the "par" format, the same information is now available as an XML file. This decision has been taken to allow the information to be more easily extended as the PAR file was getting increasingly limited.
 
 ## Detecting, Reporting and Fixing the V4 Image offcentre Bug
 
@@ -43,5 +43,3 @@ Note that for Philips (unlike DICOM) the For PAR/REC the acquisition (%u) and se
 ## dcm2niix Limitations
 
 Be aware that dcm2niix assumes that the data is stored in complete 3D volumes. It will not convert datasets where the scan is interrupted mid-volume (e.g. where the number of 2D slices is not divisible by the number of slices in a volume). This can occur if the user aborts a sequence part way through acquisition. If dcm2niix detects this situation it will suggest you use [dicm2nii](https://www.mathworks.com/matlabcentral/fileexchange/42997-dicom-to-nifti-converter--nifti-tool-and-viewer) which can handle these files.
-
-