.. currentmodule:: nilearn

.. include:: names.rst

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.

-   :class:`~nilearn.surface.PolyMesh` (and :class:`~nilearn.surface.PolyData`)
    can be used to instantiate mesh (and respectively data) objects with both hemisphere.

-   :class:`~nilearn.surface.SurfaceImage` are objects that hold meshes and data for both hemispheres.

-   :class:`~nilearn.surface.SurfaceImage`, :class:`~nilearn.surface.PolyMesh`, :class:`~nilearn.surface.PolyData`
    allow you to load and save mesh or data from one hemisphere from or to a Gifti file.
    :class:`~nilearn.surface.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 :class:`~nilearn.surface.SurfaceImage` object.

-   To facilitate extracting data from those :class:`~nilearn.surface.SurfaceImage` objects,
    this new release also introduces :class:`~nilearn.maskers.SurfaceMasker` and :class:`~nilearn.maskers.SurfaceLabelsMasker`
    as counterparts to the volumetric :class:`~nilearn.maskers.NiftiMasker` and :class:`~nilearn.maskers.NiftiLabelsMasker`.

-   Several classes will already accept :class:`~nilearn.surface.SurfaceImage` and :class:`~nilearn.maskers.SurfaceMasker` as inputs:
    :class:`~nilearn.decoding.Decoder`, :class:`~nilearn.decoding.DecoderRegressor`,
    :class:`~nilearn.decoding.FREMClassifier`, :class:`~nilearn.decoding.FREMRegressor`,
    :class:`~nilearn.glm.first_level.FirstLevelModel`, :class:`~nilearn.glm.second_level.SecondLevelModel`.
    Moreover :func:`~nilearn.glm.first_level.first_level_from_bids` will be able to to build :class:`~nilearn.glm.first_level.FirstLevelModel`
    with the ``fsaverage5`` files generated by fmriprep to directly analysis with surface data.

.. topic:: **Code examples**

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

    -   :ref:`sphx_glr_auto_examples_00_tutorials_plot_surface_101.py`
    -   :ref:`sphx_glr_auto_examples_07_advanced_plot_surface_image_and_maskers.py`

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

    -   :ref:`sphx_glr_auto_examples_01_plotting_plot_surf_atlas.py`
    -   :ref:`sphx_glr_auto_examples_01_plotting_plot_3d_map_to_surface_projection.py`
    -   :ref:`sphx_glr_auto_examples_01_plotting_plot_surf_stat_map.py`
    -   :ref:`sphx_glr_auto_examples_02_decoding_plot_haxby_searchlight_surface.py`
    -   :ref:`sphx_glr_auto_examples_04_glm_first_level_plot_localizer_surface_analysis.py`
    -   :ref:`sphx_glr_auto_examples_07_advanced_plot_surface_bids_analysis.py`


Fixes
-----

- :bdg-dark:`Code` Add a new attribute ``_region_id_name`` to :class:`~nilearn.maskers.NiftiLabelsMasker` which is used to fix the issue with creating ``region_names_`` attribute (:gh:`4360` by `Mohammad Torabi`_).

- :bdg-dark:`Code` :func:`~nilearn.image.binarize_img` explicitly cast images to ``int8`` to avoid warnings about ``int64`` when working with ``float64`` images (:gh:`4498` by `Patrick Sadil`_).

- :bdg-dark:`Code` Make :func:`~nilearn.interfaces.fmriprep.load_confounds` return ``None`` for confounds when provided with an empty cleaning strategy (:gh:`4570` by `Micha Burkhardt`_).

- :bdg-dark:`Code` Fix previous Glover HRF implementation to fit the original paper (Glover, 1999) (:gh:`4452` by `Kun CHEN`_).

- :bdg-dark:`Code` Allow single 4D nifti as input to fit for SecondLevelModel (:gh:`4806` by `Rémi Gau`_).

- :bdg-dark:`Code` :func:`~nilearn.glm.first_level.first_level_from_bids` will look for images in ``MNI152NLin2009cAsym`` space if no space is provided (:gh:`4507` by `Rémi Gau`_).

- :bdg-dark:`Code` Fix bug that would lead ``compute_contrast`` to return 4D images even for one dimensional contrasts (:gh:`4413` by `Bertrand Thirion`_ and `Rémi Gau`_).

- :bdg-dark:`Code` ``first_level_from_bids`` will now return subjects in order (:gh:`4582` by `Tharun K`_).

- :bdg-secondary:`Maint` Fix several PTH errors flagged by ruff (:gh:`4620` by `Prakhar Jain`_ , and :gh:`4607`, :gh:`4612`, :gh:`4590`, :gh:`4618`, :gh:`4860` by `Hande Gözükan`_).

- :bdg-secondary:`Maint` Fix failing test in ``test_nilearn_standardize`` on MacOS 14 by adding trend in simulated data (:gh:`4411` by `Hao-Ting Wang`_).

- :bdg-info:`Plotting` Make sure that radiological view is applied when requested and not only when figures are annotated (:gh:`4556` by `Rémi Gau`_).

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

- :bdg-dark:`Code` Move SurfaceImage and associated classes from experimental to :mod:`~nilearn.surface` (:gh:`4723` by `Rémi Gau`_).

- :bdg-dark:`Code` Move SurfaceMasker and SurfaceLabelsMasker from experimental to :class:`~nilearn.maskers.SurfaceMasker` and to :class:`~nilearn.maskers.SurfaceLabelsMasker` (:gh:`4692` and :gh:`4714` by `Rémi Gau`_).

- :bdg-dark:`Code` :func:`~nilearn.datasets.load_nki` that returns the NKI dataset as a list of :obj:`~nilearn.surface.SurfaceImage` instances, :func:`~nilearn.datasets.load_fsaverage` that returns fsaverage meshes as a :obj:`dict` of :obj:`~nilearn.surface.PolyMesh` instances, and :func:`~nilearn.datasets.load_fsaverage_data` that returns fsaverage data (thickness, curvature...) as :obj:`~nilearn.surface.SurfaceImage` instances (:gh:`4693` by `Rémi Gau`_ based on original work by `Jerome Dockes`_).

- :bdg-dark:`Code` Improve input/output for :obj:`~nilearn.surface.SurfaceImage` by loading meshes from files on disk, loading data from files or Nifti object, and saving meshes to file (:gh:`4446`, :gh:`4593` by `Rémi Gau`_ and `Jerome Dockes`_).

- :bdg-dark:`Code` Allow list of :obj:`~nilearn.surface.SurfaceImage` as input to :class:`~nilearn.maskers.SurfaceMasker` fit and transform methods (:gh:`4719` by `Rémi Gau`_).

- :bdg-dark:`Code` Allow :class:`~nilearn.decoding.Decoder` and :class:`~nilearn.decoding.DecoderRegressor` to work with surface objects (:gh:`4205` by `Yasmin Mzayek`_ and `Rémi Gau`_).

- :bdg-dark:`Code` Allow :class:`~nilearn.decoding.FREMClassifier` and :class:`~nilearn.decoding.FREMRegressor` to work with surface objects (:gh:`4577` by `Yasmin Mzayek`_ and `Rémi Gau`_).

- :bdg-dark:`Code` Improve :func:`~nilearn.glm.first_level.first_level_from_bids` to look for and load ``fsaverage5`` data to easily run GLM on surface data (:gh:`4507` by `Rémi Gau`_).

- :bdg-dark:`Code` Improve :class:`~nilearn.glm.first_level.FirstLevelModel` and :class:`~nilearn.glm.second_level.SecondLevelModel` to accept :obj:`~nilearn.maskers.SurfaceMasker` and to fit directly :obj:`~nilearn.surface.SurfaceImage` (:gh:`4126`, :gh:`4715` by `Rémi Gau`_).

- :bdg-dark:`Code` Improved SearchLight with NIfTI Support, Mask Handling, and Reusable Transform Method (:gh:`4652` by `Prakhar Jain`_).

- :bdg-dark:`Code` Add footer to masker reports (:gh:`4307` by `Rémi Gau`_).

- :bdg-primary:`Doc` Add an option in :func:`~nilearn.datasets.fetch_atlas_aal` to fetch the latest AAL version, 3v2 (:gh:`4554` by `Jeremy Lefort-Besnard`_ and `Rémi Gau`_).

- :bdg-primary:`Doc` Add example showing how to compute hemisphere-wise connectivity for Yeo 17 networks (:gh:`4585` by `Victoria Shevchenko`_).

- :bdg-primary:`Doc` Add example to demonstrate the use of the new ``copy_header_from`` parameter in :func:`~nilearn.image.math_img` (:gh:`4392` by `Himanshu Aggarwal`_).

- :bdg-primary:`Doc` Add example to provide a clear understanding of the :class:`~nilearn.decoding.Decoder` object by demonstrating underlying steps via a Scikit-Learn pipeline. (:gh:`4437` by `Himanshu Aggarwal`_).

- :bdg-primary:`Doc` Adapt examples showing how to plot events and design matrices to show how to use parametric modulation. Also implement modulation of events in :func:`~nilearn.plotting.plot_event` (:gh:`4436` by `Rémi Gau`_).

- :bdg-info:`Plotting` Improve plotting contours for :class:`~nilearn.plotting.displays.PlotlySurfaceFigure` objects by adding :meth:`~nilearn.plotting.displays.PlotlySurfaceFigure.add_contours` method that accepts arguments to adjust line aesthetics (:gh:`3949` by `Patrick Sadil`_).

- :bdg-info:`Plotting` Add a new function :func:`~nilearn.plotting.plot_design_matrix_correlation` to plot the correlation between regressors of a GLM design matrix (:gh:`4467` by `Rémi Gau`_).

- :bdg-info:`Plotting` Add option to resize output image width ``width_view`` in :func:`~nilearn.plotting.view_img` (:gh:`4416` by `Alexandre Sayal`_).

- :bdg-info:`Plotting` Surface plotting functions :func:`~nilearn.plotting.view_surf`, :func:`~nilearn.plotting.plot_surf`, :func:`~nilearn.plotting.plot_surf_roi`, :func:`~nilearn.plotting.plot_surf_contours` and :func:`~nilearn.plotting.plot_surf_stat_map` can accept ``SurfaceImage`` as inputs making their ``surf_mesh`` parameter optional (:gh:`4688` by `Rémi Gau`_).


Changes
-------

- :bdg-success:`API` Remove the unused argument ``url`` from  :func:`~nilearn.datasets.fetch_localizer_contrasts`, :func:`~nilearn.datasets.fetch_localizer_calculation_task` and :func:`~nilearn.datasets.fetch_localizer_button_task` (:gh:`4273` by `Rémi Gau`_).

- :bdg-success:`API` Remove the unused argument ``rank`` from the constructor of :class:`~nilearn.glm.LikelihoodModelResults` (:gh:`4273` by `Rémi Gau`_).

- :bdg-success:`API` Remove the unused arguments ``upper_cutoff`` and ``exclude_zeros`` for :func:`~nilearn.masking.compute_multi_background_mask` (:gh:`4273` by `Rémi Gau`_).

- :bdg-success:`API` The default for ``force_resample`` in :func:`~nilearn.image.resample_img` and :func:`~nilearn.image.resample_to_img` will be set to ``True`` from Nilearn 0.13.0. (:gh:`4412` by `Rémi Gau`_ and `Anand Joshi`_)

- :bdg-success:`API` Allow users to control copying header to the output in :func:`~nilearn.image` functions and add future warning to copy headers by default in release 0.13.0 onwards (:gh:`4397` by `Himanshu Aggarwal`_).

- :bdg-dark:`Code` Warn the user when all volumes would be scrubbed when loading fmriprep confounds as this would lead to an empty ``sample_mask`` (:gh:`4558` by `Victoria Shevchenko`_).

- :bdg-dark:`Code` Throw error if ``sample_mask`` is empty when scrubbing an fMRI time series (:gh:`4558` by `Victoria Shevchenko`_).

- :bdg-dark:`Code` Implement argument ``sample_mask`` for :meth:`~nilearn.maskers.MultiNiftiMasker.transform_imgs` (:gh:`4273` by `Rémi Gau`_).

- :bdg-dark:`Code` Throw error in :func:`~nilearn.glm.first_level.first_level_from_bids` if unknown ``kwargs`` are passed (:gh:`4414` by `Michelle Wang`_).

- :bdg-dark:`Code` Improve logging by relying only on the Nilearn logger and adding optional support for rich printing if `rich <https://github.com/Textualize/rich>`_ is installed (:gh:`4469` and :gh:`4544` by `Rémi Gau`_).

