What’s new#

0.9.2.dev#

NEW#

Fixes#

  • Fix _NEUROVAULT_BASE_URL and _NEUROSYNTH_FETCH_WORDS_URL in nilearn/datasets/neurovault.py by using https instead of http (#3281 by Manon Pietrantoni).

  • Convert references in nilearn/mass_univariate/permuted_least_squares.py to use bibtex format (#3222 by Yasmin Mzayek).

  • Update Craddock 2012 parcellation url in nilearn/datasets/atlas.py (#3233 by Vasco Diogo)

  • plot_roi failed before when used with the “contours” view type and passing a list of cut coordinates in display mode “x”, “y” or “z”; this has been corrected (#3241 by Jerome Dockes).

  • plot_markers can now plot a single scatter point (#3255 by Caglar Cakan).

  • Fix title display for plot_surf_stat_map. The title argument does not set the figure title anymore but the axis title. (#3220 by Raphael Meudec).

  • load_surf_mesh loaded FreeSurfer specific surface files (e.g. .pial) with a shift in the coordinates. This is fixed by adding the c_ras coordinates to the mesh coordinates (#3235 by Yasmin Mzayek).

  • Function nilearn.glm.second_level.second_level._check_second_level_input now raises an error when flm_object argument is False and second_level_input is a list of FirstLevelModel (#3283 by Matthieu Joulot).

  • Function resample_img now warns the user if the provided image has an sform code equal to 0 or None (#3284 by Matthieu Joulot).

  • Fix usage of scipy.stats.gamma.pdf in _gamma_difference_hrf function under nilearn/glm/first_level/hemodynamic_models.py, which resulted in slight distortion of HRF (#3297 by Kun CHEN).

  • Fix bug introduced due to a fix in the pre-release version of scipy (1.9.0rc1) which now enforces that elements of a band-pass filter must meet condition Wn[0] < Wn[1]. Now if band-pass elements are equal butterworth returns an unfiltered signal with a warning (#3293 by Yasmin Mzayek).

  • The parameter alpha is now correctly passed to plot_glass_brain in plot_connectome (#3306 by Koen Helwegen).

Enhancements#

Changes#

0.9.1#

Released April 2022

This is a bugfix release.

Fixes#

Enhancements#

Changes#

  • The documentation for get_clusters_table has been improved, with more information about what inputs are valid and what the resulting table should look like (#3178 by Taylor Salo).

  • Requirements files have been consolidated into a setup.cfg file and installation instructions have been simplified (#2953 by Taylor Salo).

0.9.0#

Released January 2022

HIGHLIGHTS#

Warning

Python 3.6 is deprecated and will be removed in release 0.10.
We recommend upgrading to Python 3.9.

Nibabel 2.x is no longer supported. Please consider upgrading to Nibabel >= 3.0.

Minimum supported versions of packages have been bumped up:
- Numpy – v1.18
- SciPy – v1.5
- Scikit-learn – v0.22
- Pandas – v1.0
- Joblib – v0.15

NEW#

Fixes#

Enhancements#

  • Function threshold_img accepts new parameters cluster_threshold and two_sided. cluster_threshold applies a cluster-size threshold (in voxels). two_sided, which is True by default, separately thresholds both positive and negative values in the map, as was done previously. When two_sided is False, only values greater than or equal to the threshold are retained (#2965 by Taylor Salo).

  • Function clean raises a warning when the user sets parameters detrend and standardize_confound to False. The user is suggested to set one of those options to True, or standardize/demean the confounds before using the function (#3003 by Hao-Ting Wang).

  • The contributing documentation and maintenance pages were improved, especially towards ways of contributing to the project which do not require to write code. The roles of the Triage team were defined more clearly with sections on issue Labels and issue Closing policy (#3010 by Nicolas Gensollen).

  • It is now possible to provide custom HRF models to FirstLevelModel. The custom model should be defined as a function, or a list of functions, implementing the same API as Nilearn’s usual models (see spm_hrf for example). The example Example of MRI response functions was also modified to demo how to define custom HRF models (#2942 by Nicolas Gensollen).

  • Class NiftiLabelsMasker now gives a warning when some labels are removed from the label image at transform time due to resampling of the label image to the data image (#3008 by Nicolas Gensollen).

  • Function non_parametric_inference now accepts DataFrame as possible values for its second_level_input parameter. Note that a new parameter first_level_contrast has been added to this function to enable this feature (#3042 by Nicolas Gensollen).

  • Tests from nilearn/plotting/tests/test_img_plotting.py have been refactored and reorganized in separate files in new folder nilearn/plotting/tests/test_img_plotting/ (#3015 by Nicolas Gensollen).

  • Once a SecondLevelModel has been fitted and contrasts have been computed, it is now possible to access the residuals, predicted, and r_square model attributes like it was already possible for FirstLevelModel (#3033 by Nicolas Gensollen).

  • Importing nilearn.plotting will now raise a warning if the matplotlib backend has been changed from its original value, instead of silently modifying it (#3077 by Raphael Meudec).

  • Function plot_img and deriving functions like plot_anat, plot_stat_map, or plot_epi now accept an optional argument cbar_tick_format to specify how numbers should be displayed on the colorbar. This is consistent with the API of surface plotting functions (see release 0.7.1). The default format is scientific notation (#2859 by Nicolas Gensollen).

Changes#

  • Nibabel 2.x is no longer supported. Please consider upgrading to Nibabel >= 3.0 (#3106 by Nicolas Gensollen).

  • Deprecated function nilearn.datasets.fetch_cobre has been removed (#3081 by Nicolas Gensollen).

  • Deprecated function nilearn.plotting.plot_connectome_strength has been removed (#3082 by Nicolas Gensollen).

  • Deprecated function nilearn.masking.compute_gray_matter_mask has been removed (#3090 by Nicolas Gensollen).

  • Deprecated parameter sessions of function clean has been removed. Use runs instead (#3093 by Nicolas Gensollen).

  • Deprecated parameters sessions and sample_mask of NiftiMasker have been removed. Please use runs instead of sessions, and provide a sample_mask through transform (#3133 by Nicolas Gensollen).

  • Function glm.first_level.compute_regressor will now raise an exception if parameter cond_id is not a string which could be used to name a python variable. For instance, number strings (ex: “1”) will no longer be accepted as valid condition names. In particular, this will also impact glm.first_level.make_first_level_design_matrix and glm.first_level.FirstLevelModel, for which proper condition names will also be needed (#3025 by Alexis Thual).

  • Replace parameter sessions with runs in function clean_img as this replacement was already made for function clean in #2821 in order to match BIDS semantics. The use of sessions in function clean_img is deprecated and will be removed in 0.10.0 (#3039 by Nicolas Gensollen).

  • Display objects have been reorganized. For example, Slicers (like the OrthoSlicer) are all in file nilearn/plotting/displays/_slicers.py, and Projectors (like the OrthoProjector) are all in file nilearn/plotting/displays/_projectors.py. All display objects have been added to the public API, and examples have been improved to show how to use these objects to customize figures obtained with plotting functions (#3073 by Nicolas Gensollen).

  • Descriptions of datasets retrieved with fetchers from nilearn.datasets are now python strings rather than bytes. Therefore, decoding the descriptions is no longer necessary (#2655 by Nicolas Gensollen).

  • Dataset fetchers returning a recarray can now return a DataFrame instead. These fetchers now have a legacy_format optional argument defaulting to True for backward compatibility. Users will be warned that this parameter will default to False in release 0.11.0, making DataFrame the default return type instead or recarray (#2829 by Ahmad Chamma).

0.8.1#

Released September 2021

HIGHLIGHTS#

NEW#

Fixes#

Enhancements#

  • Function load_mni152_template resamples now the template to a preset resolution different from the resolution of the original template, i.e. 1mm. The default resolution is 2mm, which means that the new template is resampled to the resolution of the old template. Nevertheless, the shape of the template changed from (91, 109, 91) to (99, 117, 95); the affine also changed from array([[-2., 0., 0., 90.], [0., 2., 0., -126.], [0., 0., 2., -72.], [0., 0., 0., 1.]]) to array([[1., 0., 0., -98.], [0., 1., 0., -134.], [0., 0., 1., -72.], [0., 0., 0., 1.]]). Additionally, the new template has also been rescaled; whereas the old one varied between 0 and 8339, the new one varies between 0 and 255 (#2738 by Ana Luisa Pinho).

  • Function load_mni152_brain_mask accepts now the parameter resolution, which will set the resolution of the template used for the masking (#2738 by Ana Luisa Pinho).

  • Function compute_brain_mask accepts now as input the whole-brain, 1mm-resolution, MNI152 T1 template instead of the averaged, whole-brain, 2mm-resolution MNI152 T1 template; it also accepts as input the grey-matter and white-matter ICBM152 1mm-resolution templates dated from 2009 (#2738 by Ana Luisa Pinho).

  • Common parts of docstrings across Nilearn can now be filled automatically using the decorator nilearn._utils.fill_doc. This can be applied to common function parameters or common lists of options for example. The standard parts are defined in a single location (nilearn._utils.docs.py) which makes them easier to maintain and update (#2875 by Nicolas Gensollen).

  • The data_dir argument can now be either a pathlib.Path or a str. This extension affects datasets and atlas fetchers (#2928 by Raphael Meudec).

Changes#

  • The version of the script jquery.min.js was bumped from 3.3.1 to 3.6.0 due to potential vulnerability issues with versions < 3.5.0 (#2944 by Nicolas Gensollen).

0.8.0#

Released June 2021

HIGHLIGHTS#

Warning

Python 3.5 is no longer supported. We recommend upgrading to Python 3.8.

Support for Nibabel 2.x is deprecated and will be removed in the 0.9 release.
Users with a version of Nibabel < 3.0 will be warned at their first Nilearn import.

Minimum supported versions of packages have been bumped up:
- Numpy – v1.16
- SciPy – v1.2
- Scikit-learn – v0.21
- Nibabel – v2.5
- Pandas – v0.24

NEW#

  • Function clean now accepts a new parameter sample_mask of shape (number of scans - number of volumes removed, ). Masks the niimgs along time/fourth dimension to perform scrubbing (remove volumes with high motion) and/or non-steady-state volumes. Masking is applied before signal cleaning (#2858 by Hao-Ting Wang).

  • All inherent classes of nilearn.maskers.BaseMasker can use the parameter sample_mask for sub-sample masking (#2858 by Hao-Ting Wang).

  • Class NiftiLabelsMasker can now generate HTML reports in the same way as NiftiMasker. The report shows the regions defined by the provided label image and provide summary statistics on each region (name, volume…). If a functional image was provided to fit, the middle image is plotted with the regions overlaid as contours. Finally, if a mask is provided, its contours are shown in green (#2707 by Nicolas Gensollen).

Fixes#

  • Convert references in signal.py, atlas.py, func.py, neurovault.py, and struct.py to use footcite / footbibliography (#2806 by Jeremy Lefort-Besnard).

  • Fix detrending and temporal filtering order for confounders in function clean, so that these operations are applied in the same order as for the signals, i.e., first detrending and then temporal filtering (see #2730) (#2732 by Javier Rasero).

  • Fix number of attributes returned by the nilearn.glm.first_level.FirstLevelModel._get_voxelwise_model_attribute method in the FirstLevelModel. It used to return only the first attribute, and now returns as many attributes as design matrices (#2792 by Raphael Meudec).

  • Plotting functions that show a stack of slices from a 3D image (e.g. plot_stat_map) will now plot the slices in the user specified order, rather than automatically sorting into ascending order (see #1155) (#2831 by Evan Edmond).

  • Fix the axes zoom in function plot_img_on_surf so brain would not be cutoff, and edited function so less white space surrounds brain views and smaller colorbar using gridspec (#2798 by Tom Vanasse).

  • Fix inconsistency in prediction values of sklearn.dummy.DummyClassifier for Decoder (see #2767) (#2826 by Binh Nguyen).

Enhancements#

Changes#

  • Python 3.5 is no longer supported. We recommend upgrading to Python 3.7 (#2869 by Nicolas Gensollen).

  • Support for Nibabel 2.x is now deprecated and will be removed in the 0.9 release. Users with a version of Nibabel < 3.0 will be warned at their first Nilearn import (#2869 by Nicolas Gensollen).

  • Minimum supported versions of packages have been bumped up:

    • Numpy – v1.16

    • SciPy – v1.2

    • Scikit-learn – v0.21

    • Nibabel – v2.5

    • Pandas – v0.24

    (#2869 by Nicolas Gensollen).

  • Function sym_to_vec from nilearn.connectome was deprecated since release 0.4 and has been removed (#2867 by Nicolas Gensollen).

  • Function nilearn.datasets.fetch_nyu_rest was deprecated since release 0.6.2 and has been removed (#2868 by Nicolas Gensollen).

  • Class NiftiMasker replaces attribute sessions with runs and deprecates attribute sessions in 0.9.0. Match the relevant change in function clean (#2858 by Hao-Ting Wang).

0.7.1#

Released March 2021

HIGHLIGHTS#

NEW#

  • New atlas fetcher fetch_atlas_difumo to download Dictionaries of Functional Modes, or “DiFuMo”, that can serve as atlases to extract functional signals with different dimensionalities (64, 128, 256, 512, and 1024). These modes are optimized to represent well raw BOLD timeseries, over a with range of experimental conditions (#2619 by Nicolas Gensollen).

  • Function glm.Contrast.one_minus_pvalue was added to ensure numerical stability of p-value estimation. It computes 1 - p-value using the Cumulative Distribution Function in the same way as function nilearn.glm.Contrast.p_value computes the p-value using the Survival Function. (#2567 by Ana Luisa Pinho).

Fixes#

Enhancements#

0.7.0#

Released November 2020

HIGHLIGHTS#

Warning

Minimum required version of Joblib is now 0.12.

NEW#

  • Nilearn now includes the functionality of Nistats. Here’s a guide to replacing Nistats imports to work in Nilearn.

  • New decoder object nilearn.decoding.Decoder (for classification) and nilearn.decoding.DecoderRegressor (for regression) implement a model selection scheme that averages the best models within a cross validation loop. The resulting average model is the one used as a classifier or a regressor. These two objects also leverage the NiftiMaskers to provide a direct interface with the Nifti files on disk.

  • New FREM object nilearn.decoding.FREMClassifier (for classification) and nilearn.decoding.FREMRegressor (for regression) extend the decoder object pipeline with one fast clustering step at the beginning (yielding an implicit spatial regularization) and aggregates a high number of estimators trained on various splits of the training set. This returns a state-of-the-art decoding pipeline at a low computational cost. These two objects also leverage the NiftiMaskers to provide a direct interface with the Nifti files on disk.

  • Plot events file Use nilearn.plotting.plot_event to visualize events file. The function accepts the BIDS events file read using pandas utilities.

  • Plotting function nilearn.plotting.plot_roi can now plot ROIs in contours with view_type argument.

  • New plotting function nilearn.plotting.plot_carpet generates a “carpet plot” (also known as a “Power plot” or a “grayplot”), for visualizing global patterns in 4D functional data over time.

  • New plotting function nilearn.plotting.plot_img_on_surf generates multiple views of nilearn.plotting.plot_surf_stat_map in a single figure.

  • nilearn.plotting.plot_markers shows network nodes (markers) on a glass brain template and color code them according to provided nodal measure (i.e. connection strength). This function will replace nilearn.plotting.plot_connectome_strength.

  • New plotting function nilearn.plotting.plot_surf_contours plots the contours of regions of interest on the surface, optionally overlaid on top of a statistical map.

  • The position annotation on the plot methods now implements the decimals option to enable annotation of a slice coordinate position with the float.

  • New example in Cortical surface-based searchlight decoding to demo how to do cortical surface-based searchlight decoding with Nilearn.

  • confounds or additional regressors for design matrix can be specified as numpy arrays or pandas DataFrames interchangeably

  • The decomposition estimators will now accept argument per_component with score method to explain the variance for each component.

Fixes#

  • nilearn.maskers.NiftiLabelsMasker no longer ignores its mask_img

  • nilearn.masking.compute_brain_mask has replaced nilearn.masking.compute_gray_matter_mask. Features remained the same but some corrections regarding its description were made in the docstring.

  • the default background (MNI template) in plotting functions now has the correct orientation; before left and right were inverted.

  • first level modelling can deal with regressors having multiple events which share onsets or offsets. Previously, such cases could lead to an erroneous baseline shift.

  • nilearn.mass_univariate.permuted_ols no longer returns transposed t-statistic arrays when no permutations are performed.

  • Fix decomposition estimators returning explained variance score as 0. based on all components i.e., when per_component=False.

  • Fix readme file of the Destrieux 2009 atlas.

Changes#

0.6.2#

Released February 2020

ENHANCEMENTS#

Fixes#

Changes#

  • Function nilearn.datasets.fetch_nyu_rest has been deprecated and will be removed in Nilearn 0.8.0 (#2308 by Joshua Teves).

Contributors#

The following people contributed to this release:

0.6.1#

Released January 2020

ENHANCEMENTS#

  • HTML pages use the user-provided plot title, if any, as their title (#2272 by Jerome Dockes).

Fixes#

  • Fetchers for developmental_fmri and localizer datasets resolve URLs correctly (#2290 by Elizabeth DuPre).

Contributors#

The following people contributed to this release:

0.6.0#

Released December 2019

HIGHLIGHTS#

Warning

Python2 and 3.4 are no longer supported. We recommend upgrading to Python 3.6 minimum. (#2214 by Kshitij Chawla).

Support for Python3.5 will be removed in the 0.7.x release.
Users with a Python 3.5 environment will be warned at their first Nilearn import.

joblib is now a dependency

Minimum supported versions of packages have been bumped up.
- Matplotlib -- v2.0.
- Scikit-learn -- v0.19.
- Scipy -- v0.19.

NEW#

  • New method for NiftiMasker instances for generating reports viewable in a web browser, Jupyter Notebook, or VSCode (#2019 by Elizabeth DuPre).

  • New function get_data to replace the deprecated nibabel method Nifti1Image.get_data. Now use nilearn.image.get_data(img) rather than img.get_data(). This is because Nibabel is removing the get_data method. You may also consider using the Nibabel method nibabel.nifti1.Nifti1Image.get_fdata, which returns the data cast to floating-point. See BIAP8. As a benefit, the get_data function works on niimg-like objects such as filenames (see input_output) (#2172 by Jerome Dockes).

  • New class ReNA implementing parcellation method ReNA: Fast agglomerative clustering based on recursive nearest neighbor grouping. Yields very fast & accurate models, without creation of giant clusters (#1336 by Andrés Hoyos Idrobo).

  • New function nilearn.plotting.plot_connectome_strength to plot the strength of a connectome on a glass brain. Strength is absolute sum of the edges at a node (#2028 by Guillaume Lemaitre).

  • Function resample_img has been optimized to pad rather than resample images in the special case when there is only a translation between two spaces. This is a common case in class NiftiMasker when using the mask_strategy="template" option for brains in MNI space (#2025 by Greg Kiar).

  • New brain development fMRI dataset fetcher datasets.fetch_development_fmri can be used to download movie-watching data in children and adults. A light-weight dataset implemented for teaching and usage in the examples. All the connectivity examples are changed from ADHD to brain development fMRI dataset (#1953 by Kamalakar Reddy Daddy).

ENHANCEMENTS#

CHANGES#

  • Function plot_img now has explicit keyword arguments bg_img, vmin and vmax to control the background image and the bounds of the colormap. These arguments were already accepted in kwargs but not documented before (#2157 by Jerome Dockes).

FIXES#

Lots of other fixes in documentation and examples. More detailed change list follows:

0.6.0rc#

NEW#

Warning

  • Function view_connectome no longer accepts old parameter names. Instead of coords, threshold, cmap, and marker_size, use node_coords, edge_threshold, edge_cmap, and node_size respectively (#2255 by Kshitij Chawla).

  • Function view_markers no longer accepts old parameter names. Instead of coord and color, use marker_coords and marker_color respectively (#2255 by Kshitij Chawla).

  • Support for Python3.5 will be removed in the 0.7.x release. Users with a Python3.5 environment will be warned at their first Nilearn import (#2214 by Kshitij Chawla).

Changes#

  • Add a warning to Parcellations if the generated number of parcels does not match the requested number of parcels (#2240 by Elizabeth DuPre).

  • Class NiftiLabelsMasker now accepts an optional strategy parameter which allows it to change the function used to reduce values within each labelled ROI. Available functions include mean, median, minimum, maximum, standard_deviation and variance. This change is also introduced in function img_to_signals_labels (#2221 by Daniel Gomez).

Fixes#

Contributors#

The following people contributed to this release (in alphabetical order):

0.6.0b0#

Released November 2019

Warning

Python2 and 3.4 are no longer supported. Pip will raise an error in these environments.
Minimum supported version of Python is now 3.5 .
We recommend upgrading to Python 3.6 .

NEW#

  • New function get_data to replace the deprecated nibabel method Nifti1Image.get_data. Now use nilearn.image.get_data(img) rather than img.get_data(). This is because Nibabel is removing the get_data method. You may also consider using the Nibabel method nibabel.nifti1.Nifti1Image.get_fdata, which returns the data cast to floating-point. See BIAP8. As a benefit, the get_data function works on niimg-like objects such as filenames (see input_output) (#2172 by Jerome Dockes).

Changes#

Fixes#

  • Function plot_connectome now correctly displays marker size on ‘l’ and ‘r’ orientations, if an array or a list is passed to the function.

Contributors#

The following people contributed to this release (in alphabetical order):

0.6.0a0#

Released October 2019

NEW#

Warning

Python2 and 3.4 are no longer supported. We recommend upgrading to Python 3.6 minimum.

Minimum supported versions of packages have been bumped up.
- Matplotlib -- v2.0.
- Scikit-learn -- v0.19.
- Scipy -- v0.19.

  • A new method for NiftiMasker instances for generating reports viewable in a web browser, Jupyter Notebook, or VSCode (#2019 by Elizabeth DuPre).

  • joblib is now a dependency (#2090 by Jerome Dockes).

  • New class ReNA implementing parcellation method ReNA: Fast agglomerative clustering based on recursive nearest neighbor grouping. Yields very fast & accurate models, without creation of giant clusters (#1336 by Andrés Hoyos Idrobo).

  • New function nilearn.plotting.plot_connectome_strength to plot the strength of a connectome on a glass brain. Strength is absolute sum of the edges at a node (#2028 by Guillaume Lemaitre).

  • Function resample_img has been optimized to pad rather than resample images in the special case when there is only a translation between two spaces. This is a common case in class NiftiMasker when using the mask_strategy="template" option for brains in MNI space (#2025 by Greg Kiar).

  • New brain development fMRI dataset fetcher fetch_development_fmri can be used to download movie-watching data in children and adults; a light-weight dataset implemented for teaching and usage in the examples.

  • New example in examples/05_advanced/plot_age_group_prediction_cross_val.py to compare methods for classifying subjects into age groups based on functional connectivity. Similar example in examples/03_connectivity/plot_group_level_connectivity.py simplified (#2063 by Jerome Dockes).

  • Merged examples/03_connectivity/plot_adhd_spheres.py and examples/03_connectivity/plot_sphere_based_connectome.py to remove duplication across examples. The improved examples/03_connectivity/plot_sphere_based_connectome.py contains concepts previously reviewed in both examples (#2013 by Jake Vogel).

  • Merged examples/03_connectivity/plot_compare_decomposition.py and examples/03_connectivity/plot_canica_analysis.py into an improved examples/03_connectivity/plot_compare_decomposition.py (#2013 by Jake Vogel).

  • The Localizer dataset now follows the BIDS organization.

Changes#

  • All the connectivity examples are changed from ADHD to brain development fMRI dataset.

  • Examples plot_decoding_tutorial, plot_haxby_decoder, plot_haxby_different_estimators, plot_haxby_full_analysis, plot_oasis_vbm now use Decoder and DecoderRegressor instead of sklearn SVC and SVR (#2000 by Binh Nguyen).

  • Functions view_img_on_surf, view_surf and view_connectome can display a title, and allow disabling the colorbar, and setting its height and the fontsize of its ticklabels (#1951 by Jerome Dockes).

  • Rework of the standardize-options of function clean and the various Maskers in nilearn.maskers. You can now set standardize to zscore or psc. psc stands for Percent Signal Change, which can be a meaningful metric for BOLD (#1952 by Gilles de Hollander).

  • Function plot_img now has explicit keyword arguments bg_img, vmin and vmax to control the background image and the bounds of the colormap. These arguments were already accepted in kwargs but not documented before (#2157 by Jerome Dockes).

  • Function view_connectome now converts NaNs in the adjacency matrix to 0 (#2166 by Jerome Dockes).

  • Removed the plotting connectomes example which used the Seitzman atlas from examples/03_connectivity/plot_sphere_based_connectome.py. The atlas data is unsuitable for the method & the example is redundant (#2177 by Kshitij Chawla).

Fixes#

Contributors#

The following people contributed to this release (in alphabetical order):

0.5.2#

Released April 2019

NEW#

Warning

This is the last release supporting Python2 and 3.4. The lowest Python version supported is now Python 3.5. We recommend switching to Python 3.6.

Fixes#

  • Plotting .mgz files in MNE broke in 0.5.1 and has been fixed.

Contributors#

The following people contributed to this release:

0.5.1#

Released April 2019

NEW#

  • Support for Python2 & Python3.4 will be removed in the next release. We recommend Python 3.6 and up. Users with a Python2 or Python3.4 environment will be warned at their first Nilearn import.

  • Calculate image data dtype from header information.

  • New display mode tiled which allows 2x2 plot arrangement when plotting three cuts (see Plotting brain images).

  • Class NiftiLabelsMasker now consumes less memory when extracting the signal from a 3D/4D image. This is especially noteworthy when extracting signals from large 4D images.

  • New function fetch_atlas_schaefer_2018.

  • New function fetch_coords_seitzman_2018.

Changes#

  • Lighting used for interactive surface plots changed; plots may look a bit different.

  • Function view_connectome default colormap is bwr, consistent with function plot_connectome.

  • Function view_connectome parameter names are consistent with function plot_connectome:

    • coords is now node_coord.

    • marker_size is now node_size.

    • cmap is now edge_cmap.

    • threshold is now edge_threshold.

  • Functions view_markers and view_connectome can accept different marker sizes for each node / marker.

  • Function plotting.view_markers default marker color is now red, consistent with add_markers().

  • Function plotting.view_markers parameter names are consistent with add_markers():

    • coords is now marker_coords.

    • colors is now marker_color.

  • Function view_img_on_surf now accepts a symmetric_cmap argument to control whether the colormap is centered around 0 and a vmin argument.

  • Users can now control the size and fontsize of colorbars in interactive surface and connectome plots, or disable the colorbar.

Fixes#

  • Example plot_seed_to_voxel_correlation now really saves z-transformed maps.

  • Function connected_regions and class RegionExtractor now correctly use the provided mask_img.

  • Function load_niimg no longer drops header if dtype is changed.

  • Class NiftiSpheresMasker no longer silently ignores voxels if no mask_img is specified.

  • Interactive brainsprites generated from view_img are correctly rendered in Jupyter Book.

Known Issues#

  • On Python2, functions view_connectome and function view_markers do not show parameters names in function signature when using help() and similar features. Please refer to their docstrings for this information.

  • Plotting .mgz files in MNE is broken.

Contributors#

The following people contributed to this release:

0.5.0#

Released November 2018

NEW#

Note

Function view_img was nilearn.plotting.view_stat_map in alpha and beta releases.

Minimum supported versions of packages have been bumped up.

  • scikit-learn -- v0.18.

  • scipy -- v0.17.

  • pandas -- v0.18.

  • numpy -- v1.11

  • matplotlib -- v1.5.1

Nilearn Python2 support is being removed in the near future.

Users with a Python2 environment will be warned at their first Nilearn import.

Additional dataset downloaders for examples and tutorials.

ENHANCEMENTS#

  • Function clean_img now accepts a mask to restrict the cleaning of the image, reducing memory load and computation time.

  • NiftiMaskers now have a dtype parameter, by default keeping the same data type as the input data.

  • Displays by plotting functions can now add a scale bar (see Plotting brain images).

  • Lots of other fixes in documentation and examples.

  • A cleaner layout and improved navigation for the website, with a better introduction.

  • Dataset fetchers are now more reliable, less verbose.

  • The fit method now accepts 4D niimgs.

  • Anaconda link in the installation documentation updated.

  • Scipy is listed as a dependency for Nilearn installation.

Changes#

  • Default value of t_r in functions clean and clean_img is None and cannot be None if low_pass or high_pass is specified.

Lots of changes and improvements. Detailed change list for each release follows.

0.5.0 rc#

Highlights#

  • Function view_img (formerly nilearn.plotting.view_stat_map in Nilearn 0.5.0 pre-release versions) generates significantly smaller notebooks and HTML pages while getting a more consistent look and feel with Nilearn’s plotting functions. Huge shout out to Pierre Bellec (pbellec) for making a great feature awesome and for sportingly accommodating all our feedback.

  • Function clean_img now accepts a mask to restrict the cleaning of the image. This approach can help to reduce the memory load and computation time. Big thanks to Michael Notter (miykael).

Enhancements#

  • Function view_img is now using the brainsprite.js library, which results in much smaller notebooks or html pages. The interactive viewer also looks more similar to the plots generated by function plot_stat_map, and most parameters found in plot_stat_map are now supported in view_img.

  • Function clean_img now accepts a mask to restrict the cleaning of the image. This approach can help to reduce the memory load and computation time.

  • Method fit raises a meaningful error in regression tasks if the target Y contains all 1s.

Changes#

  • Default value of t_r in functions clean and clean_img is changed from 2.5 to None. If low_pass or high_pass is specified, then t_r needs to be specified as well otherwise it will raise an error.

  • Order of filters in functions clean and clean_img has changed to detrend, low- and high-pass filter, remove confounds and standardize. To ensure orthogonality between temporal filter and confound removal, an additional temporal filter will be applied on the confounds before removing them. This is according to Lindquist et al. (2018).

  • Function clean_img now accepts a mask to restrict the cleaning of the image. This approach can help to reduce the memory load and computation time.

  • Function view_img is now using the brainsprite.js library, which results in much smaller notebooks or html pages. The interactive viewer also looks more similar to the plots generated by plot_stat_map, and most parameters found in plot_stat_map are now supported in view_img.

Contributors#

The following people contributed to this release:

0.5.0 beta#

Released October 2018

Highlights#

Nilearn Python2 support is being removed in the near future. Users with a Python2 environment will be warned at their first Nilearn import.

Enhancements#

  • Displays created by plotting functions can now add a scale bar to indicate the size in mm or cm (see Plotting brain images) (by Oscar Esteban).

  • Colorbars in plotting functions now have a middle gray background suitable for use with custom colormaps with a non-unity alpha channel (by Eric Larson).

Loads of fixes and quality of life improvements

  • A cleaner layout and improved navigation for the website, with a better introduction.

  • Less warnings and verbosity while using certain functions and during dataset downloads.

  • Improved backend for the dataset fetchers means more reliable dataset downloads.

  • Some datasets, such as the ICBM, are now compressed to take up less disk space.

Fixes#

  • Method decoding.SearchLight.fit now accepts 4D niimgs (by Dan Gale).

  • plotting.view_markers.open_in_browser() in js_plotting_utils fixed.

  • Brainomics dataset has been replaced in several examples.

  • Lots of other fixes in documentation and examples.

Changes#

Contributors#

The following people contributed to this release:

0.5.0 alpha#

Released August 2018

This is an alpha release: to download it, you need to explicitly ask for the version number:

pip install nilearn==0.5.0a0

Highlights#

  • Minimum supported versions of packages have been bumped up.

    • scikit-learn -- v0.18

    • scipy -- v0.17

    • pandas -- v0.18

    • numpy -- v1.11

    • matplotlib -- v1.5.1

  • New interactive plotting functions, eg for use in a notebook.

Enhancements#

Changes#

  • Function nilearn.datasets.fetch_surf_fsaverage5 is deprecated and will be removed in a future release. Use function fetch_surf_fsaverage, with the parameter mesh="fsaverage5" (the default) instead.

  • fsaverage5 surface data files are now shipped directly with Nilearn (see #1705 for discussion).

  • sklearn.cross_validation and sklearn.grid_search have been replaced by sklearn.model_selection in all the examples.

  • Colorbars in plotting functions now have a middle gray background suitable for use with custom colormaps with a non-unity alpha channel.

Contributors#

The following people contributed to this release:

0.4.2#

Released June 2018

Few important bugs fix release for OHBM conference.

Changes#

  • Default colormaps for surface plotting functions have changed to be more consistent with slice plotting. plot_surf_stat_map now uses cold_hot, as plot_stat_map does, and plot_surf_roi now uses gist_ncar, as plot_roi does.

  • Improve 3D surface plotting: lock the aspect ratio of the plots and reduce the whitespace around the plots.

Fixes#

  • Fix bug with input repetition time (TR) which had no effect in signal cleaning (fixed by Pradeep Reddy Raamana).

  • Fix issues with signal extraction on list of 3D images in Parcellations.

  • Fix issues with raising AttributeError rather than HTTPError in datasets fetching utilities (by Jerome Dockes).

  • Fix issues in datasets testing function uncompression of files (by Pierre Glaser).

0.4.1#

Released March 2018

This bug fix release is focused on few bug fixes and minor developments.

Enhancements#

Note

This feature is usable only if SciPy version is >= 1.0.0.

Changes#

  • Using output attribute components_ which is an extracted components in classes CanICA and DictLearning is deprecated and will be removed in next two releases. Use components_img_ instead (#1536 by Kamalakar Reddy Daddy).

Bug fixes#

  • Fix issues using function plot_connectome when string is passed in node_color with display modes left and right hemispheric cuts in the glass brain.

  • Fix bug while plotting only coordinates using add_markers on glass brain (#1595 by Kamalakar Reddy Daddy).

  • Fix issues with estimators in decomposition module when input images are given in glob patterns.

  • Fix bug loading Nifti2Image.

  • Fix bug while adjusting contrast of the background template while using function plot_prob_atlas.

  • Fix colormap bug with recent matplotlib 2.2.0.

0.4.0#

Released November 2017

Highlights#

  • New function vol_to_surf to project volume data to the surface.

  • New function plot_matrix to display matrices, eg connectomes.

Enhancements#

  • New function vol_to_surf to project a 3d or 4d brain volume on the cortical surface.

  • New function plot_matrix to display connectome matrices.

  • Expose function coord_transform for end users. Useful to transform coordinates (x, y, z) from one image space to another space.

  • Function resample_img now takes a linear resampling option (implemented by Joe Necus).

  • Function fetch_atlas_talairach to fetch the Talairach atlas (#1523 by Jerome Dockes).

  • Enhancing new surface plotting functions, added new parameters axes and figure to accept user-specified instances in plot_surf, plot_surf_stat_map, and plot_surf_roi.

  • Class SearchLight has new parameter groups to do LeaveOneGroupOut type cv with new scikit-learn module model selection.

  • Enhancing the glass brain plotting in back view ‘y’ direction.

  • New parameter resampling_interpolation is added in most used plotting functions to have user control for faster visualizations.

  • Upgraded to Sphinx-Gallery 0.1.11.

Fixes#

  • Dimming factor applied to background image in plotting functions with dim parameter will no longer accepts as string (‘-1’). An error will be raised.

  • Fixed issues with matplotlib 2.1.0.

  • Fixed issues with SciPy 1.0.0.

Changes#

  • Backward incompatible change: Function find_xyz_cut_coords now takes a mask_img argument which is a niimg, rather than a mask argument, which used to be a numpy array.

  • The minimum required version for scipy is now 0.14.

  • Dropped support for Nibabel older than 2.0.2.

  • Function smooth_img no longer accepts smoothing parameter FWHM as 0. Behavior is changed in according to the issues with recent SciPy version 1.0.0.

  • dim factor range is slightly increased to -2 to 2 from -1 to 1. Range exceeding -1 meaning more increase in contrast should be cautiously set.

  • New anterior and posterior view added to the plot_surf family views.

  • Using argument anat_img for placing background image in function plot_prob_atlas is deprecated. Use argument bg_img instead.

  • The examples now use pandas for the behavioral information.

Contributors#

The following people contributed to this release:

0.3.1#

Released June 2017

This is a minor release for BrainHack.

Highlights#

  • Dropped support for scikit-learn older than 0.14.1 Minimum supported version is now 0.15.

Changes#

  • The function sym_to_vec is deprecated and will be removed in release 0.4. Use function sym_matrix_to_vec instead.

  • Added argument smoothing_fwhm to RegionExtractor to control smoothing according to the resolution of atlas images.

Fixes#

  • The helper function largest_connected_component should now work with inputs of non-native data dtypes.

  • Fix plotting issues when non-finite values are present in background anatomical image.

  • A workaround to handle non-native endianness in Nifti1Image passed to resampling the image.

Enhancements#

  • New functions fetch_neurovault and fetch_neurovault_ids help you download statistical maps from the Neurovault platform.

  • New function vec_to_sym_matrix reshapes vectors to symmetric matrices. It acts as the reverse of function sym_matrix_to_vec.

  • Add an option allowing to vectorize connectivity matrices returned by the transform method of class ConnectivityMeasure.

  • Class ConnectivityMeasure now exposes an inverse_transform method, useful for going back from vectorized connectivity coefficients to connectivity matrices. Also, it allows to recover the covariance matrices for the “tangent” kind.

  • Reworking and renaming of connectivity measures example. Renamed from plot_connectivity_measures to plot_group_level_connectivity.

  • Tighter bounding boxes when using add_contours for plotting.

  • Function largest_connected_component_img to directly extract the largest connected component from Nifti1Image.

  • Improvements in plotting, decoding and functional connectivity examples.

0.3.0#

Released April 2017

In addition, more details of this release are listed below. Please checkout in 0.3.0 beta release section for minimum version support of dependencies, latest updates, highlights, changelog and enhancements.

Changes#

  • Function find_cut_slices now supports to accept Nifti1Image as an input for argument img.

  • Helper functions _get_mask_volume and _adjust_screening_percentile are now moved to param_validation file in utilities module to be used in common with Decoder object.

Fixes#

  • Fix bug uncompressing tar files with datasets fetcher.

  • Fixed bunch of CircleCI documentation build failures.

  • Fixed deprecations set_axis_bgcolor related to matplotlib in plotting functions.

  • Fixed bug related to not accepting a list of arrays as an input to unmask, in nilearn.masking module.

Enhancements#

  • ANOVA SVM example on Haxby datasets plot_haxby_anova_svm in Decoding section now uses SelectPercentile to select voxels rather than SelectKBest.

  • New function fast_svd implementation in base decomposition module to automatically switch between randomized and lapack SVD (heuristic of scikit-learn).

0.3.0 beta#

Released February 2017

To install the beta version, use:

pip install --upgrade --pre nilearn

Highlights#

  • Simple surface plotting.

  • A function to break a parcellation into its connected components.

  • Dropped support for scikit-learn older than 0.14.1 Minimum supported version is now 0.14.1.

  • Dropped support for Python 2.6

  • Minimum required version of NiBabel is now 1.2.0, to support loading annotated data with freesurfer.

Changes#

  • A helper function _safe_get_data as a nilearn utility now safely removes NaN values in the images with argument ensure_finite=True.

  • Functions cov_to_corr and prec_to_partial can now be used.

Fixes#

  • Fix colormap issue with colorbar=True when using qualitative colormaps. Fixed in according with changes of matplotlib 2.0 fixes.

  • Fix plotting functions to work with NaN values in the images.

  • Fix bug related get dtype of the images with nibabel get_data().

  • Fix bug in function clean_img.

Enhancements#

  • New function connected_label_regions to extract the connected components represented as same label to regions apart with each region labelled as unique label.

  • New plotting modules for surface plotting visualization. Matplotlib with version higher 1.3.1 is required for plotting surface data using these functions.

  • Function plot_surf can be used for plotting surfaces mesh data with optional background.

  • Function plot_surf_stat_map can be used for plotting statistical maps on a brain surface with optional background.

  • Function plot_surf_roi can be used for plotting statistical maps rois onto brain surface.

  • Function nilearn.datasets.fetch_surf_fsaverage5 can be used for surface data object to be as background map for the above plotting functions.

  • New function fetch_atlas_surf_destrieux can give you Destrieux et. al 2010 cortical atlas in fsaverage5 surface space.

  • New function fetch_surf_nki_enhanced gives you resting state data preprocessed and projected to fsaverage5 surface space.

  • Two good examples in plotting gallery shows how to fetch atlas and NKI data and used for plotting on brain surface.

  • New function load_surf_mesh in surf_plotting module for loading surface mesh data into two arrays, containing (x, y, z) coordinates for mesh vertices and indices of mesh faces.

  • New function load_surf_data in surf_plotting module for loading data of numpy array to represented on a surface mesh.

  • Add fetcher for Allen et al. 2011 RSN atlas in fetch_atlas_allen_2011.

  • Function nilearn.datasets.fetch_cobre is now updated to new light release of COBRE data (schizophrenia).

  • A new example to show how to extract regions on labels image in example section manipulating images.

  • coveralls is replaced with codecov.

  • Upgraded to Sphinx version 0.1.7.

  • Extensive plotting example shows how to use contours and filled contours on glass brain.

0.2.6#

Released September 2016

This release enhances usage of several functions by fine tuning their parameters. It allows to select which Haxby subject to fetch. It also refactors documentation to make it easier to understand. Sphinx-gallery has been updated and nilearn is ready for new nibabel 2.1 version. Several bugs related to masks in Searchlight and ABIDE fetching have been resolved.

Fixes#

  • Change default dtype in function concat_imgs to be the original type of the data (see #1238).

  • Fix SearchLight that did not run without process_mask or with one voxel mask.

  • Fix flipping of left hemisphere when plotting glass brain.

  • Fix bug when downloading ABIDE timeseries.

Enhancements#

  • Sphinx-gallery updated to version 0.1.3.

  • Refactoring of examples and documentation.

  • Better ordering of regions in function fetch_coords_dosenbach_2010.

  • Remove outdated power atlas example.

Changes#

  • The parameter n_subjects is deprecated and will be removed in future release. Use subjects instead in function fetch_haxby.

  • The function fetch_haxby will now fetch the data accepting input given in subjects as a list than integer.

  • Replace get_affine by affine with recent versions of nibabel.

0.2.5.1#

Released August 2016

This is a bugfix release. The new minimum required version of scikit-learn is 0.14.1.

Changes#

  • Default option for dim argument in plotting functions which uses MNI template as a background image is now changed to ‘auto’ mode. Meaning that an automatic contrast setting on background image is applied by default.

  • Scikit-learn validation tools have been imported and are now used to check consistency of input data, in SpaceNet for example.

New#

  • Add an option to select only off-diagonal elements in function sym_to_vec. Also, the scaling of matrices is modified: we divide the diagonal by sqrt(2) instead of multiplying the off-diagonal elements.

  • Connectivity examples rely on ConnectivityMeasure.

Fixes#

  • Scipy 0.18 introduces a bug in a corner-case of resampling. Nilearn 0.2.5 can give wrong results with scipy 0.18, but this is fixed in 0.2.6.

  • Broken links and references fixed in docs.

0.2.5#

Released June 2016

The 0.2.5 release includes plotting for connectomes and glass brain with hemisphere-specific projection, as well as more didactic examples and improved documentation.

New#

Contributors#

Contributors (from git shortlog -ns 0.2.4..0.2.5):

0.2.4#

Released April 2016

The 0.2.4 is a small release focused on documentation for teaching.

New#

  • The path given to the memory argument of object now have their “~” expanded to the homedir.

  • Display object created by plotting now uniformly expose an add_markers method.

  • Function plot_connectome now plots connectome with colorbars.

  • New function resample_to_img to resample one image on another one (just resampling / interpolation, no coregistration).

Changes#

  • Atlas fetcher fetch_atlas_msdl now returns directly labels of the regions in output variable labels and its coordinates in output variable region_coords and its type of network in networks.

  • The output variable name regions is now changed to maps in AAL atlas fetcher fetch_atlas_aal.

  • AAL atlas now returns directly its labels in variable labels and its index values in variable indices.

0.2.3#

Released February 2016

Changelog#

The 0.2.3 is a small feature release for BrainHack 2016.

New features#

  • Mathematical formulas based on numpy functions can be applied on an image or a list of images using function math_img.

  • Downloader for COBRE datasets of 146 rest fMRI subjects with function nilearn.datasets.fetch_cobre.

  • Downloader for Dosenbach atlas fetch_coords_dosenbach_2010.

  • Fetcher for multiscale functional brain parcellations (BASC) fetch_atlas_basc_multiscale_2015.

Bug fixes#

  • Better dimming on white background for plotting.

0.2.2#

Released February 2016

The 0.2.2 is a bugfix + dependency update release (for sphinx-gallery). It aims at preparing a renewal of the tutorials.

New#

  • Fetcher for Megatrawl Netmats dataset.

Enhancements#

  • Flake8 is now run on pull requests.

  • Reworking of the documentation organization.

  • Sphinx-gallery updated to version 0.1.1.

  • The default n_subjects=None in function fetch_adhd is now changed to n_subjects=30.

Fixes#

  • Fix symmetric_split behavior in function fetch_atlas_harvard_oxford.

  • Fix casting errors when providing integer data to function high_variance_confounds.

  • Fix matplotlib 1.5.0 compatibility in function plot_prob_atlas.

  • Fix matplotlib backend choice on Mac OS X.

  • Function find_xyz_cut_coords raises a meaningful error when 4D data is provided instead of 3D.

  • Class NiftiSpheresMasker handles radius smaller than the size of a voxel.

  • Class RegionExtractor handles data containing Nans.

  • Confound regression does not force systematically the normalization of the confounds.

  • Force time series normalization in ConnectivityMeasure and check dimensionality of the input.

  • Function nilearn._utils.numpy_conversions.csv_to_array could consider valid CSV files as invalid.

Changes#

  • Deprecated dataset downloading function have been removed.

  • Download progression message refreshing rate has been lowered to sparsify CircleCI logs.

Contributors#

Contributors (from git shortlog -ns 0.2.1..0.2.2):

0.2.1#

Released December 2015

Changelog#

Small bugfix for more flexible input types (targetter in particular at making code easier in nistats).

0.2.0#

Released December 2015

Changelog#

Warning

The new minimum required version of scikit-learn is 0.13.

New features#

Enhancements#

  • Making website a bit elaborated & modernise by using sphinx-gallery.

  • Documentation enhancement by integrating sphinx-gallery notebook style examples.

  • Documentation about class maskers.NiftiSpheresMasker.

Bug fixes#

  • Fixed bug to control the behaviour when cut_coords=0 in function plot_stat_map in nilearn.plotting (See #784).

  • Fixed bug in function copy_img occurred while caching the Nifti images (See #793).

  • Fixed bug causing an IndexError in fast_abs_percentile (See #875).

API changes summary#

Contributors#

Contributors (from git shortlog -ns 0.1.4..0.2.0):

0.1.4#

Released July 2015

Highlights#

  • New class nilearn.maskers.NiftiSpheresMasker which extracts signals from balls specified by their coordinates.

  • Obey Debian packaging rules.

  • Add the Destrieux 2009 and Power 2011 atlas.

  • Better caching in maskers.

Contributors (from git shortlog -ns 0.1.3..0.1.4):

0.1.3#

Released May 2015

Changelog#

The 0.1.3 release is a bugfix release that fixes a lot of minor bugs. It also includes a full rewamp of the documentation, and support for Python 3.

Warning

Minimum version of supported packages are now:

  • numpy -- 1.6.1

  • scipy -- 0.9.0

  • scikit-learn -- 0.12.1

  • Matplotlib -- 1.1.1 (optional)

Fixes#

  • Dealing with NaNs in function plot_connectome.

  • Fix extreme values in colorbar were sometimes brok.

  • Fix confounds removal with single confounds.

  • Fix frequency filtering.

  • Keep header information in images.

  • add_overlay finds vmin and vmax automatically.

  • Function plot_connectome now supports vmin and vmax.

  • Detrending 3D images no longer puts them to zero.

Contributors (from git shortlog -ns 0.1.2..0.1.3):

0.1.2#

Released March 2015

Changelog#

The 0.1.2 release is a bugfix release, specifically to fix the NiftiMapsMasker.

0.1.1#

Released February 2015

Changelog#

The main change compared to 0.1.0 is the addition of connectome plotting via the function plot_connectome. See the plotting documentation for more details.

Contributors (from git shortlog -ns 0.1..0.1.1):

0.1.0#

Released February 2015

Changelog#

First release of nilearn.

Contributors (from git shortlog -ns 0.1):