[ENH] Enable the clinica_file_reader to work with run numbers

[NicolasGensollen]

Description

The issue being addressed

This is a work-in-progress-PR to analyze how we could support run numbers in Clinica.

Some of our converters like GENFI2BIDS or OASIS32BIDS already output files with run numbers and pipelines have different behaviors in regard of this unsupported entity.

The proposed solution

Most of the related logic lies around the clinica_file_reader function which relies on _read_files_parallel or _read_files_sequential. These two function take as input a BIDS/CAPS folder, a subject, a session, and a query, and they expect to get a single file based on these inputs.

If the input BIDS dataset contains some files with run numbers and if the query captures the different runs of a given acquisition, then the file reader will raise an error saying that too many files were found.

This PR investigates how we could allow the file reader to handle the fact that a query returns multiple files. If this happens, we need to verify that the files found only differ through their run numbers. Otherwise, this is indeed an error and we raise as before.

If the files are really different runs, then I believe it makes sense to select only one of the runs to proceed (otherwise I'm not sure what would happen. I suspect the pipelines will crash with unexpected number of files in the input nodes, but we could try to see for real...).

This selection could be done in multiple ways:

• Use QC information if available (ideal solution but requires some work. Also, since this information isn't always present, we need a default solution).
• Enable the user to specify which run to use (should be possible through a CLI option I suppose, but same issue, we need a default way of handling the runs if the user didn't specify anything...).
• Pick the latest run assuming it is the best (obviously can be False but should be a not-too-bad heuristic. This is what this PR proposes to implement).

Example

Assuming a BIDS input dataset like this:

├── dataset_description.json
├── sub-02
│   └── ses-M000
│       └── anat
│           ├── sub-02_ses-M000_run-01_T1w.nii.gz
│           └── sub-02_ses-M000_run-02_T1w.nii.gz
└── sub-ADNI022S0004
    └── ses-M000
        └── anat
            └── sub-ADNI022S0004_ses-M000_T1w.nii.gz

This is what the file reader does with the proposed implementation.

In [1]: from clinica.utils.inputs import clinica_file_reader

In [2]: from clinica.utils.input_files import T1W_NII

In [3]: anat_files = clinica_file_reader(["sub-02"], ["ses-M000"], "/Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/", T1W_NII)
More than one run were found for subject sub-02 and session ses-M000 :

- /Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-01_T1w.nii.gz
- /Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-02_T1w.nii.gz

Clinica will proceed with the latest run available, that is

-/Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-02_T1w.nii.gz.

In [4]: anat_files
Out[4]:
(['/Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-02_T1w.nii.gz'],
 'Clinica encountered 0 problem(s) while getting T1w MRI:\n')

In [5]: anat_files = clinica_file_reader(["sub-ADNI022S0004"], ["ses-M000"], "/Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/", T1W_NII)

In [6]: anat_files
Out[6]:
(['/Users/nicolas.gensollen/GitRepos/clinica_data_ci/data_ci/T1Linear/in/bids/sub-ADNI022S0004/ses-M000/anat/sub-ADNI022S0004_ses-M000_T1w.nii.gz'],
 'Clinica encountered 0 problem(s) while getting T1w MRI:\n')

Thoughts, comments, suggestions, or ideas are more than welcome !

[NicolasGensollen]

The linked data PR proposes to add some multi-run data for T1Linear and FLAIRLinear.

Assuming the input for T1Linear:

├── dataset_description.json
├── sub-02
│   └── ses-M000
│       └── anat
│           ├── sub-02_ses-M000_run-01_T1w.nii.gz
│           ├── sub-02_ses-M000_run-02_T1w.nii.gz
│           └── sub-02_ses-M000_run-03_T1w.nii.gz

The user should obtain:

├── sub-02
│   └── ses-M000
│       └── t1_linear
│           ├── sub-02_ses-M000_run-03_space-MNI152NLin2009cSym_desc-Crop_res-1x1x1_T1w.nii.gz
│           ├── sub-02_ses-M000_run-03_space-MNI152NLin2009cSym_res-1x1x1_T1w.nii.gz
│           └── sub-02_ses-M000_run-03_space-MNI152NLin2009cSym_res-1x1x1_affine.mat

Where run-03 was selected by the file reader as the latest available run.

Without the code from this PR, the user should face the following kind of error:

E           clinica.utils.exceptions.ClinicaBIDSError: Clinica faced error(s) while trying to read files in your BIDS directory.
E           Clinica encountered 1 problem(s) while getting T1w MRI:
E           	*  (sub-02 | ses-M000): More than 1 file found:
E           		/Users/ci-aramis-clinica/data/clinica/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-03_T1w.nii.gz
E           		/Users/ci-aramis-clinica/data/clinica/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-01_T1w.nii.gz
E           		/Users/ci-aramis-clinica/data/clinica/clinica_data_ci/data_ci/T1Linear/in/bids/sub-02/ses-M000/anat/sub-02_ses-M000_run-02_T1w.nii.gz

[NicolasGensollen]

I think this is ready for reviews.

[ghisvail]

LGTM, with a small suggestion in regex parsing.

[NicolasGensollen]

Thanks for the review @ghisvail !
Let's merge...