What’s new

0.11.0

Released November 2024

HIGHLIGHTS

Warning

Support for Python 3.8 has been dropped.

We recommend upgrading to Python 3.11 or above.

This version is the first one to support Python 3.13.

Minimum supported versions of the following packages have been bumped up:

- numpy – 1.22.4

- nibabel – 5.2.0

- scikit-learn – 1.4.0

- joblib – 1.2.0

- pandas – 2.2.0

Surface API

• This version includes a new “surface” API that allow to represent surface meshes and data.

• PolyMesh (and PolyData) can be used to instantiate mesh (and respectively data) objects with both hemisphere.

• SurfaceImage are objects that hold meshes and data for both hemispheres.

• SurfaceImage, PolyMesh, PolyData allow you to load and save mesh or data from one hemisphere from or to a Gifti file. SurfaceImage can also be instantiated directly with a nifti image and a mesh to project it on.

• Surface plotting functions have been adapted to work with SurfaceImage object.

• To facilitate extracting data from those SurfaceImage objects, this new release also introduces SurfaceMasker and SurfaceLabelsMasker as counterparts to the volumetric NiftiMasker and NiftiLabelsMasker.

• Several classes will already accept SurfaceImage and SurfaceMasker as inputs: Decoder, DecoderRegressor, FREMClassifier, FREMRegressor, FirstLevelModel, SecondLevelModel. Moreover first_level_from_bids will be able to to build FirstLevelModel with the fsaverage5 files generated by fmriprep to directly analysis with surface data.

Code examples

To learn more about these new features see our new examples:

• Working with Surface images

• A short demo of the surface images & maskers

We have also updated several examples to make use of it:

• Loading and plotting of a cortical surface atlas

• Making a surface plot of a 3D statistical map

• Seed-based connectivity on the surface

• Cortical surface-based searchlight decoding

• Example of surface-based first-level analysis

• Surface-based dataset first and second level analysis of a dataset

Fixes

