Skip to content

Commit 97447e2

Browse files
effigieseffigies
committed
Merge remote-tracking branch 'upstream/maint/2.4.x'
2 parents ed3cdb5 + 79392b0 commit 97447e2

26 files changed

+405
-295
lines changed

‎Changelog

+37
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,43 @@ Eric Larson (EL), Demian Wassermann, and Stephan Gerhard.
2525

2626
References like "pr/298" refer to github pull request numbers.
2727

28+
2.4.1 (Monday 27 May 2019)
29+
============================
30+
31+
Contributions from Egor Pafilov, Jath Palasubramaniam, Richard Nemec, and
32+
Dave Allured.
33+
34+
Enhancements
35+
------------
36+
* Enable ``mmap``, ``keep_file_open`` options when loading any
37+
``DataobjImage`` (pr/759) (CM, reviewed by PM)
38+
39+
Bug fixes
40+
---------
41+
* Ensure loaded GIFTI files expose writable data arrays (pr/750) (CM,
42+
reviewed by PM)
43+
* Safer warning registry manipulation when checking for overflows (pr/753)
44+
(CM, reviewed by MB)
45+
* Correctly write .annot files with duplicate lables (pr/763) (Richard Nemec
46+
with CM)
47+
48+
Maintenance
49+
-----------
50+
* Fix typo in coordinate systems doc (pr/751) (Egor Panfilov, reviewed by
51+
CM)
52+
* Replace invalid MINC1 test file with fixed file (pr/754) (Dave Allured
53+
with CM)
54+
* Update Sphinx config to support recent Sphinx/numpydoc (pr/749) (CM,
55+
reviewed by PM)
56+
* Pacify ``FutureWarning`` and ``DeprecationWarning`` from h5py, numpy
57+
(pr/760) (CM)
58+
* Accommodate Python 3.8 deprecation of collections.MutableMapping
59+
(pr/762) (Jath Palasubramaniam, reviewed by CM)
60+
61+
API changes and deprecations
62+
----------------------------
63+
* Deprecate ``keep_file_open == 'auto'`` (pr/761) (CM, reviewed by PM)
64+
2865
2.4.0 (Monday 1 April 2019)
2966
============================
3067

‎README.rst

+6-4
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,16 @@ Read / write access to some common neuroimaging file formats
1818

1919
This package provides read +/- write access to some common medical and
2020
neuroimaging file formats, including: ANALYZE_ (plain, SPM99, SPM2 and later),
21-
GIFTI_, NIfTI1_, NIfTI2_, MINC1_, MINC2_, MGH_ and ECAT_ as well as Philips
22-
PAR/REC. We can read and write FreeSurfer_ geometry, annotation and
23-
morphometry files. There is some very limited support for DICOM_. NiBabel is
24-
the successor of PyNIfTI_.
21+
GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_, MINC1_, MINC2_, `AFNI BRIK/HEAD`_, MGH_ and
22+
ECAT_ as well as Philips PAR/REC. We can read and write FreeSurfer_ geometry,
23+
annotation and morphometry files. There is some very limited support for
24+
DICOM_. NiBabel is the successor of PyNIfTI_.
2525

2626
.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
27+
.. _AFNI BRIK/HEAD: https://afni.nimh.nih.gov/pub/dist/src/README.attributes
2728
.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
2829
.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
30+
.. _CIFTI-2: https://www.nitrc.org/projects/cifti/
2931
.. _MINC1:
3032
https://en.wikibooks.org/wiki/MINC/Reference/MINC1_File_Format_Reference
3133
.. _MINC2:

‎doc/source/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,8 @@ contributed code and discussion (in rough order of appearance):
9696
* Samir Reddigari
9797
* Konstantinos Raktivan
9898
* Matt Cieslak
99+
* Egor Pafilov
100+
* Jath Palasubramaniam
99101

100102
License reprise
101103
===============

‎nibabel/analyze.py

