[FIX] properly infer slice_time_ref from BIDS derivatives (#3605)

* checks for tr and slice time

* improve getting t_r and slice_time_ref

* refactor

* refactor

* refactor

* [DATALAD] Recorded changes

* refactor

* refactor

* refactor

* fix

* add more tests

* fix

* use pytest fixture

* add indent for readability

* update changelog

* Apply suggestions from code review

Co-authored-by: Taylor Salo <tsalo90@gmail.com>

* fix tests

* add verbose level to reduce number of warnings

* rm type annotations

* extend coverage

* Apply suggestions from code review

Co-authored-by: Yasmin <63292494+ymzayek@users.noreply.github.com>
Co-authored-by: bthirion <bertrand.thirion@inria.fr>

* [DATALAD] Recorded changes

* rm type hints

* rm warnings

* refactor get_bids_file

* make xfail strict

* fix typo

* infer metadata all the time

* swith back to original default

* use new default in most tests to reduce number of warnings

* Apply suggestions from code review

* update deprecation version number

* update doc

* add test for depreaction warning

* lint

* lint

* add test for waning

* lint

* update doc

* update doc

* fix flake8

* add doc strings

* Update nilearn/_utils/tests/test_data_gen.py

Co-authored-by: Yasmin <63292494+ymzayek@users.noreply.github.com>

* typo

---------

Co-authored-by: Taylor Salo <tsalo90@gmail.com>
Co-authored-by: Yasmin <63292494+ymzayek@users.noreply.github.com>
Co-authored-by: bthirion <bertrand.thirion@inria.fr>

.flake8

@@ -7,6 +7,7 @@ exclude =
     build,
     dist,
 	nilearn/externals/tempita
+	nilearn_cache
 --select = D,E,F,W,C90
 docstring-convention = numpy
 max-line-length = 79

doc/changes/latest.rst

@@ -17,6 +17,8 @@ NEW
 Fixes
 -----
 
+- Improve how :func:`~.glm.first_level.first_level_from_bids` handles fetching slice timing metadata and add additional input validation. In release ``0.12`` the default `slice_time_ref` will be `None` instead of `0` (:gh:`3605` by `Rémi Gau`_).
+
 - Fixes several bugs in :func:`~glm.first_level.first_level_from_bids`. Refactors :func:`~glm.first_level.first_level_from_bids` and ``nilearn._utils.data_gen.create_fake_bids_dataset``. (:gh:`3525` by `Rémi Gau`_).
 
 - Change calculation of TR in :func:`~.glm.first_level.compute_regressor` to be more precise (:gh:`3362` by `Anne-Sophie Kieslinger`_)

nilearn/_utils/data_gen.py

@@ -1,15 +1,14 @@
 """
 Data generation utilities
 """
-
 from __future__ import annotations
 
 import itertools
+
 import json
 import string
 
 from pathlib import Path
-from typing import Any
 
 import numpy as np
 import pandas as pd
@@ -751,6 +750,52 @@ def basic_confounds(length, random_state=0):
     return confounds
 
 
+def _add_metadata_to_bids_dataset(bids_path,
+                                  metadata,
+                                  json_file=None):
+    """Add JSON file with specific metadata to BIDS dataset.
+
+    Note no "BIDS validation" are performed on the metadata, 
+    or on the file path.
+
+    Parameters
+    ----------
+    bids_path : :obj:`str` or :obj:`pathlib.Path`
+        Path to the BIDS dataset where the file is to be added.
+
+    metadata : :obj:`dict`
+        Dictionary with metadata to be added to the JSON file.
+
+    json_file :  :obj:`str` or :obj:`pathlib.Path`, default=None
+        Path to the json file relative to the root of the BIDS dataset.
+        If no json_file is specified, a default path is used 
+        that is meant to work well with the defaults of 
+        `create_fake_bids_dataset`: 
+        this is meant to facilitate modifying datasets used during tests.
+
+    Returns
+    -------
+    pathlib.Path
+        Full path to the json file created.
+    """    
+    if json_file is None:
+        json_file = (
+            Path(bids_path) / 
+            'derivatives' / 
+            'sub-01' / 
+            'ses-01' / 
+            'func' / 
+            'sub-01_ses-01_task-main_run-01_space-MNI_desc-preproc_bold.json'
+        )
+    else:
+        json_file = Path(bids_path) / json_file
+
+    with open(json_file, 'w') as f:
+        json.dump(metadata, f)
+
+    return json_file
+
+
 def generate_random_img(
     shape,
     affine=np.eye(4),

nilearn/_utils/tests/test_data_gen.py

@@ -1,8 +1,7 @@
 """Tests for the data generation utilities."""
-
 from __future__ import annotations
 
-from pathlib import Path
+import json
 
 import numpy as np
 import pytest
@@ -15,6 +14,39 @@
 )
 from nilearn.image import get_data
 
+from nilearn._utils.data_gen import _add_metadata_to_bids_dataset
+
+
+def test_add_metadata_to_bids_derivatives_default_path(tmp_path):
+    """Check the filename created is the default value \
+    of _add_metadata_to_bids_dataset."""
+    target_dir = tmp_path / 'derivatives' / 'sub-01' / 'ses-01' / 'func'
+    target_dir.mkdir(parents=True)
+    json_file = _add_metadata_to_bids_dataset(bids_path=tmp_path,
+                                              metadata={"foo": "bar"})
+    assert json_file.exists()
+    assert (json_file.name == 
+            'sub-01_ses-01_task-main_run-01_space-MNI_desc-preproc_bold.json')
+    with open(json_file, 'r') as f:
+        metadata = json.load(f)
+        assert metadata == {"foo": "bar"}
+
+
+def test_add_metadata_to_bids_derivatives_with_json_path(tmp_path):
+    # bare bone smoke test
+    target_dir = tmp_path / 'derivatives' / 'sub-02' 
+    target_dir.mkdir(parents=True)
+    json_file = 'derivatives/sub-02/sub-02_task-main_bold.json'
+    json_file = _add_metadata_to_bids_dataset(bids_path=tmp_path,
+                                              metadata={"foo": "bar"},
+                                              json_file=json_file)
+    assert json_file.exists()
+    assert (json_file.name == 
+            'sub-02_task-main_bold.json')
+    with open(json_file, 'r') as f:
+        metadata = json.load(f)
+        assert metadata == {"foo": "bar"}
+
 
 def _bids_path_template(
     task,