
.. currentmodule:: nilearn

.. include:: names.rst

0.7.0
=====

**Released November 2020**

HIGHLIGHTS
----------

- :bdg-success:`API` Nilearn now includes the functionality of `Nistats <https://nistats.github.io>`_ as :mod:`nilearn.glm`. This module is experimental, hence subject to change in any future release. (:gh:`2299`, :gh:`2304`, and :gh:`2307` by `Kshitij Chawla`_, and :gh:`2509` by `Binh Nguyen`_).

- :bdg-success:`API` New classes :class:`nilearn.decoding.Decoder` (for :term:`classification`) and :class:`nilearn.decoding.DecoderRegressor` (for :term:`regression`) implement a model selection scheme that averages the best models within a cross validation loop (:gh:`2000` by `Binh Nguyen`_).

- :bdg-success:`API` New classes :class:`nilearn.decoding.FREMClassifier` (for :term:`classification`) and :class:`nilearn.decoding.FREMRegressor` (for :term:`regression`) extend the :class:`~decoding.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 (:gh:`2327` by `Thomas Bazeille`_).

- :bdg-info:`Plotting` New plotting functions:

  * :func:`~plotting.plot_event` to visualize events file.
  * :func:`~plotting.plot_roi` can now plot ROIs in contours with ``view_type`` argument.
  * :func:`~plotting.plot_carpet` generates a "carpet plot" (also known as a "Power plot" or a "grayplot")
  * :func:`~plotting.plot_img_on_surf` generates multiple views of :func:`~plotting.plot_surf_stat_map` in a single figure.
  * :func:`~plotting.plot_markers` shows network nodes (markers) on a glass brain template
  * :func:`~plotting.plot_surf_contours` plots the contours of regions of interest on the surface

.. warning::

  Minimum required version of ``Joblib`` is now ``0.12``.


NEW
---

- :bdg-success:`API` Nilearn now includes the functionality of `Nistats <https://nistats.github.io>`_.

- :bdg-success:`API` New decoder object :class:`nilearn.decoding.Decoder` (for classification) and  :class:`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.

- :bdg-success:`API` New FREM object :class:`nilearn.decoding.FREMClassifier` (for classification) and :class:`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.

- :bdg-success:`API` confounds or additional regressors for design matrix can be specified as numpy arrays or pandas DataFrames interchangeably

- :bdg-success:`API` The decomposition estimators will now accept argument ``per_component`` with ``score`` method to explain the variance for each component.

- :bdg-primary:`Doc` New example in :ref:`sphx_glr_auto_examples_02_decoding_plot_haxby_searchlight_surface.py` to demo how to do cortical surface-based searchlight decoding with Nilearn.

- :bdg-info:`Plotting` Plot events file Use :func:`nilearn.plotting.plot_event` to visualize events file. The function accepts the :term:`BIDS` events file read using ``pandas`` utilities.

- :bdg-info:`Plotting` Plotting function :func:`nilearn.plotting.plot_roi` can now plot ROIs in contours with ``view_type`` argument.

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

- :bdg-info:`Plotting` New plotting function :func:`nilearn.plotting.plot_img_on_surf` generates multiple views of :func:`nilearn.plotting.plot_surf_stat_map` in a single figure.

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

- :bdg-info:`Plotting` New plotting function :func:`nilearn.plotting.plot_surf_contours` plots the contours of regions of interest on the surface, optionally overlaid on top of a statistical map.

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

- :bdg-dark:`Code` :class:`nilearn.maskers.NiftiLabelsMasker` no longer ignores its ``mask_img``

- :bdg-dark:`Code` :func:`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.

- :bdg-dark:`Code` first level modeling can deal with regressors having multiple events which share onsets or offsets. Previously, such cases could lead to an erroneous baseline shift.

- :bdg-dark:`Code` Fix decomposition estimators returning explained variance score as 0. based on all components i.e., when ``per_component=False``.

- :bdg-danger:`Deprecation` :func:`nilearn.mass_univariate.permuted_ols` no longer returns transposed t-statistic arrays when no permutations are performed.

- :bdg-primary:`Doc` Fix readme file of the Destrieux 2009 atlas.

- :bdg-info:`Plotting` the default background (MNI template) in plotting functions now has the correct orientation; before left and right were inverted.

Changes
-------

- :bdg-dark:`Code` :class:`nilearn.connectome.ConnectivityMeasure` can now remove confounds in its transform step.

- :bdg-dark:`Code` :func:`nilearn.surface.vol_to_surf` can now sample between two nested surfaces (eg white matter and pial surfaces) at specific cortical depths

- :bdg-dark:`Code` :func:`nilearn.datasets.fetch_surf_fsaverage` now also downloads white matter surfaces.

- :bdg-danger:`Deprecation` Function ``nilearn.plotting.plot_connectome_strength`` has been deprecated and will be removed in release 0.9 .

- :bdg-danger:`Deprecation` Function ``nilearn.datasets.fetch_cobre`` has been deprecated and will be removed in release 0.9 .