+9-50
Original file line numberDiff line numberDiff line change
@@ -935,7 +935,11 @@ def set_data_dtype(self, dtype):
935935
@classmethod
936936
@kw_only_meth(1)
937937
def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
938-
'''class method to create image from mapping in `file_map ``
938+
''' Class method to create image from mapping in ``file_map``
939+
940+
.. deprecated:: 2.4.1
941+
``keep_file_open='auto'`` is redundant with `False` and has
942+
been deprecated. It will raise an error in nibabel 3.0.
939943
940944
Parameters
941945
----------
@@ -950,18 +954,14 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
950954
`mmap` value of True gives the same behavior as ``mmap='c'``. If
951955
image data file cannot be memory-mapped, ignore `mmap` value and
952956
read array from file.
953-
keep_file_open : { None, 'auto', True, False }, optional, keyword only
957+
keep_file_open : { None, True, False }, optional, keyword only
954958
`keep_file_open` controls whether a new file handle is created
955959
every time the image is accessed, or a single file handle is
956960
created and used for the lifetime of this ``ArrayProxy``. If
957961
``True``, a single file handle is created and used. If ``False``,
958-
a new file handle is created every time the image is accessed. If
959-
``'auto'``, and the optional ``indexed_gzip`` dependency is
960-
present, a single file handle is created and persisted. If
961-
``indexed_gzip`` is not available, behaviour is the same as if
962-
``keep_file_open is False``. If ``file_map`` refers to an open
963-
file handle, this setting has no effect. The default value
964-
(``None``) will result in the value of
962+
a new file handle is created every time the image is accessed.
963+
If ``file_map`` refers to an open file handle, this setting has no
964+
effect. The default value (``None``) will result in the value of
965965
``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
966966
967967
Returns
@@ -988,47 +988,6 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
988988
'file_map': copy_file_map(file_map)}
989989
return img
990990

991-
@classmethod
992-
@kw_only_meth(1)
993-
def from_filename(klass, filename, mmap=True, keep_file_open=None):
994-
'''class method to create image from filename `filename`
995-
996-
Parameters
997-
----------
998-
filename : str
999-
Filename of image to load
1000-
mmap : {True, False, 'c', 'r'}, optional, keyword only
1001-
`mmap` controls the use of numpy memory mapping for reading image
1002-
array data. If False, do not try numpy ``memmap`` for data array.
1003-
If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``. A
1004-
`mmap` value of True gives the same behavior as ``mmap='c'``. If
1005-
image data file cannot be memory-mapped, ignore `mmap` value and
1006-
read array from file.
1007-
keep_file_open : { None, 'auto', True, False }, optional, keyword only
1008-
`keep_file_open` controls whether a new file handle is created
1009-
every time the image is accessed, or a single file handle is
1010-
created and used for the lifetime of this ``ArrayProxy``. If
1011-
``True``, a single file handle is created and used. If ``False``,
1012-
a new file handle is created every time the image is accessed. If
1013-
``'auto'``, and the optional ``indexed_gzip`` dependency is
1014-
present, a single file handle is created and persisted. If
1015-
``indexed_gzip`` is not available, behaviour is the same as if
1016-
``keep_file_open is False``. The default value (``None``) will
1017-
result in the value of
1018-
``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
1019-
1020-
Returns
1021-
-------
1022-
img : Analyze Image instance
1023-
'''
1024-
if mmap not in (True, False, 'c', 'r'):
1025-
raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
1026-
file_map = klass.filespec_to_file_map(filename)
1027-
return klass.from_file_map(file_map, mmap=mmap,
1028-
keep_file_open=keep_file_open)
1029-
1030-
load = from_filename
1031-
1032991
@staticmethod
1033992
def _get_fileholders(file_map):
1034993
""" Return fileholder for header and image

‎nibabel/arrayproxy.py

+32-33
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"""
2828
from contextlib import contextmanager
2929
from threading import RLock
30+
import warnings
3031

3132
import numpy as np
3233

