Merge remote-tracking branch 'upstream/maint/2.4.x'

Author: effigies

Changelog

@@ -25,6 +25,43 @@ Eric Larson (EL), Demian Wassermann, and Stephan Gerhard.
 
 References like "pr/298" refer to github pull request numbers.
 
+2.4.1 (Monday 27 May 2019)
+============================
+
+Contributions from Egor Pafilov, Jath Palasubramaniam, Richard Nemec, and
+Dave Allured.
+
+Enhancements
+------------
+* Enable ``mmap``, ``keep_file_open`` options when loading any
+  ``DataobjImage`` (pr/759) (CM, reviewed by PM)
+
+Bug fixes
+---------
+* Ensure loaded GIFTI files expose writable data arrays (pr/750) (CM,
+  reviewed by PM)
+* Safer warning registry manipulation when checking for overflows (pr/753)
+  (CM, reviewed by MB)
+* Correctly write .annot files with duplicate lables (pr/763) (Richard Nemec
+  with CM)
+
+Maintenance
+-----------
+* Fix typo in coordinate systems doc (pr/751) (Egor Panfilov, reviewed by
+  CM)
+* Replace invalid MINC1 test file with fixed file (pr/754) (Dave Allured
+  with CM)
+* Update Sphinx config to support recent Sphinx/numpydoc (pr/749) (CM,
+  reviewed by PM)
+* Pacify ``FutureWarning`` and ``DeprecationWarning`` from h5py, numpy
+  (pr/760) (CM)
+* Accommodate Python 3.8 deprecation of collections.MutableMapping
+  (pr/762) (Jath Palasubramaniam, reviewed by CM)
+
+API changes and deprecations
+----------------------------
+* Deprecate ``keep_file_open == 'auto'`` (pr/761) (CM, reviewed by PM)
+
 2.4.0 (Monday 1 April 2019)
 ============================
 

README.rst

@@ -18,14 +18,16 @@ Read / write access to some common neuroimaging file formats
 
 This package provides read +/- write access to some common medical and
 neuroimaging file formats, including: ANALYZE_ (plain, SPM99, SPM2 and later),
-GIFTI_, NIfTI1_, NIfTI2_, MINC1_, MINC2_, MGH_ and ECAT_ as well as Philips
-PAR/REC.  We can read and write FreeSurfer_ geometry, annotation and
-morphometry files.  There is some very limited support for DICOM_.  NiBabel is
-the successor of PyNIfTI_.
+GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_, MINC1_, MINC2_, `AFNI BRIK/HEAD`_, MGH_ and
+ECAT_ as well as Philips PAR/REC.  We can read and write FreeSurfer_ geometry,
+annotation and morphometry files.  There is some very limited support for
+DICOM_.  NiBabel is the successor of PyNIfTI_.
 
 .. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
+.. _AFNI BRIK/HEAD: https://afni.nimh.nih.gov/pub/dist/src/README.attributes
 .. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
 .. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
+.. _CIFTI-2: https://www.nitrc.org/projects/cifti/
 .. _MINC1:
     https://en.wikibooks.org/wiki/MINC/Reference/MINC1_File_Format_Reference
 .. _MINC2:

doc/source/index.rst

@@ -96,6 +96,8 @@ contributed code and discussion (in rough order of appearance):
 * Samir Reddigari
 * Konstantinos Raktivan
 * Matt Cieslak
+* Egor Pafilov
+* Jath Palasubramaniam
 
 License reprise
 ===============

nibabel/analyze.py

@@ -935,7 +935,11 @@ def set_data_dtype(self, dtype):
     @classmethod
     @kw_only_meth(1)
     def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
-        '''class method to create image from mapping in `file_map ``
+        ''' Class method to create image from mapping in ``file_map``
+
+        .. deprecated:: 2.4.1
+            ``keep_file_open='auto'`` is redundant with `False` and has
+            been deprecated. It will raise an error in nibabel 3.0.
 
         Parameters
         ----------
@@ -950,18 +954,14 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             `mmap` value of True gives the same behavior as ``mmap='c'``.  If
             image data file cannot be memory-mapped, ignore `mmap` value and
             read array from file.
-        keep_file_open : { None, 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, True, False }, optional, keyword only
             `keep_file_open` controls whether a new file handle is created
             every time the image is accessed, or a single file handle is
             created and used for the lifetime of this ``ArrayProxy``. If
             ``True``, a single file handle is created and used. If ``False``,
