[ENH] Add clinica iotools describe

[NicolasGensollen]

This PR proposes to add the command:

clinica iotools describe DATASET_PATH

which will basically parse the dataset_description.json file describing the dataset provided in order to display the information in a nice user-friendly way.

Here is a toy example with a BIDS and CAPS dataset having only their respective dataset_description.json file:

tree
.
├── bids
│   └── dataset_description.json
├── caps
│   └── dataset_description.json

We can describe them with the added tool:

[AliceJoubert]

Thanks for your work @NicolasGensollen ! I tried testing with a new conda environment. I get no issues with BIDS, but I found a CAPS for which it fails :

(describe) alice.joubert@ICM-COLLI-MP013 clinica % clinica iotools describe /Users/alice.joubert/clinicaQC/data/test_jump_subjects/caps
  + Exception Group Traceback (most recent call last):
  |   File "/Users/alice.joubert/anaconda3/envs/describe/bin/clinica", line 6, in <module>
  |     sys.exit(main())
  |              ^^^^^^
  |   File "/Users/alice.joubert/clinica/clinica/cmdline.py", line 113, in main
  |     cli()
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/click/core.py", line 1157, in __call__
  |     return self.main(*args, **kwargs)
  |            ^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/click/core.py", line 1078, in main
  |     rv = self.invoke(ctx)
  |          ^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
  |     return _process_result(sub_ctx.command.invoke(sub_ctx))
  |                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
  |     return _process_result(sub_ctx.command.invoke(sub_ctx))
  |                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/click/core.py", line 1434, in invoke
  |     return ctx.invoke(self.callback, **ctx.params)
  |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/click/core.py", line 783, in invoke
  |     return __callback(*args, **kwargs)
  |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/clinica/clinica/iotools/utils/cli.py", line 27, in describe
  |     _describe(dataset)
  |   File "/Users/alice.joubert/clinica/clinica/iotools/utils/describe.py", line 25, in describe
  |     ).from_file(Path(dataset) / "dataset_description.json")
  |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/clinica/clinica/utils/caps.py", line 304, in from_file
  |     return converter.structure(content, CAPSDatasetDescription)
  |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/cattrs/converters.py", line 332, in structure
  |     return self._structure_func.dispatch(cl)(obj, cl)
  |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |   File "<cattrs generated structure clinica.utils.caps.CAPSDatasetDescription>", line 33, in structure_CAPSDatasetDescription
  | cattrs.errors.ClassValidationError: While structuring CAPSDatasetDescription (1 sub-exception)
  +-+---------------- 1 ----------------
    | Exception Group Traceback (most recent call last):
    |   File "<cattrs generated structure clinica.utils.caps.CAPSDatasetDescription>", line 29, in structure_CAPSDatasetDescription
    |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/cattrs/converters.py", line 531, in _structure_list
    |     raise IterableValidationError(
    | cattrs.errors.IterableValidationError: While structuring typing.MutableSequence[clinica.utils.caps.CAPSProcessingDescription] (1 sub-exception)
    | Structuring class CAPSDatasetDescription @ attribute processing
    +-+---------------- 1 ----------------
      | Exception Group Traceback (most recent call last):
      |   File "/Users/alice.joubert/anaconda3/envs/describe/lib/python3.11/site-packages/cattrs/converters.py", line 521, in _structure_list
      |     res.append(handler(e, elem_type))
      |                ^^^^^^^^^^^^^^^^^^^^^
      |   File "<cattrs generated structure clinica.utils.caps.CAPSProcessingDescription>", line 39, in structure_CAPSProcessingDescription
      | cattrs.errors.ClassValidationError: While structuring CAPSProcessingDescription (2 sub-exceptions)
      | Structuring typing.MutableSequence[clinica.utils.caps.CAPSProcessingDescription] @ index 0
      +-+---------------- 1 ----------------
        | Traceback (most recent call last):
        |   File "<cattrs generated structure clinica.utils.caps.CAPSProcessingDescription>", line 30, in structure_CAPSProcessingDescription
        | KeyError: 'ClinicaVersion'
        | Structuring class CAPSProcessingDescription @ attribute clinica_version
        +---------------- 2 ----------------
        | Traceback (most recent call last):
        |   File "<cattrs generated structure clinica.utils.caps.CAPSProcessingDescription>", line 35, in structure_CAPSProcessingDescription
        | KeyError: 'Dependencies'
        | Structuring class CAPSProcessingDescription @ attribute dependencies
        +------------------------------------

Since there is a chance the .json is not probably formatted, here is what it looks like :

{
    "Name": "8b337e7e-fa9c-4fb9-b056-cbb234713da2",
    "BIDSVersion": "1.7.0",
    "CAPSVersion": "1.0.0",
    "DatasetType": "derivative",
    "Processing": [
        {
            "Name": "t1-linear",
            "Date": "2024-09-19T14:55:47.789074",
            "Author": "alice.joubert",
            "Machine": "ICM-COLLI-MP013",
            "InputPath": "/Users/alice.joubert/clinicaQC/data/test_jump_subjects/bids"
        }
    ]
}

[NicolasGensollen]

Thanks for the review @AliceJoubert !

Is this a dataset_description.json file that you generated with clinica some time ago (i.e. before we merged #1275) ?

#1275 modified the format of this file by adding a Dependencies entry which seems to be missing from your file.
Since this was merged, when writing these files, this field is supposed to be automatically written, so you should definitely have it.

Since we never published a version of Clinica with the temporary format (i.e. the one without the Dependencies key) we don't have to worry about being backward compatible. This means that you'd need to regenerate the dataset_description.json file in order to test the describe tool.

Does this make sense ?

[AliceJoubert]

You're right ! Sorry for the noise. LGTM then 👍

[NicolasGensollen]

Alright ! Thanks for the review @AliceJoubert !
Merging then...