@@ -40,23 +41,22 @@
4041
"""This flag controls whether a new file handle is created every time an image
4142
is accessed through an ``ArrayProxy``, or a single file handle is created and
4243
used for the lifetime of the ``ArrayProxy``. It should be set to one of
43-
``True``, ``False``, or ``'auto'``.
44+
``True`` or ``False``.
4445
4546
Management of file handles will be performed either by ``ArrayProxy`` objects,
4647
or by the ``indexed_gzip`` package if it is used.
4748
4849
If this flag is set to ``True``, a single file handle is created and used. If
49-
``False``, a new file handle is created every time the image is accessed. For
50-
gzip files, if ``'auto'``, and the optional ``indexed_gzip`` dependency is
51-
present, a single file handle is created and persisted. If ``indexed_gzip`` is
52-
not available, behaviour is the same as if ``keep_file_open is False``.
50+
``False``, a new file handle is created every time the image is accessed.
51+
If this flag is set to ``'auto'``, a ``DeprecationWarning`` will be raised, which
52+
will become a ``ValueError`` in nibabel 3.0.0.
5353
5454
If this is set to any other value, attempts to create an ``ArrayProxy`` without
5555
specifying the ``keep_file_open`` flag will result in a ``ValueError`` being
5656
raised.
5757
58-
.. warning:: Setting this flag to a value of ``'auto'`` will become deprecated
59-
behaviour in version 2.4.0. Support for ``'auto'`` will be removed
58+
.. warning:: Setting this flag to a value of ``'auto'`` became deprecated
59+
behaviour in version 2.4.1. Support for ``'auto'`` will be removed
6060
in version 3.0.0.
6161
"""
6262
KEEP_FILE_OPEN_DEFAULT = False
@@ -100,6 +100,10 @@ class ArrayProxy(object):
100100
def __init__(self, file_like, spec, mmap=True, keep_file_open=None):
101101
"""Initialize array proxy instance
102102
103+
.. deprecated:: 2.4.1
104+
``keep_file_open='auto'`` is redundant with `False` and has
105+
been deprecated. It will raise an error in nibabel 3.0.
106+
103107
Parameters
104108
----------
105109
file_like : object
@@ -127,18 +131,15 @@ def __init__(self, file_like, spec, mmap=True, keep_file_open=None):
127131
True gives the same behavior as ``mmap='c'``. If `file_like`
128132
cannot be memory-mapped, ignore `mmap` value and read array from
129133
file.
130-
keep_file_open : { None, 'auto', True, False }, optional, keyword only
134+
keep_file_open : { None, True, False }, optional, keyword only
131135
`keep_file_open` controls whether a new file handle is created
132136
every time the image is accessed, or a single file handle is
133137
created and used for the lifetime of this ``ArrayProxy``. If
134138
``True``, a single file handle is created and used. If ``False``,
135-
a new file handle is created every time the image is accessed. If
136-
``'auto'``, and the optional ``indexed_gzip`` dependency is
137-
present, a single file handle is created and persisted. If
138-
``indexed_gzip`` is not available, behaviour is the same as if
139-
``keep_file_open is False``. If ``file_like`` is an open file
140-
handle, this setting has no effect. The default value (``None``)
141-
will result in the value of ``KEEP_FILE_OPEN_DEFAULT`` being used.
139+
a new file handle is created every time the image is accessed.
140+
If ``file_like`` is an open file handle, this setting has no
141+
effect. The default value (``None``) will result in the value of
142+
``KEEP_FILE_OPEN_DEFAULT`` being used.
142143
"""
143144
if mmap not in (True, False, 'c', 'r'):
144145
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):
236237
In this case, file handle management is delegated to the
237238
``indexed_gzip`` library.
238239
239-
5. If ``keep_file_open`` is ``'auto'``, ``file_like`` is a path to a
240-
``.gz`` file, and ``indexed_gzip`` is present, both internal flags
241-
are set to ``True``.
242-
243-
6. If ``keep_file_open`` is ``'auto'``, and ``file_like`` is not a
244-
path to a ``.gz`` file, or ``indexed_gzip`` is not present, both
245-
internal flags are set to ``False``.
246-
247-
Note that a value of ``'auto'`` for ``keep_file_open`` will become
248-
deprecated behaviour in version 2.4.0, and support for ``'auto'`` will
249-
be removed in version 3.0.0.
240+
.. deprecated:: 2.4.1
241+
``keep_file_open='auto'`` is redundant with `False` and has
242+
been deprecated. It will be removed in nibabel 3.0.
250243
251244
Parameters
252245
----------
@@ -266,20 +259,26 @@ def _should_keep_file_open(self, file_like, keep_file_open):
266259
"""
267260
if keep_file_open is None:
268261
keep_file_open = KEEP_FILE_OPEN_DEFAULT
269-
if keep_file_open not in ('auto', True, False):
270-
raise ValueError('keep_file_open should be one of {None, '
271-
'\'auto\', True, False}')
262+
if keep_file_open == 'auto':
263+
warnings.warn("Setting nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT to 'auto' is "
264+
"deprecated and will become an error in v3.0.", DeprecationWarning)
265+
if keep_file_open == 'auto':
266+
warnings.warn("A value of 'auto' for keep_file_open is deprecated and will become an "
267+
"error in v3.0. You probably want False.", DeprecationWarning)
268+
elif keep_file_open not in (True, False):
269+
raise ValueError('keep_file_open should be one of {None, True, False}')
270+
272271
# file_like is a handle - keep_file_open is irrelevant
273272
if hasattr(file_like, 'read') and hasattr(file_like, 'seek'):
274273
return False, False
275274
# if the file is a gzip file, and we have_indexed_gzip,
276275
have_igzip = openers.HAVE_INDEXED_GZIP and file_like.endswith('.gz')
276+
# XXX Remove in v3.0
277277
if keep_file_open == 'auto':
278278
return have_igzip, have_igzip
279-
elif keep_file_open:
280-
return True, True
281-
else:
282-
return False, have_igzip
279+
280+
persist_opener = keep_file_open or have_igzip
281+
return keep_file_open, persist_opener
283282

284283
@property
285284
@deprecate_with_version('ArrayProxy.header deprecated', '2.2', '3.0')

0 commit comments

Comments
 (0)