-            a new file handle is created every time the image is accessed. If
-            ``'auto'``, and the optional ``indexed_gzip`` dependency is
-            present, a single file handle is created and persisted. If
-            ``indexed_gzip`` is not available, behaviour is the same as if
-            ``keep_file_open is False``. If ``file_map`` refers to an open
-            file handle, this setting has no effect. The default value
-            (``None``) will result in the value of
+            a new file handle is created every time the image is accessed.
+            If ``file_map`` refers to an open file handle, this setting has no
+            effect. The default value (``None``) will result in the value of
             ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
 
         Returns
@@ -988,47 +988,6 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
                            'file_map': copy_file_map(file_map)}
         return img
 
-    @classmethod
-    @kw_only_meth(1)
-    def from_filename(klass, filename, mmap=True, keep_file_open=None):
-        '''class method to create image from filename `filename`
-
-        Parameters
-        ----------
-        filename : str
-            Filename of image to load
-        mmap : {True, False, 'c', 'r'}, optional, keyword only
-            `mmap` controls the use of numpy memory mapping for reading image
-            array data.  If False, do not try numpy ``memmap`` for data array.
-            If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A
-            `mmap` value of True gives the same behavior as ``mmap='c'``.  If
-            image data file cannot be memory-mapped, ignore `mmap` value and
-            read array from file.
-        keep_file_open : { None, 'auto', True, False }, optional, keyword only
-            `keep_file_open` controls whether a new file handle is created
-            every time the image is accessed, or a single file handle is
-            created and used for the lifetime of this ``ArrayProxy``. If
-            ``True``, a single file handle is created and used. If ``False``,
-            a new file handle is created every time the image is accessed. If
-            ``'auto'``, and the optional ``indexed_gzip`` dependency is
-            present, a single file handle is created and persisted. If
-            ``indexed_gzip`` is not available, behaviour is the same as if
-            ``keep_file_open is False``. The default value (``None``) will
-            result in the value of
-            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
-
-        Returns
-        -------
-        img : Analyze Image instance
-        '''
-        if mmap not in (True, False, 'c', 'r'):
-            raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
-        file_map = klass.filespec_to_file_map(filename)
-        return klass.from_file_map(file_map, mmap=mmap,
-                                   keep_file_open=keep_file_open)
-
-    load = from_filename
-
     @staticmethod
     def _get_fileholders(file_map):
         """ Return fileholder for header and image

nibabel/arrayproxy.py

@@ -27,6 +27,7 @@
 """
 from contextlib import contextmanager
 from threading import RLock
+import warnings
 
 import numpy as np
 
@@ -40,23 +41,22 @@
 """This flag controls whether a new file handle is created every time an image
 is accessed through an ``ArrayProxy``, or a single file handle is created and
 used for the lifetime of the ``ArrayProxy``. It should be set to one of
-``True``, ``False``, or ``'auto'``.
+``True`` or ``False``.
 
 Management of file handles will be performed either by ``ArrayProxy`` objects,
 or by the ``indexed_gzip`` package if it is used.
 
 If this flag is set to ``True``, a single file handle is created and used. If
-``False``, a new file handle is created every time the image is accessed. For
-gzip files, if ``'auto'``, and the optional ``indexed_gzip`` dependency is
-present, a single file handle is created and persisted. If ``indexed_gzip`` is
-not available, behaviour is the same as if ``keep_file_open is False``.
+``False``, a new file handle is created every time the image is accessed.
+If this flag is set to ``'auto'``, a ``DeprecationWarning`` will be raised, which
+will become a ``ValueError`` in nibabel 3.0.0.
 
 If this is set to any other value, attempts to create an ``ArrayProxy`` without
 specifying the ``keep_file_open`` flag will result in a ``ValueError`` being
 raised.
 
-.. warning:: Setting this flag to a value of ``'auto'`` will become deprecated
-             behaviour in version 2.4.0. Support for ``'auto'`` will be removed
+.. warning:: Setting this flag to a value of ``'auto'`` became deprecated
+             behaviour in version 2.4.1. Support for ``'auto'`` will be removed
              in version 3.0.0.
 """
 KEEP_FILE_OPEN_DEFAULT = False
