Merge branch 'master' into sparse-models

doc/modules/reference.rst

@@ -150,6 +150,29 @@ uses.
 
 **Functions**:
 
+.. currentmodule:: nilearn.masking
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   compute_epi_mask
+   compute_multi_epi_mask
+   compute_background_mask
+   compute_multi_background_mask
+   intersect_mask
+   apply_mask
+   unmask
+
+:mod:`nilearn.region`: Operating on regions
+==============================================
+
+.. automodule:: nilearn.region
+   :no-members:
+   :no-inherited-members:
+
+**Functions**:
+
 .. currentmodule:: nilearn.region
 
 .. autosummary::
@@ -161,12 +184,12 @@ uses.
    img_to_signals_maps
    signals_to_img_maps
 
+
 .. seealso::
 
    :func:`nilearn.masking.apply_mask`,
    :func:`nilearn.masking.unmask`
 
-
 :mod:`nilearn.mass_univariate`: Mass-univariate analysis
 =========================================================
 

examples/README.txt

@@ -1,8 +1,9 @@
 .. warning::
 
-    If you want to run the examples you need to make sure you have
-    installed nilearn by following the instructions :ref:`there
-    <installation>`.
+    If you want to run the examples, make sure you execute them in a directory
+    where you have write permissions, or you copy the examples into such a
+    directory. If you install nilearn manually, make sure you have followed
+    :ref:`the instructions <installation>`.
 
 .. note::
 

nilearn/_utils/niimg.py

@@ -30,6 +30,51 @@ def _safe_get_data(img):
     return img.get_data()
 
 
+def _get_data_dtype(img):
+    """Returns the dtype of an image.
+    If the image is non standard (no get_data_dtype member), this function
+    relies on the data itself.
+    """
+    try:
+        return img.get_data_dtype()
+    except AttributeError:
+        return img.get_data().dtype
+
+
+def _get_target_dtype(dtype, target_dtype):
+    """Returns a new dtype if conversion is needed
+
+    Parameters
+    ----------
+
+    dtype: dtype
+        Data type of the original data
+
+    target_dtype: {None, dtype, "auto"}
+        If None, no conversion is required. If a type is provided, the
+        function will check if a conversion is needed. The "auto" mode will
+        automatically convert to int32 if dtype is discrete and float32 if it
+        is continuous.
+
+    Returns
+    -------
+
+    dtype: dtype
+        The data type toward which the original data should be converted.
+    """
+
+    if target_dtype is None:
+        return None
+    if target_dtype == 'auto':
+        if dtype.kind == 'i':
+            target_dtype = np.int32
+        else:
+            target_dtype = np.float32
+    if target_dtype == dtype:
+        return None
+    return target_dtype
+
+
 def load_niimg(niimg, dtype=None):
     """Load a niimg, check if it is a nibabel SpatialImage and cast if needed
 
@@ -40,6 +85,11 @@ def load_niimg(niimg, dtype=None):
         See http://nilearn.github.io/building_blocks/manipulating_mr_images.html#niimg.
         Image to load.
 
+    dtype: {dtype, "auto"}
+        Data type toward which the data should be converted. If "auto", the
+        data will be converted to int32 if dtype is discrete and float32 if it
+        is continuous.
+
     Returns:
     --------
     img: image
@@ -52,6 +102,12 @@ def load_niimg(niimg, dtype=None):
         raise TypeError("Data given cannot be loaded because it is"
                         " not compatible with nibabel format:\n"
                         + short_repr(niimg))
+
+    dtype = _get_target_dtype(_get_data_dtype(niimg), dtype)
+
+    if dtype is not None:
+        niimg = new_img_like(niimg, niimg.get_data().astype(dtype),
+                             niimg.get_affine())
     return niimg
 
 

nilearn/_utils/niimg_conversions.py

@@ -70,7 +70,7 @@ def _index_img(img, index):
 
 
 def _iter_check_niimg(niimgs, ensure_ndim=None, atleast_4d=False,
-                      target_fov=None,
+                      target_fov=None, dtype=None,
                       memory=Memory(cachedir=None),
                       memory_level=0, verbose=0):
     """Iterate over a list of niimgs and do sanity checks and resampling