• Code Add a new attribute _region_id_name to NiftiLabelsMasker which is used to fix the issue with creating region_names_ attribute (#4360 by Mohammad Torabi).

• Code binarize_img explicitly cast images to int8 to avoid warnings about int64 when working with float64 images (#4498 by Patrick Sadil).

• Code Make load_confounds return None for confounds when provided with an empty cleaning strategy (#4570 by Micha Burkhardt).

• Code Fix previous Glover HRF implementation to fit the original paper (Glover, 1999) (#4452 by Kun CHEN).

• Code Allow single 4D nifti as input to fit for SecondLevelModel (#4806 by Rémi Gau).

• Code first_level_from_bids will look for images in MNI152NLin2009cAsym space if no space is provided (#4507 by Rémi Gau).

• Code Fix bug that would lead compute_contrast to return 4D images even for one dimensional contrasts (#4413 by Bertrand Thirion and Rémi Gau).

• Code first_level_from_bids will now return subjects in order (#4582 by Tharun K).

• Maint Fix several PTH errors flagged by ruff (#4620 by Prakhar Jain , and #4607, #4612, #4590, #4618, #4860 by Hande Gözükan).

• Maint Fix failing test in test_nilearn_standardize on MacOS 14 by adding trend in simulated data (#4411 by Hao-Ting Wang).

• Plotting Make sure that radiological view is applied when requested and not only when figures are annotated (#4556 by Rémi Gau).

Enhancements

• Code Move SurfaceImage and associated classes from experimental to surface (#4723 by Rémi Gau).

• Code Move SurfaceMasker and SurfaceLabelsMasker from experimental to SurfaceMasker and to SurfaceLabelsMasker (#4692 and #4714 by Rémi Gau).

• Code load_nki that returns the NKI dataset as a list of SurfaceImage instances, load_fsaverage that returns fsaverage meshes as a dict of PolyMesh instances, and load_fsaverage_data that returns fsaverage data (thickness, curvature…) as SurfaceImage instances (#4693 by Rémi Gau based on original work by Jerome Dockes).

• Code Improve input/output for SurfaceImage by loading meshes from files on disk, loading data from files or Nifti object, and saving meshes to file (#4446, #4593 by Rémi Gau and Jerome Dockes).

• Code Allow list of SurfaceImage as input to SurfaceMasker fit and transform methods (#4719 by Rémi Gau).

• Code Allow Decoder and DecoderRegressor to work with surface objects (#4205 by Yasmin Mzayek and Rémi Gau).

• Code Allow FREMClassifier and FREMRegressor to work with surface objects (#4577 by Yasmin Mzayek and Rémi Gau).

• Code Improve first_level_from_bids to look for and load fsaverage5 data to easily run GLM on surface data (#4507 by Rémi Gau).

• Code Improve FirstLevelModel and SecondLevelModel to accept SurfaceMasker and to fit directly SurfaceImage (#4126, #4715 by Rémi Gau).

• Code Improved SearchLight with NIfTI Support, Mask Handling, and Reusable Transform Method (#4652 by Prakhar Jain).

• Code Add footer to masker reports (#4307 by Rémi Gau).

• Doc Add an option in fetch_atlas_aal to fetch the latest AAL version, 3v2 (#4554 by Jeremy Lefort-Besnard and Rémi Gau).

• Doc Add example showing how to compute hemisphere-wise connectivity for Yeo 17 networks (#4585 by Victoria Shevchenko).

• Doc Add example to demonstrate the use of the new copy_header_from parameter in math_img (#4392 by Himanshu Aggarwal).

• Doc Add example to provide a clear understanding of the Decoder object by demonstrating underlying steps via a Scikit-Learn pipeline. (#4437 by Himanshu Aggarwal).

• Doc Adapt examples showing how to plot events and design matrices to show how to use parametric modulation. Also implement modulation of events in plot_event (#4436 by Rémi Gau).

• Plotting Improve plotting contours for PlotlySurfaceFigure objects by adding add_contours method that accepts arguments to adjust line aesthetics (#3949 by Patrick Sadil).

• Plotting Add a new function plot_design_matrix_correlation to plot the correlation between regressors of a GLM design matrix (#4467 by Rémi Gau).

• Plotting Add option to resize output image width width_view in view_img (#4416 by Alexandre Sayal).

• Plotting Surface plotting functions view_surf, plot_surf, plot_surf_roi, plot_surf_contours and plot_surf_stat_map can accept SurfaceImage as inputs making their surf_mesh parameter optional (#4688 by Rémi Gau).

Changes

• API Remove the unused argument url from fetch_localizer_contrasts, fetch_localizer_calculation_task and fetch_localizer_button_task (#4273 by Rémi Gau).

• API Remove the unused argument rank from the constructor of LikelihoodModelResults (#4273 by Rémi Gau).

• API Remove the unused arguments upper_cutoff and exclude_zeros for compute_multi_background_mask (#4273 by Rémi Gau).

• API The default for force_resample in resample_img and resample_to_img will be set to True from Nilearn 0.13.0. (#4412 by Rémi Gau and Anand Joshi)

• API Allow users to control copying header to the output in image functions and add future warning to copy headers by default in release 0.13.0 onwards (#4397 by Himanshu Aggarwal).

• Code Warn the user when all volumes would be scrubbed when loading fmriprep confounds as this would lead to an empty sample_mask (#4558 by Victoria Shevchenko).

• Code Throw error if sample_mask is empty when scrubbing an fMRI time series (#4558 by Victoria Shevchenko).

• Code Implement argument sample_mask for transform_imgs (#4273 by Rémi Gau).

• Code Throw error in first_level_from_bids if unknown kwargs are passed (#4414 by Michelle Wang).

• Code Improve logging by relying only on the Nilearn logger and adding optional support for rich printing if rich is installed (#4469 and #4544 by Rémi Gau).

• Code Parcellations returned by Parcellations will now be of type np.int32 to avoid unnecessary warnings (#4555 by Rémi Gau).

• Deprecation The parameter tr for Repetition time will be replaced by t_r in the “HRF” functions in version 0.13.0. The affected functions are glover_dispersion_derivative, glover_hrf, glover_time_derivative, spm_dispersion_derivative, spm_hrf, spm_time_derivative (#4470 by Rémi Gau).

• Deprecation The parameter ax will be replaced by axes in plot_contrast_matrix and plot_design_matrix in release 0.13.0. (#4476 by Mudassir Chapra)

• Doc Add missing default values to docstrings (#4656, #4659, #4660 by Anupriya Kumari).

• Doc Refactor design matrix and contrast formula for the two-sample T-test example in Second-level fMRI model: two-sample test, unpaired and paired (#4407 by Yichun Huang).

• Maint Extend coverage for data generating utility functions (#4465 by Sin Kim).

• Maint Use ruff as formatter and linter instead of black, isort, flake8… (#4574 by Rémi Gau).

• Maint Reorder condition in internal call of resample_img to skip checking of array values if interpolation is nearest (#4571 by Jason Kai).

• Maint Remove redundant sorting of np.unique(data) in internal call of resample_img when checking array values (#4571 by Jason Kai).

• Maint Replace pytest.warns(DeprecationWarning) with pytest.deprecated_call() in tests (#4637 by Victoria Shevchenko).

• Maint Refactor nilearn.plotting.displays._projectors.add_graph to reduce its maxixmum length (#4635 by Anupriya Kumari).

0.10.4

Released April 2024

HIGHLIGHTS

• Code Use the appropriate HTML templates for nilearn.maskers.MultiNiftiMapsMasker and nilearn.maskers.MultiNiftiLabelsMasker reports that would lead to empty reports for MultiNiftiMapsMasker (#4310 by Rémi Gau).

• Code Fix color bar handling with color map with only 1 level (#4255 by Rémi Gau).

• Code Improve colorbar size and labels in mosaic display (#4284 by Rémi Gau).

• Code Remove unused **kwargs from nilearn.plotting.view_img and nilearn.plotting.plot_surf (#4270 by Rémi Gau).

Fixes

• Code Fix plotting of carpet plot due to a change in the coming version of matplotlib (3.9.0) (#4279 by Rémi Gau).

• Code Fix errant warning when using stat_type in nilearn.glm.compute_contrast (#4257 by Eric Larson).

• Code Fix when thresholding is applied to images by GLM reports (#4258 by Rémi Gau).

• Code Use the appropriate HTML templates for nilearn.maskers.MultiNiftiMapsMasker and nilearn.maskers.MultiNiftiLabelsMasker reports that would lead to empty reports for MultiNiftiMapsMasker (#4310 by Rémi Gau).

• Code Make masker report tables horizontally scrollable (#4308 by Rémi Gau).

• Code Masker reports tables do not overlap with report image (#4308 by Rémi Gau).

• Code Fix color bar handling with color map with only 1 level (#4255 by Rémi Gau).

• Code Ensure that region_names_ can be generated by nilearn.maskers.NiftiSpheresMasker.transform_single_imgs for deterministic atlases that use floats or non-consecutive values as region_ids whether they include background in their labels or not (#4274 by Rémi Gau).

• Code Ensure that nilearn.interfaces.bids.save_glm_to_bids serializes numpy arrays to list used as GLM parameters before saving them to JSON (#4325 by Rémi Gau).

• Code Check that the view parameter in surface plotting functions is a pair of int or float when it is not a string (#4297 by Rémi Gau).

• Code Fix positions of the markers on the images on the sphere masker reports (#4285 by Rémi Gau).

• Code Fix cut position in nifti maps maskers to match displayed map maximum (#4304 by Rémi Gau).

• Code Make sure that nilearn.maskers.NiftiSpheresMasker reports displays properly when it contains only 1 sphere (#4269 by Rémi Gau).

• Code Miscellaneous fixes in GLM reports (only display FIR delay if FIR is used, display color bar “Z score” legend…) (#4266 by Rémi Gau).

• Doc Fix minor typos in documentation (glossary and connectivity/parcellating) (#4343 by Florent Pollet).

• Doc Update minor information on the Code of Conduct page (#4318 and #4320 by Himanshu Aggarwal).

Enhancements

• API Add an avg_method parameter to nilearn.plotting.plot_surf_stat_map (#4298 by Rémi Gau).

• Doc Advertise nilearn’s in built globbing capability in an example (#4334 by Himanshu Aggarwal).

Changes

• Code Throw warnings when passing parameters to surface plotting functions that are not used by the plotly engine (#4298 by Rémi Gau).

• Code Improve colorbar size and labels in mosaic display (#4284 by Rémi Gau).

• Code Change the colormap to gray for the background image in the nilearn.maskers.NiftiSpheresMasker (#4269 by Rémi Gau).

• Code Remove unused **kwargs from nilearn.plotting.view_img and nilearn.plotting.plot_surf (#4270 by Rémi Gau).

• Code Use red to blue color map in the GLM reports (#4266 by Rémi Gau).

• Code nilearn.maskers.NiftiSpheresMasker will throw warnings if the labels passed to it is not a list of str, or if the number of items in the list of labels does not match the number of regions in the label image (#4274 by Rémi Gau).

• Code Copy headers from user-specified image to the result of nilearn.image.math_img (#4337 by Himanshu Aggarwal).

• Doc Render the description of the templates, atlases and datasets of the nilearn.datasets as part of the documentation (#4232 by Rémi Gau).

• Doc Render examples of GLM and masker reports as part of the documentation (#4267 and #4295 by Rémi Gau).

• Maint HTML, CSS are now linted using prettier. (#4302, by Rémi Gau).

0.10.3

HIGHLIGHTS

Warning

Minimum supported versions of packages have been bumped up:

- Numpy – v1.19.0

- SciPy – v1.8.0

- Scikit-learn – v1.0.0

- Nibabel – v4.0.0

- Pandas – v1.1.5

- Joblib – v1.0.0

• API Allow passing arguments to first_level_from_bids to build first level models that include specific set of confounds by relying on the strategies from load_confounds (#4103 by Rémi Gau).

• API Support passing t and F contrasts to compute_contrast that that have fewer columns than the number of estimated parameters. Remaining columns are padded with zero (#4067 by Rémi Gau).

• API NiftiSpheresMasker now has generate_report method (#3102 by Yasmin Mzayek and Nicolas Gensollen).

• Code Update the CompCor strategy in load_confounds and load_confounds_strategy to support fmriprep 21.x series and above. (#3285 by Hao-Ting Wang).

• Doc Combine GLM examples plot_fixed_effect and plot_fiac_analysis into a a single example plot_two_runs_model (#3191 by Taylor Salo and Rémi Gau).

• Plotting Allow setting vmin in plot_glass_brain and plot_stat_map (#3993 by Michelle Wang).

• Plotting When plotting thresholded statistical maps with a colorbar, the threshold value(s) will now be displayed as tick labels on the colorbar (##2833 by Nicolas Gensollen).

NEW

• Plotting The temp_file_lifetime parameter of interactive plots’ open_in_browser method is deprecated and has no effect (#4180 by Jerome Dockes)..

Fixes

• API MultiNiftiMasker can now call generate_report which will generate a report for the first subject in the list of subjects (#4001 by Yasmin Mzayek).

• Code Make sure that all atlases and datasets fetchers return a description (#4215 Rémi Gau).

• Code Update the CompCor strategy in load_confounds and load_confounds_strategy to support fmriprep 21.x series and above. (#3285 by Hao-Ting Wang).

• Code Fix SimpleRegressionResults to accommodate for the lack of a model attribute (#4071 Rémi Gau)

• Code clean_img can now use kwargs clean__sample_mask argument to correctly reshape the nifti image to the dimensions of the mask in the output (#4051 by Mia Zwally).

• Code Fix plotting of an image with color bar when maximum value is exactly zero (#4204 by Rémi Gau).

• Code Fix PSC normalisation method applied by standardize_signal in signal (#4116 by Hao-Ting Wang and Yasmin Mzayek).

• Code Fixed inheritance of decoder classes to keep compatibility with scikit-learn>v1.3 (#4188 by Yasmin Mzayek).

• Deprecation Make sure that all the fetchers for atlas and func from nilearn.datasets return a sklearn.utils.Bunch. Add new behavior to fetch_language_localizer_demo_dataset to return output as Bunch. This behavior will become the default in version 0.13.0 (#4233 by Rémi Gau).

Enhancements

• API NiftiSpheresMasker now has generate_report method (#3102 by Yasmin Mzayek and Nicolas Gensollen).

• API Allow passing Pandas Series of image filenames to SecondLevelModel (#4070 by Rémi Gau).

• API Allow passing arguments to first_level_from_bids to build first level models that include specific set of confounds by relying on the strategies from load_confounds (#4103 by Rémi Gau).

• API Support passing t and F contrasts to compute_contrast that that have fewer columns than the number of estimated parameters. Remaining columns are padded with zero (#4067 by Rémi Gau).

• Code Multi-subject maskers’ generate_report method no longer fails with 5D data but instead shows report of first subject. User can index input list to show report for different subjects (#3935 by Yasmin Mzayek).

• Code Allow global_signal parameter in load_confounds_strategy in denoise_strategy='compcor' (#4225 by Hao-Ting Wang).

• Code Add two_sided option for binarize_img (#4121 by Steven Meisler).

• Code generate_report now uses appropriate cut coordinates when functional image is provided (#4099 by Yasmin Mzayek and Nicolas Gensollen).

• Doc Mention the classification type (all-vs-one) in Decoding of a dataset after GLM fit for signal extraction (#4122 by Tamer Gezici).

• Doc Add backslash to homogenize Parcellations documentation (#4042 by Nikhil Krish).

• Doc Specify full form of LSS in Beta-Series Modeling for Task-Based Functional Connectivity and Decoding (#4141 by Tamer Gezici).

• Doc Don’t fetch tmaps in examples if tmaps aren’t used in the example. (#4136 by Christina Roßmanith).

• Doc Describe the return value in fetch_abide_pcp documentation (#4159 by Suramya Pokharel).

• Plotting Allow setting vmin in plot_glass_brain and plot_stat_map (#3993 by Michelle Wang).

• Plotting When plotting thresholded statistical maps with a colorbar, the threshold value(s) will now be displayed as tick labels on the colorbar (##2833 by Nicolas Gensollen).

Changes

• API Expose scipy CubicSpline extrapolate parameter in clean to control the interpolation of censored volumes in both ends of the BOLD signal data (#4028 by Jordi Huguet).

• Code Make nilearn.reporting._get_clusters_table module public and move copy_img out of nilearn._utils.niimg (#4166 by Rémi Gau).

• Code Private utility context manager write_tmp_imgs is refactored into function write_imgs_to_path (#4094 by Yasmin Mzayek).

• Code Move user facing function concat_niimgs out of private module nilearn._utils.niimg_conversions (#4167 by Rémi Gau).

• Code Remove leading underscore from non private functions to align with PEP8 (#4086 by Rémi Gau).

• Code Make decoding/proximal_operator explicitly private to align with PEP8 (#4153 by Rémi Gau).

• Code Make private functions public when used outside of their module nilearn.interface to align with PEP8 (#4168 by Rémi Gau).

• Deprecation img_to_signals_labels will also return masked_atlas in release 0.15. Meanwhile, use return_masked_atlas parameter to enable/disable this behavior. (#3761 by Mohammad Torabi).

• Deprecation Rename the parameter contrast_type in compute_contrast and attribute contrast_type in Contrast to stat_type (#4191 by Rémi Gau).

• Deprecation plot_surf_roi will raise a warning if roi_map contains negative or non-integer values; in version 0.13 this will be a ValueError (#4131 by Michelle Wang).

• Deprecation nilearn.datasets.fetch_bids_langloc_dataset will be deprecated in release 0.13 as it returns data simuilar to fetch_language_localizer_demo_dataset (#4219 by Rémi Gau).

• Deprecation the default parameter of fd_threshold and std_dvars_threshold in load_confounds with be updated to match fmriprep default in version 0.13 (#4225 by Hao-Ting Wang).

• Doc Combine GLM examples plot_fixed_effect and plot_fiac_analysis into a a single example plot_two_runs_model (#3191 by Taylor Salo and Rémi Gau).

• Maint Switch to using tox to manage environments during development and testing. All plotting python dependencies (matplotlib AND plotly) are now installed when running pip install nilearn[plotting] (#4029 by Rémi Gau).

0.10.2

Released September 2023

HIGHLIGHTS

• API Add LassoCV as a new estimator option for Decoder objects (#3781 by Michelle Wang)

• API Add vmin and symmetric_cbar arguments to plot_img_on_surf (#3873 by Michelle Wang).

• API Improve contrasts allowing fixed effects on F contrasts (#3203 by Bertrand Thirion)

• API New experimental surface API to facilitate working with surface data in downstream surface-based analyses. We provide this API as a nilearn.experimental.surface module as it is still incomplete and subject to change without a deprecation cycle. (#3856 by Jerome Dockes).

• Code Update Decoder objects to use the more efficient LogisticRegressionCV (#3736 by Michelle Wang).

• Plotting Volume plotting functions like plot_img now have an optional radiological parameter, defaulting to False. If True, this will invert the x-axis and L and R annotations to confirm to radiological conventional view. (#3172 by Konrad Wagstyl and Yasmin Mzayek).

NEW

• API New experimental surface API to facilitate working with surface data in downstream surface-based analyses. We provide this API as a nilearn.experimental.surface module as it is still incomplete and subject to change without a deprecation cycle. (#3856 by Jerome Dockes).

• Plotting Volume plotting functions like plot_img now have an optional radiological parameter, defaulting to False. If True, this will invert the x-axis and L and R annotations to confirm to radiological conventional view. (#3172 by Konrad Wagstyl and Yasmin Mzayek).

Fixes

• API Refactor deprecation of behavior of fetch_atlas_craddock_2012, fetch_atlas_smith_2009 and fetch_atlas_basc_multiscale_2015 fetchers including using API consistent maps key (#3987 by Yasmin Mzayek)

• Code Fix bug in method transform_imgs of MultiNiftiMapsMasker and MultiNiftiLabelsMasker that would raise an error if a list of sample_mask was specified to fit_transform (#3971 by Alexandre Cionca).

• Code Fixes a bug that would lead to an error when loading a fsaverage surface while relying on numpy >= 1.24.x (#3644 by Rémi Gau).

• Code Fix bug that would prevent loading the confounds of a gifti file in actual fmriprep datasets (#3819 by Rémi Gau).

• Code Fix bug that prevented using dataframes as input for second level GLM when computing contrasts (#3879 by Rémi Gau).

• Code Fix bug in first_level_from_bids that returned no confound files if the corresponding bold files contained derivatives BIDS entities (#3742 by Rémi Gau).

• Code Fix bug in first_level_from_bids that would throw a warning about slice_time_ref not being provided even when it was (#3811 by Rémi Gau).

• Code Fix bug where the cv_params_ attribute of fitter Decoder objects sometimes had missing entries if grid_param is a sequence of dicts with different keys (#3733 by Michelle Wang).

• Code Make the load_confounds confounds file selection more generic (#3794 by Taylor Salo).

• Code Relax the load_confounds confounds selection on cosine as not all confound files contained the variables (#3816 by Hao-Ting Wang).

• Code Fix pathlib.Path not being counted as Niimg-like object in new_img_like (#3723 by Maximilian Cosmo Sitter).

• Code Fix fit_transform behavior to match when fit method is passed image data (#3897 by Yasmin Mzayek)

• Plotting Allow using both vmin and threshold with “plotly” engine to be consistent with “matplotlib” behavior (#3945 by Yasmin Mzayek)

• Plotting Set edgecolors to be the same as facecolors in plot_surf_contours so that ROI contours are rendered clearly (#3973 by Yasmin Mzayek)

• Plotting Fix bug in nilearn.plotting.surf_plotting._plot_surf_matplotlib that would make vertices transparent when saving in PDF or SVG format (#3860 by Mathieu Dugré).

• Plotting Fix bug that would prevent using symmetric_cmap=True or the avg_method argument with plot_surf_roi (#3942 by Rémi Gau).

• Plotting Change default figure sizes to prevent titles from overlapping figure content (#3797 by Yasmin Mzayek and see also #2804 by Oliver Warrington)

Enhancements

• Doc Add cross-reference links to type definitions in public surface functions (#3857 by Hao-Ting Wang).

• Code Update Decoder objects to use the more efficient LogisticRegressionCV (#3736 by Michelle Wang).

• Code Throw warning in first_level_from_bids when using event.tsv files with no trial type column (#3597 by Aswin Vijayan, Rémi Gau).

• API Make return key names in the description file of destrieux surface consistent with fetch_atlas_surf_destrieux (#3774 by Tarun Samanta).

• API Add LassoCV as a new estimator option for Decoder objects (#3781 by Michelle Wang)

• API Add vmin and symmetric_cbar arguments to plot_img_on_surf (#3873 by Michelle Wang).

• API Improve generate_report method of maskers by allowing users to pass a cmap argument for plotting image (#3897 by Yasmin Mzayek)

• API Improve contrasts allowing fixed effects on F contrasts (#3203 by Bertrand Thirion)

• Code nilearn/tests/test_signal.py Remove unnecessary code in test (#4208 by Paul Reiners).

Changes

• API Expose standardize in plot_carpet and ConnectivityMeasure to handle “zscore” deprecation (#3927 by Yasmin Mzayek).

• Code Validate the content of events files before plotting them (#3994 by Rémi Gau).

• Code nilearn.glm.first_level.experimental_paradigm.check_events will now throw a warning if some events have a 0 second duration and will throw an error if an event has NaN onset or duration (#3943 by Rémi Gau).

• Deprecation Empty region signals resulting from applying mask_img in NiftiLabelsMasker will no longer be kept in release 0.15. Meanwhile, use keep_masked_labels parameter when initializing the NiftiLabelsMasker object to enable/disable this behavior. (#3722 by Mohammad Torabi).

• Deprecation Empty region signals resulting from applying mask_img in NiftiMapsMasker will no longer be kept in release 0.15. Meanwhile, use keep_masked_maps parameter when initializing the NiftiMapsMasker object to enable/disable this behavior. (#3732 by Mohammad Torabi).

• Deprecation Added warning to deprecate darkness in surf_plotting._compute_facecolors_matplotlib and html_surface._get_vertexcolor (:gh`3855` by Alisha Kodibagkar)

• Doc Replace skipped doctests with default code-blocks (#3681 in by Patrick Sadil)

• Doc Configure plots in example gallery for better rendering (#3753 by Yasmin Mzayek)

• Doc Example Visualizing 4D probabilistic atlas maps is shortened to speed up build time (#3934 by Yasmin Mzayek)

• Maint Removed old files and test code from deprecated datasets COBRE and NYU resting state (#3743 by Michelle Wang).

• Maint PEP8 and isort compliance extended to the whole nilearn codebase. (#3538, #3566, #3548, #3556, #3601, #3609, #3646, #3650, #3647, #3640, #3615, #3614, #3648, #3651 by Rémi Gau).

• Maint Finish applying black formatting to most of the codebase. (#3836, #3833, #3827, #3810, #3803, #3802, #3795, #3790, #3783, #3777 by Rémi Gau).

• Maint Removed mention of license in “header” (#3838 by Czarina Sy).

• Maint Make one_mesh_info and full_brain_info into private functions _one_mesh_info and _full_brain_info (#3847 by Rahul Brito)

• Maint Refactor error raising tests using context managers (#3854 BY François Paugam)

• Maint Move the ~nilearn.plotting.html_surface._mix_colormaps to cm.py in plotting (#3919 by Ahmad Chamma)

• Maint Remove deprecation decorator from ~nilearn.glm.regression (#3921 by Ahmad Chamma)

0.10.1

Released April 2023

NEW

• API New function load_sample_motor_activation_image to load example contrast map (#3498 by Michelle Wang).

• Plotting fsaverage meshes accessed through fetch_surf_fsaverage now come with flat maps for all resolutions (#3444 by Alexis Thual).

• Plotting surface plotting functions allow setting custom view angles and are no longer limited to predefined views (#3259 by Sam Buck Johnson and Alexis Thual).

Fixes

• API load_confounds can support searching preprocessed data in native space. (#3531 by Hao-Ting Wang)

• API non_parametric_inference can accept first level model as input without failing. (#3600 by Rémi Gau)

• API The label of the clusters in the label maps returned by get_clusters_table now matches the Cluster IDs in the clusters table (#3563 by Julio A Peraza).

• Code Fixes several bugs in first_level_from_bids. Refactors first_level_from_bids and nilearn._utils.data_gen.create_fake_bids_dataset. (#3525 by Rémi Gau).

• Code Change calculation of TR in compute_regressor to be more precise (#3362 by Anne-Sophie Kieslinger)

• Deprecation Improve how first_level_from_bids handles fetching slice timing metadata and add additional input validation. In release 0.12 the default slice_time_ref will be None instead of 0 (#3605 by Rémi Gau).

• Deprecation Add correct “zscore_sample” strategy to signal.standardize_signal which will replace the default “zscore” strategy in release 0.13 (#3474 by Yasmin Mzayek).

Enhancements

• Doc Updated example Decoding with FREM: face vs house vs chair object recognition to include section on plotting a confusion matrix from a decoder family object (#3483 by Michelle Wang).

• Plotting Surface plotting methods no longer automatically rescale background maps, which, among other things, allows to use curvature sign as a background map (#3173 by Alexis Thual).

• API first_level_from_bids now takes an optional sub_labels argument and warns users of given subject labels that are not present in the dataset (#3351 by Kevin Sitek).

• API Added special handling of param_grid and cv_params_ for Decoder objects using models with built-in cross-validation (e.g., RidgeCV, RidgeClassifierCV) (#3626 by Michelle Wang).

• API NiftiMasker now warns users if the data is being resampled to mask resolution (#3631 by Mohammad Torabi).

• Doc The docstrings of the maskers module have been update to be more consistent across the classes (#3414 by Yasmin Mzayek)

Changes

• API The behavior of fetch_atlas_craddock_2012, fetch_atlas_smith_2009 and fetch_atlas_basc_multiscale_2015 is updated with their new parameters to return one map along with a deprecation cycle (#3353 by Ahmad Chamma).

• Code Extract helper-functions for input-image validation from img_to_signals_labels, signals_to_img_labels, img_to_signals_maps signals_to_img_maps (#3523 by Rémi Gau and Christian Gerloff).

• Doc Examples are updated with the new atlas API 3D and 4D niimgs: handling and visualizing, Visualizing multiscale functional brain parcellations and Visualizing 4D probabilistic atlas maps (#3557 by Ahmad Chamma).

• Doc Update the references format of the functions CanICA and DictLearning with bibtex (#3558 by Ahmad Chamma)

• Maint Modules image code and docstrings have been reformatted using black. Changes resulted in improved readability overall and increased consistency (#3548 by Rémi Gau).

• Maint Examples have been made PEP8 compliant and reformatted using black. (#3549, #3550, #3551, #3552, #3553, #3554, #3555, by Rémi Gau).

• Maint Moved packaging from setup.py and setuptools build backend to pyproject.toml and hatchling backend. This change comes about as new standards are defined for Python packaging that are better met by the new configuration (#3635 by Yasmin Mzayek).

0.10.1rc1

Released February 2023

This is a pre-release.

Fixes

• API non_parametric_inference now supports confounding variates when they are available in the input design matrix permuted_ols (#3465 by Jelle Roelof Dalenberg).

• API permuted_ols now checks if confounding variates contain a intercept and raises an warning when multiple intercepts are defined across target and confounding variates (#3465 by Jelle Roelof Dalenberg).

• Code Restore resample_img compatibility with all nibabel.spatialimages.SpatialImage objects (#3462 by Mathias Goncalves).

Enhancements

• API Give users control over Butterworth filter (butterworth) parameters in clean and Masker objects as kwargs (#3478 by Taylor Salo).

• API Allow users to output label maps from get_clusters_table (#3477 by Steven Meisler).

• Doc Addition to docs to note that inverse_transform only performs spatial unmasking (#3445 by Robert Williamson).

Changes

• Doc The documentation for threshold_img has been improved, with more information about which voxels are set to 0 and which ones keep their original values (#3485 by Rémi Gau).

• Maint Modules decomposition and decoding code and docstrings have been reformatted using black. Changes resulted in improved readability overall and increased consistency (#3491 and #3484 by Rémi Gau).

0.10.0

Released January 2023

HIGHLIGHTS

Warning

Python 3.7 is deprecated and will be removed in release 0.12.

We recommend upgrading to Python 3.10.

Minimum supported versions of packages have been bumped up:

- Numpy – v1.19.0

- SciPy – v1.6.0

- Scikit-learn – v1.0.0

- Nibabel – v3.2.0

- Pandas – v1.1.5

- Joblib – v1.0.0

• API New classes MultiNiftiLabelsMasker and MultiNiftiMapsMasker create maskers to extract signals from a list of subjects with 4D images using parallelization (#3237 by Yasmin Mzayek).

• API permuted_ols and non_parametric_inference now support TFCE statistic (#3196 by Taylor Salo).

• API permuted_ols and non_parametric_inference now support cluster-level Family-wise error correction (#3181 by Taylor Salo).

• API save_glm_to_bids has been added, which writes model outputs to disk according to BIDS convention (#2715 by Taylor Salo).

• Doc Updated docs with a new theme using furo (#3125 by Alexis Thual).

NEW

• API New classes MultiNiftiLabelsMasker and MultiNiftiMapsMasker create maskers to extract signals from a list of subjects with 4D images using parallelization (#3237 by Yasmin Mzayek).

Fixes

• API Regressor names can now be invalid identifiers but will raise an error with compute_contrast if combined to make an invalid expression (#3374 by Yasmin Mzayek).

• API Change the order of applying sample_masks in clean based on different filtering options (#3385 by Hao-Ting Wang).

• API When using cosine filter and sample_masks is used, clean generates the cosine discrete regressors using the full time series (#3385 by Hao-Ting Wang).

• API Pass values with correct type to scikit-learn estimator parameters and remove deprecated parameter (#3430 by Yasmin Mzayek).

• Code Fix off-by-one error when setting ticks in plot_surf (#3105 by Dimitri Papadopoulos Orfanos).

• Code Fix cluster labeling for two-sided cluster level permutation tests in permuted_ols and associated function test test_cluster_level_parameters_smoke (#3436 by Jelle Roelof Dalenberg).

• Doc Description of the opening parameter added to compute_multi_epi_mask docs (#3412 by Natasha Clarke).

• Plotting Fix display of colorbar in matrix plots. Colorbar was overlapping in subplots due to a hardcoded adjustment value in the subplot (#3403 by Raphael Meudec).

• Plotting Fix plot_connectome which was raising a ValueError when vmax < 0 (#3390 by Paul Bogdan).

• Test Fix failing CanICA test by adding noise to the data creation step (#3453 by Yasmin Mzayek).

Enhancements

• API clean imputes scrubbed volumes (defined through sample_masks) with cubic spline function before applying butterworth filter (#3385 by Hao-Ting Wang).

• API Add parameter cut_coords in make_glm_report (#3452 by Audrey Duran).

• API Parameter sample_masks in clean and masker functions accept binary mask (#3439 by Hao-Ting Wang).

• Doc As part of making the User Guide more user-friendly, the introduction was reworked (#3380 by Alexis Thual)

• Doc Contributing docs were improved by adding clear guidelines for users about changelog/whatsnew entries (#3446 by Robert Williamson).

• Doc Added instructions for maintainers to make sure LaTeX dependencies are installed before building and deploying the stable docs (#3426 by Yasmin Mzayek).

Changes

• API Private functions nilearn.regions.rena_clustering.weighted_connectivity_graph and nilearn.regions.rena_clustering.nearest_neighbor_grouping have been renamed with a leading “_”, while function recursive_neighbor_agglomeration has been added to the public API (#3347 by Ahmad Chamma).

• Deprecation Numpy deprecated type aliases are replaced by equivalent builtin types (#3422 by Yasmin Mzayek).

• Deprecation Function nilearn.masking.compute_multi_gray_matter_mask has been removed since it has been deprecated and replaced by compute_multi_brain_mask (#3427 by Yasmin Mzayek).

• Deprecation Python 3.6 is no longer supported. Support for Python 3.7 is deprecated and will be removed in release 0.12 (#3429 by Yasmin Mzayek).

• Deprecation Minimum supported versions of packages have been bumped up:

  • Numpy – v1.19.0

  • SciPy – v1.6.0

  • Scikit-learn – v1.0.0

  • Nibabel – v3.2.0

  • Pandas – v1.1.5

  • Joblib – v1.0.0

  (#3440 by Yasmin Mzayek).

• Deprecation In release 0.10.0 the default resolution for loaded MNI152 templates will be 1mm instead of 2mm (#3433 by Yasmin Mzayek).

• Doc glm will no longer warn that the module is experimental (#3424 by Yasmin Mzayek).

• Doc Remove all docstring mentions of GLM module being experimental and any references to nistats migration. doc/nistats_migration.rst is also removed (#3449 by Yasmin Mzayek).

• Maint The function _safe_cache is removed because it was deemed outdated and not necessary anymore (#3375 by Yasmin Mzayek).

0.9.2

Released August 2022

HIGHLIGHTS

• API permuted_ols and non_parametric_inference now support TFCE statistic (#3196 by Taylor Salo).

• API permuted_ols and non_parametric_inference now support cluster-level Family-wise error correction (#3181 by Taylor Salo).

• API save_glm_to_bids has been added, which writes model outputs to disk according to BIDS convention (#2715 by Taylor Salo).

• Doc Updated docs with a new theme using furo (#3125 by Alexis Thual).

NEW

• API save_glm_to_bids has been added, which writes model outputs to disk according to BIDS convention (#2715 by Taylor Salo).

• API permuted_ols and non_parametric_inference now support TFCE statistic (#3196 by Taylor Salo).

• API permuted_ols and non_parametric_inference now support cluster-level Family-wise error correction (#3181 by Taylor Salo).

• Doc Updated docs with a new theme using furo (#3125 by Alexis Thual).

Fixes

• API 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).

• API 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).

• Code 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).

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

• Code 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).

• Code 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).

• Doc Fix the typographic error on the page Default Mode Network extraction of ADHD dataset (#3337 by Sachin Patalasingh).

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

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

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

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

• Plotting 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).

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

• Plotting Fix plotting of background image in view_img when the background is not the MNI template (#3312 by Jerome Dockes).

Enhancements

• API Add sample_masks to fit for censoring time points (#3193 by Hao-Ting Wang).

• API Function run_glm and class FirstLevelModel now accept a random_state parameter, which allows users to seed the KMeans cluster model used to estimate AR coefficients. (#3185 by Sami Jawhar).

• API NiftiLabelsMasker now accepts 1-dimensional arrays in its inverse_transform method (#3322 by Taylor Salo).

• API Add n_elements_ attribute to masker classes (#3311 by Taylor Salo).

• Code In get_clusters_table, when the center of mass of a binary cluster falls outside the cluster, report the nearest within-cluster voxel instead (#3292 by Connor Lane).

• Doc Docstrings of module second_level were improved (#3030 by Nicolas Gensollen).

• Doc Contributing guidelines now include a recommendation to run flake8 locally on the branch diff with main (#3317 by Yasmin Mzayek).

• Maint Functions expecting string filesystem paths now also accept path-like objects (#3300 by Yasmin Mzayek).

• Maint Conform seeding and docstrings in module _utils.data_gen (#3262 by Yasmin Mzayek).

• Maint Improvements to permuted_ols and non_parametric_inference with TFCE statistic runtime (#3333 by Sage Hahn).

Changes

• Code Boolean input data in new_img_like now defaults to np.uint8 instead of np.int8 (#3286 by Yasmin Mzayek).

• Deprecation Function fetch_surf_fsaverage no longer supports the previously deprecated option fsaverage5_sphere (#3229 by Taylor Salo).

• Deprecation Classes RegressionResults, SimpleRegressionResults, OLSModel, and LikelihoodModelResults no longer support deprecated shortened attribute names, including df_resid, wdesign, wresid, norm_resid, resid, and wY (#3229 by Taylor Salo).

• Deprecation Function fetch_openneuro_dataset_index is now deprecated in favor of the new fetch_ds000030_urls function (#3216 by Taylor Salo).

• Deprecation The current behavior of maskers’ transform on 3D niimg inputs, in which a 2D array is returned, is deprecated, and 1D arrays will be returned starting in version 0.12 (#3322 by Taylor Salo).

• Doc 64-bit integers in Nifti files: some tools such as FSL, SPM and AFNI cannot handle Nifti images containing 64-bit integers. To avoid compatibility issues, it is best to avoid writing such images and in the future trying to create them with nibabel without explicitly specifying a data type will result in an error. See details in this issue: https://github.com/nipy/nibabel/issues/1046 and this PR: https://github.com/nipy/nibabel/pull/1082. To avoid this, new_img_like now warns when given int64 arrays and converts them to int32 when possible (ie when it would not result in an overflow). Moreover, any atlas fetcher that returned int64 images now produces images containing smaller ints. (#3227 by Jerome Dockes)

• Maint Refactors fmriprep confound loading such that that the parsing of the relevant image file and the loading of the confounds are done in separate steps (#3274 by David G Ellis).

• Maint Private submodules, functions, and classes from the decomposition module now start with a “_” character to make it clear that they are not part of the public API (#3141 by Nicolas Gensollen).

• Maint Convert references in nilearn/glm/regression.py and nilearn/glm/thresholding.py to use footcite/footbibliography (#3302 by Ahmad Chamma).

• Plotting Function plot_carpet argument cmap now respects behaviour specified by docs and changes the color of the carpet_plot. Changing the label colors is now delegated to a new variable cmap_labels (#3209 by Daniel Gomez).

0.9.1

Released April 2022

This is a bugfix release.

Fixes

• API Function fetch_atlas_aal now works with all supported versions of SPM (5, 8, and 12). (#3098 by Nicolas Gensollen).

• Code Fix function permuted_ols, which was only returning the null distribution (h0_fmax) for the first regressor (#3184 by Taylor Salo).

• Code Fix function fetch_abide_pcp which was returning empty phenotypes and func_preproc after release 0.9.0 due to supporting pandas dataframes in fetchers (#3174 by Nicolas Gensollen).

• Code Fix function fetch_atlas_harvard_oxford and fetch_atlas_juelich which were returning the image in the filename attribute instead of the path to the image (#3179 by Raphael Meudec).

• Code Fix function nilearn.image._apply_cluster_size_threshold, which resulted in wrong clusters extraction when cluster_size was non-zero (#3201 by Bertrand Thirion).

• Plotting Fix colorbars in plot_stat_map, plot_glass_brain and plot_surf_stat_map which could extend beyond the figure for users with newest matplotlib version (>=3.5.1) (#3188 by Raphael Meudec).

Enhancements

• API Function plot_carpet now accepts a t_r parameter, which allows users to provide the TR of the image when the image’s header may not be accurate. (#3165 by Taylor Salo).

• Doc New example in Beta-Series Modeling for Task-Based Functional Connectivity and Decoding to demonstrate how to implement common beta series models with nilearn (#3127 by Taylor Salo).

• Doc Terms Probabilistic atlas and Deterministic atlas were added to the glossary and references were added to atlas fetchers (#3152 by Nicolas Gensollen).

• Maint Functions in nilearn.datasets have been organized by the type of data in the references page and fetch_mixed_gambles has been added to the documentation (#3207 by Taylor Salo).

Changes

• Doc 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).

• Maint 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

• API New module nilearn.interfaces to implement loading and saving utilities with various interfaces (fMRIPrep, BIDS…) (#3061 by Nicolas Gensollen).

• API New functions load_confounds and load_confounds_strategy to load confound variables easily from fMRIPrep outputs (#2946 and #3016 by Hao-Ting Wang).

• API New class HierarchicalKMeans which yields more balanced clusters than KMeans. It is also callable through Parcellations using method=hierarchical_kmeans (#2282 by Thomas Bazeille).

• API Class NiftiMapsMasker can now generate HTML reports in the same way as NiftiMasker and NiftiLabelsMasker (#2880 by Nicolas Gensollen).

• Deprecation Masker objects like NiftiMasker now belong to the new module nilearn.maskers. The old import style, through the module input_data, still works but has been deprecated (#3065 by Nicolas Gensollen).

• Doc The contributing documentation and maintenance pages were improved (#3010 by Nicolas Gensollen).

• Plotting Surface plotting functions can now produce interactive plots with Plotly. This can be selected with the engine parameter (set it to matplotlib or plotly) (#2902 by Nicolas Gensollen).

NEW

• API New module nilearn.interfaces to implement loading and saving utilities with various interfaces (fMRIPrep, BIDS…) (#3061 by Nicolas Gensollen).

• API New submodule nilearn.interfaces.fmriprep to implement loading utilities for fMRIPrep (#3061 by Nicolas Gensollen).

• API New function load_confounds to load confound variables easily from fMRIPrep outputs (#2946 by Hao-Ting Wang).

• API New function load_confounds_strategy to load confound variables from fMRIPrep outputs using four preset strategies: simple, scrubbing, compcor, and ica_aroma (#3016 by Hao-Ting Wang).

• API New submodule nilearn.interfaces.bids to implement loading utilities for BIDS datasets (#3126 by Taylor Salo).

• API New function get_bids_files to select files easily from BIDS datasets (#3126 by Taylor Salo).

• API New function parse_bids_filename to identify subparts of BIDS filenames (#3126 by Taylor Salo).

• API New submodule nilearn.interfaces.fsl to implement loading utilities for FSL outputs. (#3126 by Taylor Salo).

• API New function get_design_from_fslmat to load design matrices from FSL files (#3126 by Taylor Salo).

• API Class NiftiMapsMasker can now generate HTML reports in the same way as NiftiMasker and NiftiLabelsMasker. The report enables the users to browse through the spatial maps with a previous and next button. The users can filter the maps they wish to display by passing an integer, or a list of integers to generate_report (#2880 by Nicolas Gensollen).

• API New class HierarchicalKMeans which yields more balanced clusters than KMeans. It is also callable through Parcellations using method=hierarchical_kmeans (#2282 by Thomas Bazeille).

• Deprecation Support for Python 3.6 is deprecated and will be removed in release 0.10. Users with a Python 3.6 environment will be warned at their first Nilearn import and encouraged to update to more recent versions of Python (#3026 by Nicolas Gensollen).

• Deprecation Masker objects like NiftiMasker now belong to the new module nilearn.maskers. The old import style, through the module input_data, still works but has been deprecated (#3065 by Nicolas Gensollen).

• Plotting When using the plotly engine, surface plotting functions derived from plot_surf return a new display object, a PlotlySurfaceFigure, which provides a similar interface to the Figure returned with the matplotlib engine (#3036 by Nicolas Gensollen).

• Plotting Surface plotting functions like plot_surf_stat_map now have an engine parameter, defaulting to matplotlib, but which can be set to plotly. If plotly and kaleido are installed, this will generate an interactive plot of the surface map using plotly instead of matplotlib. Note that this functionality is still experimental, and that some capabilities supported by our matplotlib engine are not yet supported by the plotly engine (#2902 by Nicolas Gensollen).

Fixes

• Code When a label image with non integer values was provided to the NiftiLabelsMasker, its generate_report method was raising an IndexError (#3009 by Nicolas Gensollen).

• Code Method generate_report threw a TypeError when FirstLevelModel was instantiated with mask_img being a NiftiMasker. Function make_glm_report was fixed accordingly (#3035 by Alexis Thual).

• Code Function find_parcellation_cut_coords now returns coordinates and labels having the same order as the one of the input labels index (#3078 by Myeong Seop Song).

• Code Fixed Hommel value computation in nilearn/glm/thresholding.py used in the cluster_level_inference function (#3109 by Bertrand Thirion).

• Code Fixed computation of Benjamini-Hocheberg threshold in nilearn/glm/thresholding.py function (#3137 by Bertrand Thirion).

• Deprecation Attribute scaling_axis of FirstLevelModel has been deprecated and will be removed in 0.11.0. When scaling is performed, the attribute signal_scaling is used to define the axis instead (#3135 by Nicolas Gensollen).

• Doc Convert references in nilearn/regions/region_extractor.py to use footcite / footbibliography (#3111 by Neelay Shah).

• Plotting Function plot_markers did not work when the display_mode parameter included l and r and the parameter node_size was provided as an array (#3013 by Leonard Sasse).

Enhancements

• API 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).

• API 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).

• Doc 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 were defined more clearly with sections on issue Labels and issue Closing policy (#3010 by Nicolas Gensollen).

• API 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).

• API 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).

• API 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).

• Code 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).

• Maint 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).

• Plotting 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).

• Plotting 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

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

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

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

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

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

• Deprecation 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).

• Deprecation 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).

• Deprecation 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).

• Maint 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).

• Maint 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).

• Maint 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

• API New atlas fetcher fetch_atlas_juelich to download Juelich atlas from FSL (#2723 by Ahmad Chamma).

• API New grey and white-matter template and mask loading functions: load_mni152_gm_template, load_mni152_wm_template, load_mni152_gm_mask, and load_mni152_wm_mask (#2738 by Ana Luisa Pinho).

• Code Function binarize_img binarizes images into 0 and 1 (#2900 by Daniel Gomez).

• Doc The Contributing has been reworked. It now provides insights on nilearn organization as a project as well as more explicit Contribution Guidelines (#2755 by Thomas Bazeille).

NEW

• API New atlas fetcher fetch_atlas_juelich to download Juelich atlas from FSL (#2723 by Ahmad Chamma).

• API Classes NiftiMasker, MultiNiftiMasker, and objects relying on such maskers (Decoder or CanICA for example) can now use new options for the argument mask_strategy:whole-brain-template for whole-brain template (same as previous option template), gm-template for grey-matter template, and wm-template for white-matter template (#2904 by Nicolas Gensollen).

• Code Function load_mni152_gm_template takes the skullstripped 1mm-resolution version of the grey-matter MNI152 template and re-samples it using a different resolution, if specified (#2738 by Ana Luisa Pinho).

• Code Function load_mni152_wm_template takes the skullstripped 1mm-resolution version of the white-matter MNI152 template and re-samples it using a different resolution, if specified (#2738 by Ana Luisa Pinho).

• Code Function load_mni152_gm_mask loads mask from the grey-matter MNI152 template (#2738 by Ana Luisa Pinho).

• Code Function load_mni152_wm_mask loads mask from the white-matter MNI152 template (#2738 by Ana Luisa Pinho).

• Code Function binarize_img binarizes images into 0 and 1 (#2900 by Daniel Gomez).

• Maint The Contributing has been reworked. It now provides insights on nilearn organization as a project as well as more explicit Contribution Guidelines (#2755 by Thomas Bazeille).

Fixes

• API Function compute_multi_brain_mask has replaced nilearn.masking.compute_multi_grey_matter_mask. A mask parameter has been added; it accepts three types of masks—i.e. whole-brain, grey-matter, and white-matter—following the enhancements made in the function nilearn.masking.compute_brain_mask in this release (#2738 by Ana Luisa Pinho).

• Plotting Fix colorbar of function view_img which was not visible for some combinations of black_bg and bg_img parameters (#2876 by Nicolas Gensollen).

• Plotting Fix missing title with function plot_surf and deriving functions (#2941 by Nicolas Gensollen).

Enhancements

• API 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).

• API 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).

• Code 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).

• Code 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).

• Maint 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).

Changes

• Maint 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

• API Class NiftiLabelsMasker can now generate HTML reports in the same way as the NiftiMasker (#2707 by Nicolas Gensollen).

• API Function clean now accepts a new parameter sample_mask of shape (number of scans - number of volumes removed, ) (#2858 by Hao-Ting Wang).

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

• API Function fetch_surf_fsaverage now accepts fsaverage3, fsaverage4 and fsaverage6 as values for parameter mesh, so that all resolutions of fsaverage from 3 to 7 are now available (#2815 by Alexis Thual).

• API Function fetch_surf_fsaverage now provides attributes {area, curv, sphere, thick}_{left, right} for all fsaverage resolutions (#2815 by Alexis Thual).

• API Function run_glm now allows auto regressive noise models of order greater than one (#2532 by Robert Luke).

NEW

• API 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).

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

• API 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

• API 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).

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

• Code 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).

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

• Plotting 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).

• Plotting 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).

Enhancements

• API Parameter sessions has been replaced with runs in clean to match BIDS semantics. sessions has been deprecated and will be removed in 0.9.0 (#2821 by Hao-Ting Wang).

• API Add argument filter in clean and allow a selection of signal filtering strategies: butterwoth for butterworth filter, cosine for discrete cosine transformation, and False for no filtering (#2821 by Hao-Ting Wang).

• API Change the default strategy for sklearn.dummy.DummyClassifier from prior to stratified (#2826 by Binh Nguyen).

• API Function run_glm now allows auto regressive noise models of order greater than one (#2532 by Robert Luke).

• API Function fetch_surf_fsaverage now accepts fsaverage3, fsaverage4 and fsaverage6 as values for parameter mesh, so that all resolutions of fsaverage from 3 to 7 are now available (#2815 by Alexis Thual).

• API Function fetch_surf_fsaverage now provides attributes {area, curv, sphere, thick}_{left, right} for all fsaverage resolutions (#2815 by Alexis Thual).

• Plotting Function view_markers now accepts an optional argument marker_labels to provide labels to each marker (#2745 by Greydon Gilmore).

• Plotting Function plot_surf now accepts new values for avg_method argument, such as min, max, or even a custom python function to compute the value displayed for each face of the plotted mesh (#2790 by Alexis Thual).

• Plotting Function view_img_on_surf can now optionally pass through parameters to function vol_to_surf using the vol_to_surf_kwargs argument. One application is better HTML visualization of atlases (https://nilearn.github.io/auto_examples/01_plotting/plot_3d_map_to_surface_projection.html) (#2805 by Evan Edmond).

• Plotting Function view_connectome now accepts an optional argument node_color to provide a single color for all nodes, or one color per node. It defaults to auto which colors markers according to the viridis colormap (#2810 by Raphael Meudec).

• Maint Function clean has been refactored to clarify the data flow (#2821 by Hao-Ting Wang).

• Maint Moves parameter sample_mask from NiftiMasker to method transform in base class nilearn.maskers.BaseMasker (#2858 by Hao-Ting Wang).

Changes

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

• Deprecation 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).

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

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

• Deprecation 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

• API 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).

• Code Decoder and DecoderRegressor are now implemented with random predictions to estimate a chance level (#2622 by Kamalakar Reddy Daddy).

• Plotting Functions plot_epi, plot_roi, plot_stat_map, plot_prob_atlas are now implemented with new display mode Mosaic. That implies plotting 3D maps in multiple columns and rows in a single axes (#2684 by Kamalakar Reddy Daddy).

• Plotting Function plot_carpet now supports discrete atlases. When an atlas is used, a colorbar is added to the figure, optionally with labels corresponding to the different values in the atlas (#2702 by Taylor Salo).

NEW

• API 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).

• API 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

• Code Fix altered, non-zero baseline in design matrices where multiple events in the same condition end at the same time (see #2674) (#2553 by Martin Wegrzyn).

• Code Fix testing issues on ARM machine (#2606 by Kamalakar Reddy Daddy).

Enhancements

• API Functions make_glm_report and get_clusters_table have a new argument, two_sided, which allows for two-sided thresholding, which is disabled by default (#2719 by Taylor Salo).

• API Function clean now has a psc standardization option which allows time series with negative mean values (#2714 by Hao-Ting Wang).

• API Function fetch_neurovault now implements a resample boolean argument to either perform a fixed resampling during download or keep original images. This can be handy to reduce disk usage. By default, the downloaded images are not resampled (#2696 by Raphael Meudec).

• Code Decoder and DecoderRegressor are now implemented with random predictions to estimate a chance level (#2622 by Kamalakar Reddy Daddy).

• Code Decoder, DecoderRegressor, FREMRegressor, and FREMClassifier now override the score method to use whatever scoring strategy was defined through the scoring attribute instead of the sklearn default. If the scoring attribute of the decoder is set to None, the scoring strategy will default to accuracy for classifiers and to r2 score for regressors (#2669 by Nicolas Gensollen).

• Code NiftiMasker, NiftiLabelsMasker, MultiNiftiMasker, NiftiMapsMasker, and NiftiSpheresMasker can now compute high variance confounds on the images provided to transform and regress them out automatically. This behaviour is controlled through the high_variance_confounds boolean parameter of these maskers which default to False (#2697 by Nicolas Gensollen).

• Code NiftiLabelsMasker now automatically replaces NaNs in input data with zeros, to match the behavior of other maskers (#2712 by Taylor Salo).

• Plotting Functions plot_epi, plot_roi, plot_stat_map, plot_prob_atlas are now implemented with new display mode Mosaic. That implies plotting 3D maps in multiple columns and rows in a single axes (#2684 by Kamalakar Reddy Daddy).

• Plotting Function plot_surf and deriving functions like plot_surf_roi now accept an optional argument cbar_tick_format to specify how numbers should be displayed on the colorbar of surface plots. The default format is scientific notation except for function plot_surf_roi for which it is set as integers (#2643 by Nicolas Gensollen).

• Plotting Function plot_carpet now supports discrete atlases. When an atlas is used, a colorbar is added to the figure, optionally with labels corresponding to the different values in the atlas (#2702 by Taylor Salo).

0.7.0

Released November 2020

HIGHLIGHTS

• API Nilearn now includes the functionality of Nistats as nilearn.glm. This module is experimental, hence subject to change in any future release. (#2299, #2304, and #2307 by Kshitij Chawla, and #2509 by Binh Nguyen).

• API New classes 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 (#2000 by Binh Nguyen).

• API New classes nilearn.decoding.FREMClassifier (for classification) and nilearn.decoding.FREMRegressor (for regression) extend the Decoder object with one fast clustering step at the beginning and aggregates a high number of estimators trained on various splits of the training set (#2327 by Thomas Bazeille).

• Plotting New plotting functions:

  • plot_event to visualize events file.

  • plot_roi can now plot ROIs in contours with view_type argument.

  • plot_carpet generates a “carpet plot” (also known as a “Power plot” or a “grayplot”)

  • plot_img_on_surf generates multiple views of plot_surf_stat_map in a single figure.

  • plot_markers shows network nodes (markers) on a glass brain template

  • plot_surf_contours plots the contours of regions of interest on the surface

Warning

Minimum required version of Joblib is now 0.12.

NEW

• API Nilearn now includes the functionality of Nistats.

• API 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.

• API 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.

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

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

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

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

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

• Plotting 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.

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

• Plotting 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.

• Plotting 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.

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

Fixes

• Code nilearn.maskers.NiftiLabelsMasker no longer ignores its mask_img

• Code 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.

• Code 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.

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

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

• Doc Fix readme file of the Destrieux 2009 atlas.

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

Changes

• Code nilearn.connectome.ConnectivityMeasure can now remove confounds in its transform step.

• Code nilearn.surface.vol_to_surf can now sample between two nested surfaces (eg white matter and pial surfaces) at specific cortical depths

• Code nilearn.datasets.fetch_surf_fsaverage now also downloads white matter surfaces.

• Deprecation Function nilearn.plotting.plot_connectome_strength has been deprecated and will be removed in release 0.9 .

• Deprecation Function nilearn.datasets.fetch_cobre has been deprecated and will be removed in release 0.9 .

0.6.2

Released February 2020

ENHANCEMENTS

• API NiftiSpheresMasker now has an inverse transform, projecting spheres to the corresponding mask_img (#2429 by Simon Steinkamp).

• Maint Generated documentation now includes Binder links to launch examples interactively in the browser (#2300 by Elizabeth DuPre).

Fixes

• Doc Typo in example fixed (#2312 by Jon Haitz Legarreta Gorrono).

• Maint More robust matplotlib backend selection (#2302 by Gael Varoquaux).

Changes

• Deprecation 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:

• Elizabeth DuPre

• Franz Liem

• Gael Varoquaux

• Jon Haitz Legarreta Gorrono

• Joshua Teves

• Kshitij Chawla

• Zvi Baratz

• Simon Steinkamp

0.6.1

Released January 2020

ENHANCEMENTS

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

Fixes

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

Contributors

The following people contributed to this release:

• Elizabeth DuPre

• Jerome Dockes

• Kshitij Chawla

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

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

• API 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).

• API 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).

• API 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).

• Code 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).

• Plotting 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).

ENHANCEMENTS

• API 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).

• API 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).

• Plotting 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).

• Plotting Function view_surf now accepts surface data provided as a file path (#2057 by Jerome Dockes).

CHANGES

• Plotting 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

• Code Class NiftiLabelsMasker no longer truncates region means to their integral part when input images are of integer type (#2195 by Kshitij Chawla).

• Code The argument version='det' in function fetch_atlas_pauli_2017 now works as expected (#2235 by Ryan Hammonds).

• Maint pip install nilearn now installs the necessary dependencies (#2214 by Kshitij Chawla).

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

0.6.0rc

NEW

Warning

• Deprecation 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).

• Plotting 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).

• Plotting 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).

Changes

• API 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).

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

Fixes

• API Method inverse_transform now works without the need to call transform first (#2248 by Gael Varoquaux).

• Code Class NiftiLabelsMasker no longer truncates region means to their integral part when input images are of integer type (#2195 by Kshitij Chawla).

• Code Function smooth_img no longer fails if fwhm is a numpy.ndarray (#2107 by Paula Sanz-Leon).

• Code Function new_img_like no longer attempts to copy non-iterable headers (#2212 by Kshitij Chawla).

• Code Nilearn no longer raises ImportError for nose when Matplotlib is not installed (#2231 by Kshitij Chawla).

• Code The argument version='det' in function fetch_atlas_pauli_2017 now works as expected (#2235 by Ryan Hammonds).

• Maint pip install nilearn now installs the necessary dependencies (#2214 by Kshitij Chawla).

Contributors

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

• Chris Markiewicz

• Dan Gale

• Daniel Gomez

• Derek Pisner

• Elizabeth DuPre

• Eric Larson

• Gael Varoquaux

• Jerome Dockes

• Johannes Wiesner

• Kshitij Chawla

• Paula Sanz-Leon

• Loic Tetrel

• Ryan Hammonds

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

• API 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

• API All functions and examples now use function get_data rather than the deprecated method nibabel.Nifti1Image.get_data (#2172 by Jerome Dockes).

• API Users can now specify fetching data for adults, children, or both from fetch_development_fmri.

• Code Function fetch_neurovault now does not filter out images that have their metadata field is_valid cleared by default (#2169 by Jerome Dockes).

Fixes

• Plotting 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):

• Jake Vogel

• Jerome Dockes

• Kshitij Chawla

• Roberto Guidotti

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.

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

• API 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).

• Code 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).

• Code 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.

• Doc 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).

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

• Maint 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).

• Maint 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).

• Maint The Localizer dataset now follows the BIDS organization.

• Plotting 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).

Changes

• API 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).

• Doc 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).

• Doc 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).

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

• Plotting 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).

• Plotting 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).

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

Fixes

• API Function add_contours now accepts threshold argument for filled=False. Now threshold is equally applied when asked for fillings in the contours.

• Code Function fetch_surf_nki_enhanced is now downloading the correct left and right functional surface data for each subject (#2118 by Julia Huntenburg).

• Code Function fetch_atlas_schaefer_2018 now downloads from release version 0.14.3 (instead of 0.8.1) by default, which includes corrected region label names along with 700 and 900 region parcelations (#2138 by Dan Gale).

• Code Colormap creation functions have been updated to avoid matplotlib deprecation warnings about colormap reversal (#2131 by Eric Larson).

• Code Neurovault fetcher no longer fails if unable to update dataset metadata file due to faulty permissions.

• Plotting Function plot_glass_brain with colorbar=True does not crash when images have NaNs (#1953 by Kamalakar Reddy Daddy).

• Plotting Functions plot_surf and plot_surf_stat_map no longer threshold zero values when no threshold is given (#1997 by Julia Huntenburg).

• Plotting Function plot_surf_stat_map used with a thresholded map but without a background map results in the surface mesh being displayed in half-transparent grey to maintain a 3D perception (#1997 by Julia Huntenburg).

• Plotting Function view_surf now accepts surface data provided as a file path.

• Plotting Function plot_glass_brain now correctly displays the left ‘l’ orientation even when the given images are completely masked (empty images) (#1888 by Kamalakar Reddy Daddy).

• Plotting Function plot_matrix with providing labels=None, False, or an empty list now correctly disables labels (#2083 by Moritz Boos).

• Plotting Function plot_surf_roi now takes vmin, and vmax parameters (#2052 by Ian Abenes).

Contributors

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

• Alexandre Abraham

• Alexandre Gramfort

• Ana Luisa Pinho

• Andrés Hoyos Idrobo

• Thomas Bazeille

• Bertrand Thirion

• Colin Reininger

• Céline Delettre

• Dan Gale

• Daniel Gomez

• Elizabeth DuPre

• Eric Larson

• Franz Liem

• Gael Varoquaux

• Gilles de Hollander

• Greg Kiar

• Guillaume Lemaitre

• Ian Abenes

• Jake Vogel

• Jerome Dockes

• Jerome-Alexis Chevalier

• Julia Huntenburg

• Kamalakar Reddy Daddy

• Kshitij Chawla

• Mehdi Rahim

• Moritz Boos

• Sylvain Takerkart

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 Plotting .mgz files in MNE broke in 0.5.1 and has been fixed.

Contributors

The following people contributed to this release:

• Kshitij Chawla (11)

• Gael Varoquaux (3)

• Alexandre Gramfort (2)

0.5.1

Released April 2019

NEW

• API New function fetch_atlas_schaefer_2018.

• API New function fetch_coords_seitzman_2018.

• Code Calculate image data dtype from header information.

• Code 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.

• Deprecation 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.

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

Changes

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

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

• Plotting 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.

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

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

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

  • coords is now marker_coords.

  • colors is now marker_color.

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

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

Fixes

• Code Example plot_seed_to_voxel_correlation now really saves z-transformed maps.

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

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

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

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

Known Issues

• Plotting 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 Plotting .mgz files in MNE is broken.

Contributors

The following people contributed to this release:

• Bertrand Thirion (2)

• Kshitij Chawla (90)

• Franz Liem (22)

• Jerome Dockes (16)

• Gael Varoquaux (11)

• Salma Bougacha (8)

• himanshupathak21061998 (7)

• Elizabeth DuPre (2)

• Eric Larson (1)

• Pierre Bellec (1)

0.5.0

Released November 2018

NEW

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

• Plotting New functions view_surf and view_img_on_surf for interactive visualization of maps on the cortical surface in a web browser.

• Plotting New functions view_connectome and view_markers for interactive visualization of connectomes and seed locations in 3D.

• Plotting New function view_img for interactive visualization of volumes with 3 orthogonal cuts.

Note

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

• Plotting Function find_parcellation_cut_coords for extraction of coordinates on brain parcellations denoted as labels.

• Plotting Function find_probabilistic_atlas_cut_coords for extraction of coordinates on brain probabilistic maps.

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.

• fetch_surf_fsaverage.

• fetch_atlas_pauli_2017.

• fetch_neurovault_auditory_computation_task.

• fetch_neurovault_motor_task.

ENHANCEMENTS

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

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

• API The fit method now accepts 4D niimgs.

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

• Code Dataset fetchers are now more reliable, less verbose.

• Code Anaconda link in the installation documentation updated.

• Maint Lots of other fixes in documentation and examples.

• Maint Scipy is listed as a dependency for Nilearn installation.

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

Changes

• Code 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

• API 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).

• Plotting 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.

Enhancements

• API 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.

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

• Plotting 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.

Changes

• API 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.

• API 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).

• API 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.

• Plotting 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:

• Gael Varoquaux (15)

• Pierre Bellec (114)

• Michael Notter (30)

• Kshitij Chawla (28)

• Kamalakar Reddy Daddy (4)

• himanshupathak21061998 (4)

• Christian Horea (1)

• Jerome Dockes (7)

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

• Plotting 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).

• Plotting 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

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

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

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

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

Fixes

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

• Doc Brainomics dataset has been replaced in several examples.

• Maint Lots of other fixes in documentation and examples.

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

Changes

• Doc In function img_to_signals_labels, the See Also section in documentation now also points to NiftiLabelsMasker and NiftiMapsMasker.

• Doc Anaconda link in the installation documentation updated.

• Maint Scipy is listed as a dependency for Nilearn installation.

Contributors

The following people contributed to this release:

• Gael Varoquaux (58)

• Kshitij Chawla (115)

• Jerome Dockes (15)

• Oscar Esteban (14)

• Eric Larson (10)

• Kamalakar Reddy Daddy (6)

• Bertrand Thirion (3)

• Alexandre Abadie (5)

• Sourav Singh (4)

• Alex Rothberg (3)

• AnaLu (3)

• Demian Wassermann (3)

• Christian Horea (3)

• Jason Gors (3)

• Jean Remi King (3)

• MADHYASTHA Meghana (3)

• Simon Steinkamp (3)

• Jerome-Alexis Chevalier (3)

• Salma Bougacha (3)

• sfvnMAC (3)

• Akshay (2)

• Daniel Gomez (2)

• Guillaume Lemaitre (2)

• Pierre Bellec (2)

• Ariel Rokem (2)

• erramuzpe (2)

• foucault (2)

• jehane (2)

• Sylvain LANNUZEL (1)

• Aki Nikolaidis (1)

• Christophe Bedetti (1)

• Dan Gale (1)

• Dillon Plunkett (1)

• Dimitri Papadopoulos Orfanos (1)

• Greg Operto (1)

• Ivan Gonzalez (1)

• Yaroslav Halchenko (1)

• dtyulman (1)

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

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

Enhancements

• API All NiftiMaskers now have a dtype argument. For now the default behaviour is to keep the same data type as the input data.

• API New function fetch_surf_fsaverage to download either fsaverage or fsaverage5 (Freesurfer cortical meshes).

• API New function fetch_atlas_pauli_2017 to download a recent subcortical neuroimaging atlas.

• API New functions fetch_neurovault_auditory_computation_task and fetch_neurovault_motor_task for simple example data.

• Plotting 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).

• Plotting New functions view_surf and view_surf and view_img_on_surf for interactive visualization of maps on the cortical surface in a web browser.

• Plotting New functions view_connectome and view_markers to visualize connectomes and seed locations in 3D

• Plotting New function nilearn.plotting.view_stat_map (renamed to view_img in stable release) for interactive visualization of volumes with 3 orthogonal cuts.

• Plotting New function find_parcellation_cut_coords for extraction of coordinates on brain parcellations denoted as labels.

• Plotting New function find_probabilistic_atlas_cut_coords for extraction of coordinates on brain probabilistic maps.

Changes

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

• Deprecation 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.

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

• Plotting 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:

• Gael Varoquaux (49)

• Jerome Dockes (180)

• Kshitij Chawla (57)

• Sylvain Lan (38)

• Kamalakar Reddy Daddy (36)

• Gilles de Hollander (10)

• Bertrand Thirion (4)

• MENUET Romuald (4)

• Moritz Boos (3)

• Peer Herholz (1)

• Pierre Bellec (1)

0.4.2

Released June 2018

Few important bugs fix release for OHBM conference.

Changes

• Plotting 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.

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

Fixes

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

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

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

• Code 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

• API Classes CanICA and DictLearning have a new attribute components_img_ providing directly the components learned as a Nifti1Image. This avoids the step of unmasking the attribute components_ which is true for older versions (#1536 by Kamalakar Reddy Daddy).

• API New class nilearn.regions.Parcellations for learning brain parcellations on fMRI data (#1370 by Kamalakar Reddy Daddy).

• API Add optional reordering of the matrix using a argument reorder with function plot_matrix.

Note

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

Changes

• Deprecation 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

• Code Fix bug loading Nifti2Image.

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

• Plotting 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.

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

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

• Plotting Fix colormap bug with recent matplotlib 2.2.0.

0.4.0

Released November 2017

Highlights

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

• Plotting New function plot_matrix to display matrices, eg connectomes.

Enhancements

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

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

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

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

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

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

• Maint Upgraded to Sphinx-Gallery 0.1.11.

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

• Plotting New function plot_matrix to display connectome matrices.

• Plotting 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.

Fixes

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

• Maint Fixed issues with matplotlib 2.1.0.

• Maint Fixed issues with SciPy 1.0.0.

Changes

• API 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.

• Code 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.

• Deprecation 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.

• Deprecation The minimum required version for scipy is now 0.14.

• Deprecation Dropped support for Nibabel older than 2.0.2.

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

• Maint The examples now use pandas for the behavioral information.

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

Contributors

The following people contributed to this release:

• Jerome Dockes (127)

• Gael Varoquaux (62)

• Kamalakar Reddy Daddy (36)

• Jeff Chiang (11)

• Elizabeth DuPre (9)

• Jona Sassenhagen (9)

• Sylvain Lan (7)

• J Necus (6)

• Pierre-Olivier Quirion (5)

• AnaLu (3)

• Jean-Rémi King (3)

• MADHYASTHA Meghana (3)

• Salma Bougacha (3)

• sfvnMAC (3)

• Eric Larson (2)

• Christian Horea (2)

• Moritz Boos (2)

• Alex Rothberg (1)

• Bertrand Thirion (1)

• Christophe Bedetti (1)

• John Griffiths (1)

• Mehdi Rahim (1)

• Sylvain LANNUZEL (1)

• Yaroslav Halchenko (1)

• clfs (1)

0.3.1

Released June 2017

This is a minor release for BrainHack.

Highlights

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

Changes

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

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

Fixes

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

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

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

Enhancements

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

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

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

• API 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.

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

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

• Doc Improvements in plotting, decoding and functional connectivity examples.

• Plotting Tighter bounding boxes when using add_contours for plotting.

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

• Code 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.

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

Fixes

• Code Fix bug uncompressing tar files with datasets fetcher.

• Code Fixed deprecations set_axis_bgcolor related to matplotlib in plotting functions.

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

• Maint Fixed bunch of CircleCI documentation build failures.

Enhancements

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

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

0.3.0 beta

Released February 2017

To install the beta version, use:

pip install --upgrade --pre nilearn

Highlights

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

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

• Maint Dropped support for Python 2.6

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

• Plotting Simple surface plotting.

Changes

• API Functions cov_to_corr and prec_to_partial can now be used.

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

Fixes

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

• Code Fix bug in function clean_img.

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

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

Enhancements

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

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

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

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

• API 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.

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

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

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

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

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

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

• Maint coveralls is replaced with codecov.

• Maint Upgraded to Sphinx version 0.1.7.

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

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

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

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

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

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

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

• Code Fix bug when downloading ABIDE timeseries.

• Plotting Fix flipping of left hemisphere when plotting glass brain.

Enhancements

• Deprecation Remove outdated power atlas example.

• Maint Sphinx-gallery updated to version 0.1.3.

• Maint Refactoring of examples and documentation.

• Maint Better ordering of regions in function fetch_coords_dosenbach_2010.

Changes

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

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

• Deprecation 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

• Code 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.

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

New

• API 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.

• Doc Connectivity examples rely on ConnectivityMeasure.

Fixes

• Code 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.

• Maint 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

• API New display_mode options in functions plot_glass_brain and plot_connectome. It is possible to plot right and left hemisphere projections separately.

• API New function load_mni152_brain_mask to load canonical brain mask image in MNI template space.

• API New function fetch_icbm152_brain_gm_mask to load brain grey matter mask image.

• API New function load_img loads data from a filename or a list of filenames.

• API New function clean_img applies the cleaning function clean on all voxels.

• API New simple data downloader fetch_localizer_button_task to simplify some examples.

• API New function get_data_dirs to check where nilearn downloads data.

• Code Function fetch_localizer_contrasts can now download a specific list of subjects rather than a range of subjects.

Contributors

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

• Gael Varoquaux (55)

• Alexandre Abraham (39)

• Martin Perez-Guevara (26)

• Kamalakar Reddy Daddy (20)

• Amadeus Kanaan (8)

• Alexandre Abadie (3)

• Arthur Mensch (3)

• Elvis Dohmatob (3)

• Loic Estève (3)

• Jerome Dockes (2)

• Alexandre M. S (1)

• Bertrand Thirion (1)

• Ivan Gonzalez (1)

• Roberto Guidotti (1)

0.2.4

Released April 2016

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

New

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

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

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

• Plotting Function plot_connectome now plots connectome with colorbars.

Changes

• API 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.

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

• API 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

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

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

• Code Downloader for Dosenbach atlas fetch_coords_dosenbach_2010.

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

Bug fixes

• Plotting 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

• API Fetcher for Megatrawl Netmats dataset.

Enhancements

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

• Maint Flake8 is now run on pull requests.

• Maint Reworking of the documentation organization.

• Maint Sphinx-gallery updated to version 0.1.1.

Fixes

• Code Fix symmetric_split behavior in function fetch_atlas_harvard_oxford.

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

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

• Code Class RegionExtractor handles data containing Nans.

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

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

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

• Maint Fix matplotlib 1.5.0 compatibility in function plot_prob_atlas.

• Maint Fix matplotlib backend choice on Mac OS X.

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

Changes

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

• Deprecation Deprecated dataset downloading function have been removed.

Contributors

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

• Kamalakar Reddy Daddy (39)

• Alexandre Abraham (22)

• Loic Estève (21)

• Gael Varoquaux (19)

• Alexandre Abadie (12)

• Salma Bougacha (7)

• Danilo Bzdok (3)

• Arthur Mensch (1)

• Ben Cipollini (1)

• Elvis Dohmatob (1)

• Óscar Nájera (1)

0.2.1

Released December 2015

Changelog

• Code 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

• API The new module nilearn.connectome now has class nilearn.connectome.ConnectivityMeasure can be useful for computing functional connectivity matrices.

• API Globbing expressions can now be used in all nilearn functions expecting a list of files.

• API The new module nilearn.regions now has class regions.RegionExtractor which can be used for post processing brain regions of interest extraction.

• API The function connected_regions in nilearn.regions is also implemented as a helper function to regions.RegionExtractor.

• API The function threshold_img in nilearn.image is implemented to use it for thresholding statistical maps.

• Code The function nilearn.connectome.sym_to_vec in same module nilearn.connectome is also implemented as a helper function to class nilearn.connectome.ConnectivityMeasure.

• Code The class decomposition.DictLearning in nilearn.decomposition is a decomposition method similar to ICA that imposes sparsity on components instead of independence between them.

• Maint Integrating back references template from sphinx-gallery of 0.0.11 version release.

Enhancements

• Doc Documentation about class maskers.NiftiSpheresMasker.

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

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

Bug fixes

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

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

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

API changes summary

• API The default value for number of cuts (n_cuts) in function find_cut_slices in nilearn.plotting module has been changed from 12 to 7 i.e. n_cuts=7.

• Maint The utilities in function group_sparse_covariance have been moved into module nilearn.connectome.

Contributors

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

• Elvis Dohmatob (822)

• Gael Varoquaux (142)

• Alexandre Abraham (119)

• Loic Estève (90)

• Kamalakar Reddy Daddy (85)

• Alexandre Abadie (65)

• Chris Gorgolewski (43)

• Salma Bougacha (39)

• Danilo Bzdok (29)

• Martin Perez-Guevara (20)

• Mehdi Rahim (19)

• Óscar Nájera (19)

• Arthur Mensch (8)

• Ben Cipollini (8)

• Aina Frau-Pascual (4)

• Julia Huntenburg (4)

• Michael Hanke (2)

• Ariel Rokem (2)

• Bertrand Thirion (1)

• Dimitri Papadopoulos Orfanos (1)

0.1.4

Released July 2015

Highlights

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

• Code Add the Destrieux 2009 and Power 2011 atlas.

• Code Better caching in maskers.

• Maint Obey Debian packaging rules.

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

• Alexandre Abraham (141)

• Gael Varoquaux (15)

• Loic Estève (10)

• Arthur Mensch (2)

• Danilo Bzdok (2)

• Michael Hanke (2)

• Mehdi Rahim (1)

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

• API Function plot_connectome now supports vmin and vmax.

• Code Dealing with NaNs in function plot_connectome.

• Code Fix confounds removal with single confounds.

• Code Fix frequency filtering.

• Code Keep header information in images.

• Code add_overlay finds vmin and vmax automatically.

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

• Plotting Fix extreme values in colorbar were sometimes brok.

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

• Alexandre Abraham (129)

• Loic Estève (67)

• Gael Varoquaux (57)

• Ben Cipollini (44)

• Danilo Bzdok (37)

• Elvis Dohmatob (20)

• Óscar Nájera (14)

• Salma Bougacha (9)

• Alexandre Gramfort (8)

• Kamalakar Reddy Daddy (7)

• Demian Wassermann (3)

• Bertrand Thirion (1)

0.1.2

Released March 2015

Changelog

• Code 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):

• Loic Estève (81)

• Alexandre Abraham (18)

• Danilo Bzdok (18)

• Ben Cipollini (14)

• Gael Varoquaux (2)

0.1.0

Released February 2015

Changelog

First release of nilearn.

Contributors (from git shortlog -ns 0.1):

• Gael Varoquaux (600)

• Alexandre Abraham (483)

• Loic Estève (302)

• Philippe Gervais (254)

• Virgile Fritsch (122)

• Michael Eickenberg (83)

• Jean Kossaifi (59)

• Jaques Grobler (57)

• Danilo Bzdok (46)

• Chris Gorgolewski (35)

• Ronald Phlypo (28)

• Ben Cipollini (25)

• Bertrand Thirion (15)

• Alexandre Gramfort (13)

• Fabian Pedregosa (12)

• Yannick Schwartz (11)

• Mehdi Rahim (9)

• Óscar Nájera (7)

• Elvis Dohmatob (6)

• Konstantin Shmelkov (4)

• Jason Gors (3)

• Salma Bougacha (3)

• Alexandre Savio (1)

• Jan Margeta (1)

• Matthias Ekman (1)

• Michael Waskom (1)

• Vincent Michel (1)