.. currentmodule:: nilearn

.. include:: names.rst

0.9.2
=========

**Released August 2022**

HIGHLIGHTS
----------

- :bdg-success:`API` :func:`~mass_univariate.permuted_ols` and :func:`~glm.second_level.non_parametric_inference` now support :term:`TFCE` statistic (:gh:`3196` by `Taylor Salo`_).

- :bdg-success:`API` :func:`~mass_univariate.permuted_ols` and :func:`~glm.second_level.non_parametric_inference` now support cluster-level Family-wise error correction (:gh:`3181` by `Taylor Salo`_).

- :bdg-success:`API` :func:`~interfaces.bids.save_glm_to_bids` has been added, which writes model outputs to disk according to BIDS convention (:gh:`2715` by `Taylor Salo`_).

- :bdg-primary:`Doc` Updated docs with a new theme using `furo <https://github.com/pradyunsg/furo>`_ (:gh:`3125` by `Alexis Thual`_).

NEW
---

- :bdg-success:`API` :func:`~interfaces.bids.save_glm_to_bids` has been added, which writes model outputs to disk according to BIDS convention (:gh:`2715` by `Taylor Salo`_).

- :bdg-success:`API` :func:`~mass_univariate.permuted_ols` and :func:`~glm.second_level.non_parametric_inference` now support :term:`TFCE` statistic (:gh:`3196` by `Taylor Salo`_).

- :bdg-success:`API` :func:`~mass_univariate.permuted_ols` and :func:`~glm.second_level.non_parametric_inference` now support cluster-level Family-wise error correction (:gh:`3181` by `Taylor Salo`_).

- :bdg-primary:`Doc` Updated docs with a new theme using `furo <https://github.com/pradyunsg/furo>`_ (:gh:`3125` by `Alexis Thual`_).

Fixes
-----

- :bdg-success:`API` :func:`~plotting.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 (:gh:`3241` by `Jerome Dockes`_).

- :bdg-success:`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 :class:`~glm.first_level.FirstLevelModel` (:gh:`3283` by `Matthieu Joulot`_).

- :bdg-dark:`Code` :func:`~surface.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 (:gh:`3235` by `Yasmin Mzayek`_).

- :bdg-dark:`Code` Function :func:`~image.resample_img` now warns the user if the provided image has an ``sform`` code equal to 0 or None  (:gh:`3284` by `Matthieu Joulot`_).

- :bdg-dark:`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 (:gh:`3297` by `Kun CHEN`_).

