Merge commit 'v1.0.20200427-207-g66a4fd0' into debian

* commit 'v1.0.20200427-207-g66a4fd0': (76 commits)
  Philips ASL in temporal order (rordenlab#533)
  Optional compilation to disable kludge for issue 532, e.g. "make CFLAGS=-DmyDisableGEPEPolarFlip" (rordenlab#532)
  0020,9157 if dcuncat, use 0020,0013 if 0019,10A2; 0020,0100; 2005,1063; 2005,1413 do not vary (rordenlab#529)
  Add BIDS ArterialSpinLabelingType field
  Diagnostics for issue 529 (rordenlab#529)
  Flip row order for kGE_EPI_PEPOLAR_REV
  Detect and correct GE epi_pepolar sequence (rordenlab#532)
  More CT meta data, detect manufacturer MEDISO
  Philips ASL volume order (rordenlab#529)
  ensureSequentialSlicePositions verbosity
  Handle Philips images where 2005,1063 is set to zero for all volumes, see Magdeburg_2014 from dcm_qa_philips Philips MR 51.0
  @baxpr kludge (rordenlab#529)
  Remove redundancy
  Kludge for Philips random instance numbers (rordenlab#529)
  BUG: Fix preprocessor conflict.
  Support ancient Linux, tested on holy-build-box (rordenlab#531)
  undefine DT_NONE (https://neurostars.org/t/adjusting-for-negative-mosaicrefacqtimes-issue-271-warning-but-with-normal-slice-times/19866/3)
  UIH new TotalReadoutTIme formula (rordenlab#531)
  UIH uodates
  Allow acquisition number (0020,0012) in filename (rordenlab#526)
  ...

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)

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
+```

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))*

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).

Philips/README.md

@@ -71,6 +71,14 @@ Formulas:
  FP = DV / (RS * SS)
 ```
 
+## Volume Ordering
+
+The DICOM standard does not require that the [Instance Number (0020,0013)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0020,0013)) be sequential or even unique. As a convention, most manufacturers provide instance numbers that are sequential with the temporal or spatial order. However, Philips often generates these values in a random order. This can lead to images appearing in a jumbled order when displayed with many DICOM viewers (e.g. [Horos](https://horosproject.org)). dcm2niix will attempt to automatically resolve this. Hopefully, fMRI volumes will be ordered temporally, diffusion data will be ordered by gradient number (with derived TRACE/ADC maps being made the final volume), and ASL scans will follow the order hierarchical order of [repeat, phase, label/control](https://github.com/neurolabusc/dcm_qa_philips_asl)). dcm2niix makes assumptions about the volume based on assumptions observed in previous Philips data. These heuristics may not be robust for future Philips data or for DICOM images that have been manipulated (e.g. anonymized, dcuncat, touched by an AGFA/dcmche PACS). Therefore, users need to use caution when dealing with Philips data converted by dcm2niix.
+
+## Arterial Spin Labelling
+
+Details and sample datasets for Philips Arterial Spin Labeling (ASL) are provided with the [dcm_qa_philips_asl](https://github.com/neurolabusc/dcm_qa_philips_asl) (classic DICOM) and [dcm_qa_philips_asl_enh](https://github.com/neurolabusc/dcm_qa_philips_asl) (enhanced DICOM) repositories.
+
 ## Derived parametric maps stored with raw diffusion data
 
 Some Philips diffusion DICOM images include derived image(s) along with the images. Other manufacturers save these derived images as a separate series number, and the DICOM standard seems ambiguous on whether it is allowable to mix raw and derived data in the same series (see PS 3.3-2008, C.7.6.1.1.2-3). In practice, many Philips diffusion images append [derived parametric maps](http://www.revisemri.com/blog/2008/diffusion-tensor-imaging/) with the original data. With Philips, appending the derived isotropic image is optional - it is only created for the 'clinical' DTI schemes for radiography analysis and is triggered if the first three vectors in the gradient table are the unit X,Y and Z vectors. For conventional DWI, the result is the conventional mean of the ADC X,Y,Z for DTI it the conventional mean of the 3 principle Eigen vectors. As scientists, we want to discard these derived images, as they will disrupt data processing and we can generate better parametric maps after we have applied undistortion methods such as [Eddy and Topup](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide). The current version of dcm2niix uses the Diffusion Directionality (0018,9075) tag to detect B=0 unweighted ("NONE"), B-weighted ("DIRECTIONAL"), and derived ("ISOTROPIC") images. Note that the Dimension Index Values (0020,9157) tag provides an alternative approach to discriminate these images. Here are sample tags from a Philips enhanced image that includes and derived map (3rd dimension is "1" while the other images set this to "2").
@@ -167,4 +175,5 @@ Prior versions of dcm2niix used different methods to sort images. However, these
  - [Archival samples](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Archival_MRI)
  - [Diffusion Examples](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Diffusion_Tensor_Imaging)
  - [Additional Diffusion Examples](https://github.com/neurolabusc/dcm_qa_philips)
+ - Classic and enhanced [ASL Examples](https://github.com/neurolabusc/dcm_qa_philips_asl)
  - [Enhanced DICOMs](https://github.com/neurolabusc/dcm_qa_enh)