@@ -90,6 +90,11 @@ def _iter_check_niimg(niimgs, ensure_ndim=None, atleast_4d=False,
 
     target_fov: tuple of affine and shape
        If specified, images are resampled to this field of view
+
+    dtype: {dtype, "auto"}
+        Data type toward which the data should be converted. If "auto", the
+        data will be converted to int32 if dtype is discrete and float32 if it
+        is continuous.
     """
     ref_fov = None
     resample_to_first_img = False
@@ -99,7 +104,8 @@ def _iter_check_niimg(niimgs, ensure_ndim=None, atleast_4d=False,
     for i, niimg in enumerate(niimgs):
         try:
             niimg = check_niimg(
-                niimg, ensure_ndim=ndim_minus_one, atleast_4d=atleast_4d)
+                niimg, ensure_ndim=ndim_minus_one, atleast_4d=atleast_4d,
+                dtype=dtype)
             if i == 0:
                 ndim_minus_one = len(niimg.shape)
                 if ref_fov is None:
@@ -141,7 +147,7 @@ def _iter_check_niimg(niimgs, ensure_ndim=None, atleast_4d=False,
             raise
 
 
-def check_niimg(niimg, ensure_ndim=None, atleast_4d=False,
+def check_niimg(niimg, ensure_ndim=None, atleast_4d=False, dtype=None,
                 return_iterator=False):
     """Check that niimg is a proper 3D/4D niimg. Turn filenames into objects.
 
@@ -160,6 +166,11 @@ def check_niimg(niimg, ensure_ndim=None, atleast_4d=False,
     atleast_4d: boolean, optional
         Indicates if a 3d image should be turned into a single-scan 4d niimg.
 
+    dtype: {dtype, "auto"}
+        Data type toward which the data should be converted. If "auto", the
+        data will be converted to int32 if dtype is discrete and float32 if it
+        is continuous.
+
     Returns
     -------
     result: 3D/4D Niimg-like object
@@ -179,11 +190,12 @@ def check_niimg(niimg, ensure_ndim=None, atleast_4d=False,
     # in case of an iterable
     if hasattr(niimg, "__iter__") and not isinstance(niimg, _basestring):
         if return_iterator:
-            return _iter_check_niimg(niimg, ensure_ndim=ensure_ndim)
-        return concat_niimgs(niimg, ensure_ndim=ensure_ndim)
+            return _iter_check_niimg(niimg, ensure_ndim=ensure_ndim,
+                                     dtype=dtype)
+        return concat_niimgs(niimg, ensure_ndim=ensure_ndim, dtype=dtype)
 
     # Otherwise, it should be a filename or a SpatialImage, we load it
-    niimg = load_niimg(niimg)
+    niimg = load_niimg(niimg, dtype=dtype)
 
     if ensure_ndim == 3 and len(niimg.shape) == 4 and niimg.shape[3] == 1:
         # "squeeze" the image.
@@ -204,7 +216,7 @@ def check_niimg(niimg, ensure_ndim=None, atleast_4d=False,
     return niimg
 
 
-def check_niimg_3d(niimg):
+def check_niimg_3d(niimg, dtype=None):
     """Check that niimg is a proper 3D niimg-like object and load it.
     Parameters
     ----------
@@ -213,6 +225,11 @@ def check_niimg_3d(niimg):
         If niimg is a string, consider it as a path to Nifti image and
         call nibabel.load on it. If it is an object, check if get_data()
         and get_affine() methods are present, raise TypeError otherwise.
+    
+    dtype: {dtype, "auto"}
+        Data type toward which the data should be converted. If "auto", the
+        data will be converted to int32 if dtype is discrete and float32 if it
+        is continuous.
 
     Returns
     -------
@@ -229,10 +246,10 @@ def check_niimg_3d(niimg):
 
     Its application is idempotent.
     """
-    return check_niimg(niimg, ensure_ndim=3)
+    return check_niimg(niimg, ensure_ndim=3, dtype=dtype)
 
 
-def check_niimg_4d(niimg, return_iterator=False):
+def check_niimg_4d(niimg, return_iterator=False, dtype=None):
     """Check that niimg is a proper 4D niimg-like object and load it.
 
     Parameters
@@ -245,6 +262,11 @@ def check_niimg_4d(niimg, return_iterator=False):
         call nibabel.load on it. If it is an object, check if get_data
         and get_affine methods are present, raise an Exception otherwise.
 
+    dtype: {dtype, "auto"}
+        Data type toward which the data should be converted. If "auto", the
+        data will be converted to int32 if dtype is discrete and float32 if it
+        is continuous.
+    
     return_iterator: boolean
         If True, an iterator of 3D images is returned. This reduces the memory
         usage when `niimgs` contains 3D images.
@@ -262,7 +284,8 @@ def check_niimg_4d(niimg, return_iterator=False):
 
     Its application is idempotent.
     """
-    return check_niimg(niimg, ensure_ndim=4, return_iterator=return_iterator)
+    return check_niimg(niimg, ensure_ndim=4, return_iterator=return_iterator,
+                       dtype=dtype)
 
 
 def concat_niimgs(niimgs, dtype=np.float32, ensure_ndim=None,

nilearn/input_data/nifti_labels_masker.py

@@ -266,8 +266,8 @@ def transform(self, imgs, confounds=None):
                 self._resampled_labels_img_ = self._cache(
                     image.resample_img, func_memory_level=2)(
                         self.labels_img_, interpolation="nearest",
-                        target_shape=imgs.shape[:3],
-                        target_affine=imgs.get_affine())
+                        target_shape=imgs_.shape[:3],
+                        target_affine=imgs_.get_affine())
 
         region_signals = self._cache(
                 _extract_signals,

nilearn/input_data/tests/test_nifti_labels_masker.py

@@ -101,7 +101,6 @@ def test_nifti_labels_masker():
     np.testing.assert_almost_equal(fmri11_img_r.get_affine(),
                                    fmri11_img.get_affine())
 
-
 def test_nifti_labels_masker_resampling():
     # Test resampling in NiftiLabelsMasker
     shape1 = (10, 11, 12)
@@ -214,3 +213,11 @@ def test_nifti_labels_masker_resampling():
     np.testing.assert_array_equal(
         masker._resampled_labels_img_.get_affine(),
         affine2)
+
+    # Test with filenames
+    with testing.write_tmp_imgs(fmri22_img) as filename:
+        masker = NiftiLabelsMasker(labels33_img, resampling_target='data')
+        masker.fit_transform(filename)
+
+
+

nilearn/masking.py

@@ -1,5 +1,5 @@
 """
-Utilities to compute a brain mask from EPI images
+Utilities to compute and operate on brain masks
 """
 # Author: Gael Varoquaux, Alexandre Abraham, Philippe Gervais
 # License: simplified BSD

nilearn/plotting/displays.py

@@ -523,6 +523,7 @@ def _map_show(self, img, type='imshow',
                   resampling_interpolation='continuous',
                   threshold=None, **kwargs):
         img = reorder_img(img, resample=resampling_interpolation)
+        threshold = float(threshold) if threshold is not None else None
 
         if threshold is not None:
             data = img.get_data()

nilearn/plotting/img_plotting.py

@@ -74,7 +74,7 @@ def _plot_img_with_bg(img, bg_img=None, cut_coords=None,
         warnings.warn(nan_msg)
 
     if img is not False and img is not None:
-        img = _utils.check_niimg_3d(img)
+        img = _utils.check_niimg_3d(img, dtype='auto')
         data = img.get_data()
         affine = img.get_affine()
 
@@ -639,7 +639,7 @@ def plot_stat_map(stat_map_img, bg_img=MNI152TEMPLATE, cut_coords=None,
 
     # make sure that the color range is symmetrical
     if vmax is None or symmetric_cbar in ['auto', False]:
-        stat_map_img = _utils.check_niimg_3d(stat_map_img)
+        stat_map_img = _utils.check_niimg_3d(stat_map_img, dtype='auto')
         stat_map_data = stat_map_img.get_data()
         # Avoid dealing with masked_array:
         if hasattr(stat_map_data, '_mask'):

nilearn/plotting/tests/test_img_plotting.py

@@ -149,6 +149,23 @@ def test_plot_stat_map_threshold_for_affine_with_rotation():
     assert_true(plotted_array.mask.all())
 
 
+def test_plot_stat_map_threshold_for_uint8():
+    # mask was applied in [-threshold, threshold] which is problematic
+    # for uint8 data. See https://github.com/nilearn/nilearn/issues/611
+    # for more details
+    data = 10 * np.ones((10, 10, 10), dtype='uint8')
+    affine = np.eye(4)
+    img = nibabel.Nifti1Image(data, affine)
+    threshold = np.array(5, dtype='uint8')
+    display = plot_stat_map(img, bg_img=None, threshold=threshold,
+                            display_mode='z', cut_coords=1)
+    # Next two lines retrieve the numpy array from the plot
+    ax = list(display.axes.values())[0].ax
+    plotted_array = ax.images[0].get_array()
+    # Make sure that no data is masked
+    assert_equal(plotted_array.mask.sum(), 0)
+
+
 def test_save_plot():
     img = _generate_img()