- :bdg-dark:`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 :func:`~nilearn.signal.butterworth` returns an unfiltered signal with a warning (:gh:`3293` by `Yasmin Mzayek`_).

- :bdg-primary:`Doc` Fix the typographic error on the page :ref:`sphx_glr_auto_examples_04_glm_first_level_plot_adhd_dmn.py` (:gh:`3337` by `Sachin Patalasingh`_).

- :bdg-secondary:`Maint` Fix ``_NEUROVAULT_BASE_URL`` and ``_NEUROSYNTH_FETCH_WORDS_URL`` in ``nilearn/datasets/neurovault.py`` by using https instead of http (:gh:`3281` by `Manon Pietrantoni`_).

- :bdg-secondary:`Maint` Convert references in ``nilearn/mass_univariate/permuted_least_squares.py`` to use bibtex format (:gh:`3222` by `Yasmin Mzayek`_).

- :bdg-secondary:`Maint` Update Craddock 2012 parcellation url in ``nilearn/datasets/atlas.py`` (:gh:`3233` by `Vasco Diogo`_)

- :bdg-info:`Plotting` :func:`~plotting.plot_markers` can now plot a single scatter point (:gh:`3255` by `Caglar Cakan`_).

- :bdg-info:`Plotting` Fix title display for :func:`~plotting.plot_surf_stat_map`. The ``title`` argument does not set the figure title anymore but the axis title. (:gh:`3220` by `Raphael Meudec`_).

- :bdg-info:`Plotting` The parameter ``alpha`` is now correctly passed to :func:`~plotting.plot_glass_brain` in :func:`~plotting.plot_connectome` (:gh:`3306` by `Koen Helwegen`_).

- :bdg-info:`Plotting` Fix plotting of background image in :func:`~nilearn.plotting.view_img` when the background is not the MNI template (:gh:`3312` by `Jerome Dockes`_).

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

- :bdg-success:`API` Add ``sample_masks`` to :meth:`~glm.first_level.FirstLevelModel.fit` for censoring time points (:gh:`3193` by `Hao-Ting Wang`_).

- :bdg-success:`API` Function :func:`~glm.first_level.run_glm` and class :class:`~glm.first_level.FirstLevelModel` now accept a ``random_state`` parameter, which allows users to seed the ``KMeans`` cluster model used to estimate AR coefficients. (:gh:`3185` by `Sami Jawhar`_).

- :bdg-success:`API` :class:`~maskers.NiftiLabelsMasker` now accepts 1-dimensional arrays in its :meth:`~maskers.NiftiLabelsMasker.inverse_transform` method (:gh:`3322` by `Taylor Salo`_).

- :bdg-success:`API` Add ``n_elements_`` attribute to masker classes (:gh:`3311` by `Taylor Salo`_).

- :bdg-dark:`Code` In :func:`~reporting.get_clusters_table`, when the center of mass of a binary cluster falls outside the cluster, report the nearest within-cluster voxel instead (:gh:`3292` by `Connor Lane`_).

- :bdg-primary:`Doc` Docstrings of module :mod:`~nilearn.glm.second_level` were improved (:gh:`3030` by `Nicolas Gensollen`_).

- :bdg-primary:`Doc` Contributing guidelines now include a recommendation to run flake8 locally on the branch diff with main (:gh:`3317` by `Yasmin Mzayek`_).

- :bdg-secondary:`Maint` Functions expecting string filesystem paths now also accept path-like objects (:gh:`3300` by `Yasmin Mzayek`_).

- :bdg-secondary:`Maint` Conform seeding and docstrings in module ``_utils.data_gen`` (:gh:`3262` by `Yasmin Mzayek`_).

- :bdg-secondary:`Maint` Improvements to :func:`~mass_univariate.permuted_ols` and :func:`~glm.second_level.non_parametric_inference` with :term:`TFCE` statistic runtime (:gh:`3333` by `Sage Hahn`_).

Changes
-------

- :bdg-dark:`Code` Boolean input data in :func:`~image.new_img_like` now defaults to ``np.uint8`` instead of ``np.int8`` (:gh:`3286` by `Yasmin Mzayek`_).

- :bdg-danger:`Deprecation` Function :func:`~datasets.fetch_surf_fsaverage` no longer supports the previously deprecated option ``fsaverage5_sphere`` (:gh:`3229` by `Taylor Salo`_).

- :bdg-danger:`Deprecation` Classes :class:`~glm.regression.RegressionResults`, :class:`~glm.regression.SimpleRegressionResults`, :class:`~glm.regression.OLSModel`, and :class:`~glm.model.LikelihoodModelResults` no longer support deprecated shortened attribute names, including ``df_resid``, ``wdesign``, ``wresid``, ``norm_resid``, ``resid``, and ``wY`` (:gh:`3229` by `Taylor Salo`_).

- :bdg-danger:`Deprecation` Function ``fetch_openneuro_dataset_index`` is now deprecated in favor of the new :func:`~datasets.fetch_ds000030_urls` function (:gh:`3216` by `Taylor Salo`_).

- :bdg-danger:`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`` (:gh:`3322` by `Taylor Salo`_).

- :bdg-primary:`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, :func:`~image.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. (:gh:`3227` by `Jerome Dockes`_)

- :bdg-secondary:`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 (:gh:`3274` by `David G Ellis`_).

- :bdg-secondary:`Maint` Private submodules, functions, and classes from the :mod:`~nilearn.decomposition` module now start with a "_" character to make it clear that they are not part of the public API (:gh:`3141` by `Nicolas Gensollen`_).

- :bdg-secondary:`Maint` Convert references in ``nilearn/glm/regression.py`` and ``nilearn/glm/thresholding.py`` to use footcite/footbibliography (:gh:`3302` by `Ahmad Chamma`_).

- :bdg-info:`Plotting` Function :func:`~plotting.plot_carpet` argument ``cmap`` now respects behavior specified by docs and changes the color of the carpet_plot. Changing the label colors is now delegated to a new variable ``cmap_labels`` (:gh:`3209` by `Daniel Gomez`_).