- :bdg-dark:`Code` Parcellations returned by :class:`~nilearn.regions.Parcellations` will now be of type ``np.int32`` to avoid unnecessary warnings (:gh:`4555` by `Rémi Gau`_).

- :bdg-danger:`Deprecation` The parameter ``tr`` for :term:`Repetition time<TR>` will be replaced by ``t_r`` in the "HRF" functions in version 0.13.0. The affected functions are :func:`~nilearn.glm.first_level.glover_dispersion_derivative`, :func:`~nilearn.glm.first_level.glover_hrf`, :func:`~nilearn.glm.first_level.glover_time_derivative`, :func:`~nilearn.glm.first_level.spm_dispersion_derivative`, :func:`~nilearn.glm.first_level.spm_hrf`, :func:`~nilearn.glm.first_level.spm_time_derivative` (:gh:`4470` by `Rémi Gau`_).

- :bdg-danger:`Deprecation` The parameter ``ax`` will be replaced by ``axes`` in :func:`~nilearn.plotting.plot_contrast_matrix` and :func:`~nilearn.plotting.plot_design_matrix` in release 0.13.0. (:gh:`4476` by `Mudassir Chapra`_)

- :bdg-primary:`Doc` Add missing default values to docstrings (:gh:`4656`, :gh:`4659`, :gh:`4660` by `Anupriya Kumari`_).

