
.. currentmodule:: nilearn

.. include:: names.rst

0.5.0
=====

**Released November 2018**

NEW
---

- :ref:`interactive plotting functions <interactive-plotting>`, eg for use in a notebook.

- :bdg-info:`Plotting` New functions :func:`~plotting.view_surf` and :func:`~plotting.view_img_on_surf` for interactive visualization of maps on the cortical surface in a web browser.

- :bdg-info:`Plotting` New functions :func:`~plotting.view_connectome` and :func:`~plotting.view_markers` for interactive visualization of connectomes and seed locations in 3D.

- :bdg-info:`Plotting` New function :func:`~plotting.view_img` for interactive visualization of volumes with 3 orthogonal cuts.

.. note::
    Function :func:`~plotting.view_img` was ``nilearn.plotting.view_stat_map`` in alpha and beta releases.

- :bdg-info:`Plotting` Function :func:`~plotting.find_parcellation_cut_coords` for extraction of coordinates on brain parcellations denoted as labels.

- :bdg-info:`Plotting` Function :func:`~plotting.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.**

- :func:`~datasets.fetch_surf_fsaverage`.

- :func:`~datasets.fetch_atlas_pauli_2017`.

- :func:`~datasets.fetch_neurovault_auditory_computation_task`.

- :func:`~datasets.fetch_neurovault_motor_task`.


ENHANCEMENTS
------------

- :bdg-success:`API` Function :func:`~image.clean_img` now accepts a mask to restrict the cleaning of the image, reducing memory load and computation time.

- :bdg-success:`API` ``NiftiMaskers`` now have a ``dtype`` parameter, by default keeping the same data type as the input data.

- :bdg-success:`API` The :meth:`~decoding.SearchLight.fit` method now accepts 4D niimgs.

- :bdg-dark:`Code` A cleaner layout and improved navigation for the website, with a better introduction.

- :bdg-dark:`Code` Dataset fetchers are now more reliable, less verbose.

- :bdg-dark:`Code` Anaconda link in the installation documentation updated.

- :bdg-secondary:`Maint` Lots of other fixes in documentation and examples.

- :bdg-secondary:`Maint` ``Scipy`` is listed as a dependency for Nilearn installation.

- :bdg-info:`Plotting` Displays by plotting functions can now add a scale bar (see :ref:`plotting`).

Changes
-------

- :bdg-dark:`Code` Default value of ``t_r`` in functions :func:`~signal.clean` and :func:`~image.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
----------

- :bdg-success:`API` Function :func:`~image.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).

- :bdg-info:`Plotting` Function :func:`~plotting.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
------------

- :bdg-success:`API` Function :func:`~image.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.

- :bdg-dark:`Code` Method :meth:`~decoding.SpaceNetRegressor.fit` raises a meaningful error in regression tasks if the target Y contains all 1s.

- :bdg-info:`Plotting` Function :func:`~plotting.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 :func:`~plotting.plot_stat_map`, and most parameters found in :func:`~plotting.plot_stat_map` are now supported in :func:`~plotting.view_img`.

Changes
-------

- :bdg-success:`API` Default value of ``t_r`` in functions :func:`~signal.clean` and :func:`~image.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.

- :bdg-success:`API` Order of filters in functions :func:`~signal.clean` and :func:`~image.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).

- :bdg-success:`API` Function :func:`~image.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.

- :bdg-info:`Plotting` Function :func:`~plotting.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 :func:`~plotting.plot_stat_map`, and most parameters found in :func:`~plotting.plot_stat_map` are now supported in :func:`~plotting.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
------------

- :bdg-info:`Plotting` Displays created by plotting functions can now add a scale bar to indicate the size in mm or cm (see :ref:`plotting`) (by `Oscar Esteban`_).

- :bdg-info:`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

- :bdg-dark:`Code` Less warnings and verbosity while using certain functions and during dataset downloads.

- :bdg-dark:`Code` Improved backend for the dataset fetchers means more reliable dataset downloads.

- :bdg-dark:`Code` Some datasets, such as the ICBM, are now compressed to take up less disk space.

- :bdg-secondary:`Maint` A cleaner layout and improved navigation for the website, with a better introduction.

Fixes
-----

- :bdg-success:`API` Method :meth:`decoding.SearchLight.fit` now accepts 4D niimgs (by `Dan Gale`_).

- :bdg-primary:`Doc` Brainomics dataset has been replaced in several examples.

- :bdg-secondary:`Maint` Lots of other fixes in documentation and examples.

- :bdg-info:`Plotting` ``plotting.view_markers.open_in_browser()`` in ``js_plotting_utils`` fixed.

Changes
-------

- :bdg-primary:`Doc` In function :func:`~regions.img_to_signals_labels`, the ``See Also`` section in documentation now also points to :class:`~maskers.NiftiLabelsMasker` and :class:`~maskers.NiftiMapsMasker`.

- :bdg-primary:`Doc` Anaconda link in the installation documentation updated.

- :bdg-secondary:`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``

- :bdg-info:`Plotting` New :ref:`interactive plotting functions <interactive-plotting>`, eg for use in a notebook.

Enhancements
------------

- :bdg-success:`API` All ``NiftiMaskers`` now have a ``dtype`` argument. For now the default behavior is to keep the same data type as the input data.

- :bdg-success:`API` New function :func:`~datasets.fetch_surf_fsaverage` to download either ``fsaverage`` or ``fsaverage5`` (Freesurfer cortical meshes).

- :bdg-success:`API` New function :func:`~datasets.fetch_atlas_pauli_2017` to download a recent subcortical neuroimaging atlas.

- :bdg-success:`API` New functions :func:`~datasets.fetch_neurovault_auditory_computation_task` and :func:`~datasets.fetch_neurovault_motor_task` for simple example data.

- :bdg-info:`Plotting` Displays created by plotting functions can now add a scale bar to indicate the size in mm or cm (see :ref:`plotting`) (by `Oscar Esteban`_).

- :bdg-info:`Plotting` New functions :func:`~plotting.view_surf` and :func:`~plotting.view_surf` and :func:`~plotting.view_img_on_surf` for interactive visualization of maps on the cortical surface in a web browser.

- :bdg-info:`Plotting` New functions :func:`~plotting.view_connectome` and :func:`~plotting.view_markers` to visualize connectomes and seed locations in 3D

- :bdg-info:`Plotting` New function ``nilearn.plotting.view_stat_map`` (renamed to :func:`~plotting.view_img` in stable release) for interactive visualization of volumes with 3 orthogonal cuts.

- :bdg-info:`Plotting` New function :func:`~plotting.find_parcellation_cut_coords` for extraction of coordinates on brain parcellations denoted as labels.

- :bdg-info:`Plotting` New function :func:`~plotting.find_probabilistic_atlas_cut_coords` for extraction of coordinates on brain probabilistic maps.


Changes
-------

- :bdg-dark:`Code` ``fsaverage5`` surface data files are now shipped directly with Nilearn (see :gh:`1705` for discussion).

- :bdg-danger:`Deprecation` Function ``nilearn.datasets.fetch_surf_fsaverage5`` is deprecated and will be removed in a future release. Use function :func:`~datasets.fetch_surf_fsaverage`, with the parameter ``mesh="fsaverage5"`` (the default) instead.

- :bdg-primary:`Doc` ``sklearn.cross_validation`` and ``sklearn.grid_search`` have been replaced by ``sklearn.model_selection`` in all the examples.

- :bdg-info:`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)
