Merge pull request #329 from bcipolli/reload

MRG: Migrate load, save, class_map, ext_map to class properties and methods

This is to address #317 and #323 (and aims to supercede PR #319), both issues around image-specific code being distributed across files, rather than localized in the class definition.

Changes here include:
* Removing image-specific code from `nib.load` and `nib.save` functions, moving the logic into `ImageKlass.is_image` and `HeaderKlass.is_header` class functions.
* Deprecating `class_map` and `ext_map` objects, and moving necessary info to properties defined on the image classes themselves.

Author: matthew-brett

nibabel/__init__.py

@@ -61,7 +61,7 @@
 from .orientations import (io_orientation, orientation_affine,
                            flip_axis, OrientationError,
                            apply_orientation, aff2axcodes)
-from .imageclasses import class_map, ext_map
+from .imageclasses import class_map, ext_map, all_image_classes
 from . import trackvis
 from . import mriutils
 

nibabel/analyze.py

@@ -892,13 +892,28 @@ def _chk_pixdims(hdr, fix=False):
             rep.fix_msg = ' and '.join(fmsgs)
         return hdr, rep
 
+    @classmethod
+    def may_contain_header(klass, binaryblock):
+        if len(binaryblock) < klass.sizeof_hdr:
+            return False
+
+        hdr_struct = np.ndarray(shape=(), dtype=header_dtype,
+                                buffer=binaryblock[:klass.sizeof_hdr])
+        bs_hdr_struct = hdr_struct.byteswap()
+        return 348 in (hdr_struct['sizeof_hdr'], bs_hdr_struct['sizeof_hdr'])
+
 
 class AnalyzeImage(SpatialImage):
     """ Class for basic Analyze format image
     """
     header_class = AnalyzeHeader
+    _meta_sniff_len = header_class.sizeof_hdr
     files_types = (('image', '.img'), ('header', '.hdr'))
-    _compressed_exts = ('.gz', '.bz2')
+    valid_exts = ('.img', '.hdr')
+    _compressed_suffixes = ('.gz', '.bz2')
+
+    makeable = True
+    rw = True
 
     ImageArrayProxy = ArrayProxy
 

nibabel/ecat.py

