
.. currentmodule:: nilearn

.. include:: names.rst

0.7.0
=====

**Released November 2020**

HIGHLIGHTS
----------

- 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`_).

- 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`_).

- 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`_).

- 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
---
- Nilearn now includes the functionality of `Nistats <https://nistats.github.io>`_.
- 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.
- 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.
- 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.
- Plotting function :func:`nilearn.plotting.plot_roi` can now plot ROIs
  in contours with `view_type` argument.
- 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.
- 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.
- :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``.
- 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.
- The position annotation on the plot methods now implements the `decimals` option
  to enable annotation of a slice coordinate position with the float.
- New example in
  :ref:`sphx_glr_auto_examples_02_decoding_plot_haxby_searchlight_surface.py`
  to demo how to do cortical surface-based searchlight decoding with Nilearn.
- confounds or additional regressors for design matrix can be specified as
  numpy arrays or pandas DataFrames interchangeably
- The decomposition estimators will now accept argument `per_component`
  with `score` method to explain the variance for each component.


Fixes
-----

- :class:`nilearn.maskers.NiftiLabelsMasker` no longer ignores its `mask_img`
- :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.
- the default background (MNI template) in plotting functions now has the
  correct orientation; before left and right were inverted.
- first level modelling can deal with regressors
  having multiple events which share onsets or offsets.
  Previously, such cases could lead to an erroneous baseline shift.
- :func:`nilearn.mass_univariate.permuted_ols` no longer returns transposed
  t-statistic arrays when no permutations are performed.
- Fix decomposition estimators returning explained variance score as 0.
  based on all components i.e., when per_component=False.
- Fix readme file of the Destrieux 2009 atlas.


Changes
-------

- Function ``nilearn.datasets.fetch_cobre`` has been deprecated and will be
  removed in release 0.9 .
- Function ``nilearn.plotting.plot_connectome_strength`` has been deprecated and will
  be removed in release 0.9 .

- :class:`nilearn.connectome.ConnectivityMeasure` can now remove
  confounds in its transform step.
- :func:`nilearn.surface.vol_to_surf` can now sample between two nested surfaces
  (eg white matter and pial surfaces) at specific cortical depths
- :func:`nilearn.datasets.fetch_surf_fsaverage` now also downloads white matter
  surfaces.