- :bdg-primary:`Doc` Refactor design matrix and contrast formula for the two-sample T-test example in :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_two_sample_test.py` (:gh:`4407` by `Yichun Huang`_).

- :bdg-secondary:`Maint` Extend coverage for data generating utility functions (:gh:`4465` by `Sin Kim`_).

- :bdg-secondary:`Maint` Use ruff as formatter and linter instead of black, isort, flake8... (:gh:`4574` by `Rémi Gau`_).

- :bdg-secondary:`Maint` Reorder condition in internal call of :func:`~nilearn.image.resample_img` to skip checking of array values if interpolation is ``nearest`` (:gh:`4571` by `Jason Kai`_).

- :bdg-secondary:`Maint` Remove redundant sorting of ``np.unique(data)`` in internal call of :func:`~nilearn.image.resample_img` when checking array values (:gh:`4571` by `Jason Kai`_).

- :bdg-secondary:`Maint` Replace ``pytest.warns(DeprecationWarning)`` with ``pytest.deprecated_call()`` in tests (:gh:`4637` by `Victoria Shevchenko`_).

- :bdg-secondary:`Maint` Refactor ``nilearn.plotting.displays._projectors.add_graph`` to reduce its maxixmum length (:gh:`4635` by `Anupriya Kumari`_).
