.. currentmodule:: nilearn

.. include:: names.rst

0.9.2
=========

**Released August 2022**

HIGHLIGHTS
----------

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

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

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-secondary:`Maint` Conform seeding and docstrings in module ``_utils.data_gen`` (:gh:`3262` by `Yasmin Mzayek`_).
- Docstrings of module :mod:`~nilearn.glm.second_level` were improved (:gh:`3030` by `Nicolas Gensollen`_).
- :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-success:`API` Add ``n_elements_`` attribute to masker classes (:gh:`3311` by `Taylor Salo`_).
- :bdg-secondary:`Maint` Functions expecting string filesystem paths now also accept path-like objects (:gh:`3300` by `Yasmin Mzayek`_).
- :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` 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`_).
- :bdg-success:`API` :class:`~maskers.NiftiLabelsMasker` now accepts 1-dimensional arrays in its :meth:`~maskers.NiftiLabelsMasker.inverse_transform` method (:gh:`3322` by `Taylor Salo`_).

Changes
-------

- :bdg-info:`Plotting` Function :func:`~plotting.plot_carpet` argument ``cmap`` now respects behaviour 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`_).
- :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 :func:`~datasets.fetch_openneuro_dataset_index` is now deprecated in favor of the new :func:`~datasets.fetch_ds000030_urls` function (:gh:`3216` by `Taylor Salo`_).
- 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-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` 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`_).