@@ -732,6 +732,7 @@ class EcatImage(SpatialImage):
     """
     _header = EcatHeader
     header_class = _header
+    valid_exts = ('.v',)
     _subheader = EcatSubHeader
     files_types = (('image', '.v'), ('header', '.v'))
 

nibabel/freesurfer/mghformat.py

@@ -454,13 +454,18 @@ def writeftr_to(self, fileobj):
         fileobj.write(ftr_nd.tostring())
 
 
+# Register .mgz extension as compressed
 @ImageOpener.register_ext_from_image('.mgz', ImageOpener.gz_def)
 class MGHImage(SpatialImage):
     """ Class for MGH format image
     """
     header_class = MGHHeader
+    valid_exts = ('.mgh',)
     files_types = (('image', '.mgh'),)
-    _compressed_exts = (('.gz',))
+    _compressed_suffixes = ()
+
+    makeable = True
+    rw = True
 
     ImageArrayProxy = ArrayProxy
 

nibabel/freesurfer/tests/test_mghformat.py

@@ -145,7 +145,7 @@ def test_filename_exts():
     # and the default affine matrix (Note the "None")
     img = MGHImage(v, None)
     # Check if these extensions allow round trip
-    for ext in ('.mgh', '.mgz', '.mgh.gz'):
+    for ext in ('.mgh', '.mgz'):
         with InTemporaryDirectory():
             fname = 'tmpname' + ext
             save(img, fname)

nibabel/imageclasses.py

@@ -7,69 +7,92 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 ''' Define supported image classes and names '''
+import warnings
+
 from .analyze import AnalyzeImage
 from .spm99analyze import Spm99AnalyzeImage
 from .spm2analyze import Spm2AnalyzeImage
 from .nifti1 import Nifti1Pair, Nifti1Image
+from .nifti2 import Nifti2Pair, Nifti2Image
 from .minc1 import Minc1Image
+from .minc2 import Minc2Image
 from .freesurfer import MGHImage
 from .parrec import PARRECImage
 from .volumeutils import Recoder
 from .optpkg import optional_package
 _, have_scipy, _ = optional_package('scipy')
 
 
-# mapping of names to classes and class functionality
+# Ordered by the load/save priority.
+all_image_classes = [Nifti1Pair, Nifti1Image, Nifti2Pair, Nifti2Image,
+                     Spm2AnalyzeImage, Spm99AnalyzeImage, AnalyzeImage,
+                     Minc1Image, Minc2Image, MGHImage,
+                     PARRECImage]
+
+
+# DEPRECATED: mapping of names to classes and class functionality
+class ClassMapDict(dict):
+    def __getitem__(self, *args, **kwargs):
+        warnings.warn("class_map is deprecated.", DeprecationWarning,
+                      stacklevel=2)
+        return super(ClassMapDict, self).__getitem__(*args, **kwargs)
+
+class_map = ClassMapDict(
+    analyze={'class': AnalyzeImage,  # Image class
+             'ext': '.img',  # characteristic image extension
+             'has_affine': False,  # class can store an affine
+             'makeable': True,  # empty image can be easily made in memory
+             'rw': True},  # image can be written
+    spm99analyze={'class': Spm99AnalyzeImage,
+                  'ext': '.img',
+                  'has_affine': True,
+                  'makeable': True,
+                  'rw': have_scipy},
+    spm2analyze={'class': Spm2AnalyzeImage,
+                 'ext': '.img',
+                 'has_affine': True,
+                 'makeable': True,
+                 'rw': have_scipy},
+    nifti_pair={'class': Nifti1Pair,
+                'ext': '.img',
+                'has_affine': True,
+                'makeable': True,
+                'rw': True},
+    nifti_single={'class': Nifti1Image,
+                  'ext': '.nii',
+                  'has_affine': True,
+                  'makeable': True,
+                  'rw': True},
+    minc={'class': Minc1Image,
+          'ext': '.mnc',
+          'has_affine': True,
+          'makeable': True,
+          'rw': False},
+    mgh={'class': MGHImage,
+         'ext': '.mgh',
+         'has_affine': True,
+         'makeable': True,
+         'rw': True},
+    mgz={'class': MGHImage,
+         'ext': '.mgz',
+         'has_affine': True,
+         'makeable': True,
+         'rw': True},
+    par={'class': PARRECImage,
+         'ext': '.par',
+         'has_affine': True,
+         'makeable': False,
+         'rw': False})
+
 
-class_map = {
-    'analyze': {'class': AnalyzeImage,  # Image class
-                'ext': '.img',  # characteristic image extension
-                'has_affine': False,  # class can store an affine
-                'makeable': True,  # empty image can be easily made in memory
-                'rw': True},  # image can be written
-    'spm99analyze': {'class': Spm99AnalyzeImage,
-                     'ext': '.img',
-                     'has_affine': True,
-                     'makeable': True,
-                     'rw': have_scipy},
-    'spm2analyze': {'class': Spm2AnalyzeImage,
-                    'ext': '.img',
-                    'has_affine': True,
-                    'makeable': True,
-                    'rw': have_scipy},
-    'nifti_pair': {'class': Nifti1Pair,
-                   'ext': '.img',
-                   'has_affine': True,
-                   'makeable': True,
-                   'rw': True},
-    'nifti_single': {'class': Nifti1Image,
-                     'ext': '.nii',
-                     'has_affine': True,
-                     'makeable': True,
-                     'rw': True},
-    'minc': {'class': Minc1Image,
-             'ext': '.mnc',
-             'has_affine': True,
-             'makeable': True,
-             'rw': False},
-    'mgh': {'class': MGHImage,
-            'ext': '.mgh',
-            'has_affine': True,
-            'makeable': True,
-            'rw': True},
-    'mgz': {'class': MGHImage,
-            'ext': '.mgz',
-            'has_affine': True,
-            'makeable': True,
-            'rw': True},
-    'par': {'class': PARRECImage,
-            'ext': '.par',
-            'has_affine': True,
-            'makeable': False,
-            'rw': False}}
+class ExtMapRecoder(Recoder):
+    def __getitem__(self, *args, **kwargs):
+        warnings.warn("ext_map is deprecated.", DeprecationWarning,
+                      stacklevel=2)
+        return super(ExtMapRecoder, self).__getitem__(*args, **kwargs)
 
 # mapping of extensions to default image class names
-ext_map = Recoder((
+ext_map = ExtMapRecoder((
     ('nifti_single', '.nii'),
     ('nifti_pair', '.img', '.hdr'),
     ('minc', '.mnc'),

nibabel/loadsave.py

@@ -10,18 +10,12 @@
 """ Utilities to load and save image objects """
 
 import numpy as np
+import warnings
 
-from .filename_parser import types_filenames, splitext_addext
+from .filename_parser import splitext_addext
 from .openers import ImageOpener
-from .analyze import AnalyzeImage
-from .spm2analyze import Spm2AnalyzeImage
-from .nifti1 import Nifti1Image, Nifti1Pair, header_dtype as ni1_hdr_dtype
-from .nifti2 import Nifti2Image, Nifti2Pair
-from .minc1 import Minc1Image
-from .minc2 import Minc2Image
-from .freesurfer import MGHImage
 from .spatialimages import ImageFileError
-from .imageclasses import class_map, ext_map
+from .imageclasses import all_image_classes
 from .arrayproxy import is_proxy
 
 
@@ -40,9 +34,17 @@ def load(filename, **kwargs):
     img : ``SpatialImage``
        Image of guessed type
     '''
-    return guessed_image_type(filename).from_filename(filename, **kwargs)
+    sniff = None
+    for image_klass in all_image_classes:
+        is_valid, sniff = image_klass.path_maybe_image(filename, sniff)
+        if is_valid:
+            return image_klass.from_filename(filename, **kwargs)
 
+    raise ImageFileError('Cannot work out file type of "%s"' %
+                         filename)
 
+
+@np.deprecate
 def guessed_image_type(filename):
     """ Guess image type from file `filename`
 