@@ -100,6 +100,10 @@ class ArrayProxy(object):
     def __init__(self, file_like, spec, mmap=True, keep_file_open=None):
         """Initialize array proxy instance
 
+        .. deprecated:: 2.4.1
+            ``keep_file_open='auto'`` is redundant with `False` and has
+            been deprecated. It will raise an error in nibabel 3.0.
+
         Parameters
         ----------
         file_like : object
@@ -127,18 +131,15 @@ def __init__(self, file_like, spec, mmap=True, keep_file_open=None):
             True gives the same behavior as ``mmap='c'``.  If `file_like`
             cannot be memory-mapped, ignore `mmap` value and read array from
             file.
-        keep_file_open : { None, 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, True, False }, optional, keyword only
             `keep_file_open` controls whether a new file handle is created
             every time the image is accessed, or a single file handle is
             created and used for the lifetime of this ``ArrayProxy``. If
             ``True``, a single file handle is created and used. If ``False``,
-            a new file handle is created every time the image is accessed. If
-            ``'auto'``, and the optional ``indexed_gzip`` dependency is
-            present, a single file handle is created and persisted. If
-            ``indexed_gzip`` is not available, behaviour is the same as if
-            ``keep_file_open is False``. If ``file_like`` is an open file
-            handle, this setting has no effect. The default value (``None``)
-            will result in the value of ``KEEP_FILE_OPEN_DEFAULT`` being used.
+            a new file handle is created every time the image is accessed.
+            If ``file_like`` is an open file handle, this setting has no
+            effect. The default value (``None``) will result in the value of
+            ``KEEP_FILE_OPEN_DEFAULT`` being used.
         """
         if mmap not in (True, False, 'c', 'r'):
             raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
@@ -236,17 +237,9 @@ def _should_keep_file_open(self, file_like, keep_file_open):
            In this case, file handle management is delegated to the
            ``indexed_gzip`` library.
 
-        5. If ``keep_file_open`` is ``'auto'``, ``file_like`` is a path to a
-           ``.gz`` file, and ``indexed_gzip`` is present, both internal flags
-           are set to ``True``.
-
-        6. If ``keep_file_open`` is ``'auto'``, and ``file_like`` is not a
-           path to a ``.gz`` file, or ``indexed_gzip`` is not present, both
-           internal flags are set to ``False``.
-
-        Note that a value of ``'auto'`` for ``keep_file_open`` will become
-        deprecated behaviour in version 2.4.0, and support for ``'auto'`` will
-        be removed in version 3.0.0.
+        .. deprecated:: 2.4.1
+            ``keep_file_open='auto'`` is redundant with `False` and has
+            been deprecated. It will be removed in nibabel 3.0.
 
         Parameters
         ----------
@@ -266,20 +259,26 @@ def _should_keep_file_open(self, file_like, keep_file_open):
         """
         if keep_file_open is None:
             keep_file_open = KEEP_FILE_OPEN_DEFAULT
-        if keep_file_open not in ('auto', True, False):
-            raise ValueError('keep_file_open should be one of {None, '
-                             '\'auto\', True, False}')
+            if keep_file_open == 'auto':
+                warnings.warn("Setting nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT to 'auto' is "
+                              "deprecated and will become an error in v3.0.", DeprecationWarning)
+        if keep_file_open == 'auto':
+            warnings.warn("A value of 'auto' for keep_file_open is deprecated and will become an "
+                          "error in v3.0. You probably want False.", DeprecationWarning)
+        elif keep_file_open not in (True, False):
+            raise ValueError('keep_file_open should be one of {None, True, False}')
+
         # file_like is a handle - keep_file_open is irrelevant
         if hasattr(file_like, 'read') and hasattr(file_like, 'seek'):
             return False, False
         # if the file is a gzip file, and we have_indexed_gzip,
         have_igzip = openers.HAVE_INDEXED_GZIP and file_like.endswith('.gz')
+        # XXX Remove in v3.0
         if keep_file_open == 'auto':
             return have_igzip, have_igzip
-        elif keep_file_open:
-            return True, True
-        else:
-            return False, have_igzip
+
+        persist_opener = keep_file_open or have_igzip
+        return keep_file_open, persist_opener
 
     @property
     @deprecate_with_version('ArrayProxy.header deprecated', '2.2', '3.0')