@@ -56,39 +58,16 @@ def guessed_image_type(filename):
     image_class : class
         Class corresponding to guessed image type
     """
-    froot, ext, trailing = splitext_addext(filename, ('.gz', '.bz2'))
-    lext = ext.lower()
-    try:
-        img_type = ext_map[lext]
-    except KeyError:
-        raise ImageFileError('Cannot work out file type of "%s"' %
-                             filename)
-    if lext in ('.mgh', '.mgz', '.par'):
-        klass = class_map[img_type]['class']
-    elif lext == '.mnc':
-        # Look for HDF5 signature for MINC2
-        # https://www.hdfgroup.org/HDF5/doc/H5.format.html
-        with ImageOpener(filename) as fobj:
-            signature = fobj.read(4)
-            klass = Minc2Image if signature == b'\211HDF' else Minc1Image
-    elif lext == '.nii':
-        with ImageOpener(filename) as fobj:
-            binaryblock = fobj.read(348)
-        ft = which_analyze_type(binaryblock)
-        klass = Nifti2Image if ft == 'nifti2' else Nifti1Image
-    else:  # might be nifti 1 or 2 pair or analyze of some sort
-        files_types = (('image', '.img'), ('header', '.hdr'))
-        filenames = types_filenames(filename, files_types)
-        with ImageOpener(filenames['header']) as fobj:
-            binaryblock = fobj.read(348)
-        ft = which_analyze_type(binaryblock)
-        if ft == 'nifti2':
-            klass = Nifti2Pair
-        elif ft == 'nifti1':
-            klass = Nifti1Pair
-        else:
-            klass = Spm2AnalyzeImage
-    return klass
+    warnings.warn('guessed_image_type is deprecated', DeprecationWarning,
+                  stacklevel=2)
+    sniff = None
+    for image_klass in all_image_classes:
+        is_valid, sniff = image_klass.path_maybe_image(filename, sniff)
+        if is_valid:
+            return image_klass
+
+    raise ImageFileError('Cannot work out file type of "%s"' %
+                         filename)
 
 
 def save(img, filename):
@@ -105,25 +84,38 @@ def save(img, filename):
     -------
     None
     '''
+
+    # Save the type as expected
     try:
         img.to_filename(filename)
     except ImageFileError:
         pass
     else:
         return
+
+    # Be nice to users by making common implicit conversions
     froot, ext, trailing = splitext_addext(filename, ('.gz', '.bz2'))
+    lext = ext.lower()
+
     # Special-case Nifti singles and Pairs
-    if type(img) == Nifti1Image and ext in ('.img', '.hdr'):
+    # Inline imports, as this module really shouldn't reference any image type
+    from .nifti1 import Nifti1Image, Nifti1Pair
+    from .nifti2 import Nifti2Image, Nifti2Pair
+    if type(img) == Nifti1Image and lext in ('.img', '.hdr'):
         klass = Nifti1Pair
-    elif type(img) == Nifti2Image and ext in ('.img', '.hdr'):
+    elif type(img) == Nifti2Image and lext in ('.img', '.hdr'):
         klass = Nifti2Pair
-    elif type(img) == Nifti1Pair and ext == '.nii':
+    elif type(img) == Nifti1Pair and lext == '.nii':
         klass = Nifti1Image
-    elif type(img) == Nifti2Pair and ext == '.nii':
+    elif type(img) == Nifti2Pair and lext == '.nii':
         klass = Nifti2Image
-    else:
-        img_type = ext_map[ext]
-        klass = class_map[img_type]['class']
+    else:  # arbitrary conversion
+        valid_klasses = [klass for klass in all_image_classes
+                         if ext in klass.valid_exts]
+        if not valid_klasses:  # if list is empty
+            raise ImageFileError('Cannot work out file type of "%s"' %
+                                 filename)
+        klass = valid_klasses[0]
     converted = klass.from_image(img)
     converted.to_filename(filename)
 
@@ -214,6 +206,7 @@ def read_img_data(img, prefer='scaled'):
         return hdr.raw_data_from_fileobj(fileobj)
 
 
+@np.deprecate
 def which_analyze_type(binaryblock):
     """ Is `binaryblock` from NIfTI1, NIfTI2 or Analyze header?
 
@@ -241,13 +234,16 @@ def which_analyze_type(binaryblock):
     * if ``sizeof_hdr`` is 348 or byteswapped 348 assume Analyze
     * Return None
     """
-    hdr = np.ndarray(shape=(), dtype=ni1_hdr_dtype, buffer=binaryblock)
-    bs_hdr = hdr.byteswap()
-    sizeof_hdr = hdr['sizeof_hdr']
-    bs_sizeof_hdr = bs_hdr['sizeof_hdr']
+    warnings.warn('which_analyze_type is deprecated', DeprecationWarning,
+                  stacklevel=2)
+    from .nifti1 import header_dtype
+    hdr_struct = np.ndarray(shape=(), dtype=header_dtype, buffer=binaryblock)
+    bs_hdr_struct = hdr_struct.byteswap()
+    sizeof_hdr = hdr_struct['sizeof_hdr']
+    bs_sizeof_hdr = bs_hdr_struct['sizeof_hdr']
     if 540 in (sizeof_hdr, bs_sizeof_hdr):
         return 'nifti2'
-    if hdr['magic'] in (b'ni1', b'n+1'):
+    if hdr_struct['magic'] in (b'ni1', b'n+1'):
         return 'nifti1'
     if 348 in (sizeof_hdr, bs_sizeof_hdr):
         return 'analyze'