clinicadl.io.bids.Bids¶

class clinicadl.io.bids.Bids(path: Path | str)[source]¶

A class to read BIDS datasets or BIDS derivatives (including CAPS).

The directory is expected to contain the mandatory dataset_description.json file, with the key "DatasetType" (whose value can be either "raw", "derivative" or "study"). Depending on the value of DatasetType, the expected organisation is different:

"raw": default organisation, the subject-specific folders are in the root directory. The tensors saved by ClinicaDL will be in derivatives/tensors.
"study": study organisation, the subject-specific folders are in sourcedata/raw. The tensors will be saved in derivatives/tensors.
"derivative":
- if "CAPSVersion" is in dataset_description.json, the directory will be understood as a CAPS. The subject-specific folders are expected in subjects, and the tensors will be saved in ../tensors.
- otherwise, it is interpreted as a BIDS derivative. The subject-specific folders are expected in the root directory, and the tensors will be saved in ../tensors.

Parameters:: directory (str | Path) – The path to the BIDS-like directory.

Examples

The default BIDS organisation:

bids                                <- this path is passed to the Bids object
├── dataset_description.json        <- contains "DatasetType": "raw"
├── sub-...
...
└── derivatives
    └── tensors                     <- where tensors will be saved

The “study” organization:

study                               <- this path is passed to the Bids object
├── dataset_description.json        <- contains "DatasetType": "study"
├── derivatives
│   └── tensors                     <- where tensors will be saved
└── sourcedata
    └── raw
        ├── sub-...

A BIDS derivative:

├── bids_derivative                 <- this path is passed to the Bids object
│   ├── dataset_description.json    <- contains "DatasetType": "derivative"
│   ├── sub-...
│   ...
└── tensors                         <- where tensors will be saved

A CAPS:

├── caps                            <- this path is passed to the Bids object
│   ├── dataset_description.json    <- contains "CAPSVersion"
│   └── subjects
│       ├── sub-...
│       ...
└── tensors                         <- where tensors will be saved

property participants_dir: Path¶: Where the subject-specific directories are stored.

property tensors_dir: Path¶: Where the tensors produced by ClinicaDL are saved.

get_path(file_type: BidsFileType, participant_id: str | None = None, session_id: str | None = None) → Path[source]¶

To get the path of a file in the BIDS-like directory.

The specifications of the file to find are given via a BidsFileType.

The user can also give a participant id and a session id if the wanted file is subject- and session- specific.

Parameters:

file_type (BidsFileType) – The specifications of the file to find.
participant_id (Optional[str], default=None) – The participant id (e.g., "sub-xxx"), if the file is subject-specific.
session_id (Optional[str], default=None) – The session id (e.g., "ses-xxx"), if the file is session-specific.

Returns:

Path – The file matching all the requirements.

Raises:

RuntimeError – If no corresponding file is found, or if several corresponding files are found.

Examples

bids
├── sub-001
│   ├── ses-M000
│   │   └── anat
│   │   │   └── sub-001_ses-M000_space-MNI152NLin2009cSym_res-1x1x1_T1w.nii
│   │   └── sub-001_ses-M000_scans.tsv
│   └── sub-001_sessions.tsv
...
└── space-MNI152NLin2009cSym_participants.tsv

>>> from clinicadl.io.bids import Bids, BidsFileType
>>> bids = Bids("bids")
>>> bids.get_path(
        file_type=BidsFileType(
            suffix="T1w",
            data_type="anat",
            with_entities={"space": "MNI152NLin2009cSym"},
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
Path("bids/sub-001/ses-M000/anat/sub-001_ses-M000_space-MNI152NLin2009cSym_res-1x1x1_T1w.nii")
>>> bids.get_path(
        file_type=BidsFileType(
            suffix="scans",
            extension=".tsv",
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
Path("bids/sub-001/ses-M000/sub-001_ses-M000_scans.tsv")
>>> bids.get_path(
        file_type=BidsFileType(
            suffix="sessions",
            extension=".tsv",
        ),
        participant_id="sub-001",
    )
Path("bids/sub-001/sub-001_sessions.tsv")
>>> bids.get_path(
        file_type=BidsFileType(
            suffix="participants",
            extension=".tsv",
            with_entities={"space": "MNI152NLin2009cSym"},
        ),
    )
Path("bids/space-MNI152NLin2009cSym_participants.tsv")

has_file_type(participant_id: str, session_id: str, file_type: BidsFileType) → bool[source]¶

To check if a participant has a file type for a specified session.

In practice, it will just check that get_path() returns a file.

Parameters:

participant_id (str) – The participant id (e.g., "sub-xxx").
session_id (str) – The session id (e.g., "ses-xxx").
file_type (BidsFileType) – The BidsFileType containing the specifications of the file to check.

Returns:

bool – Whether the participant has a file type for the specified session.

Raises:

RuntimeError – If several corresponding files are found.

Examples

bids
├── sub-001
│   ├── ses-M000
│   │   └── anat
│   │       ├── sub-001_ses-M000_space-MNI152NLin2009cSym_res-1x1x1_T1w.nii
│   │       └── sub-001_ses-M000_T1w.nii
...

>>> from clinicadl.io.bids import Bids, BidsFileType
>>> bids = Bids("bids")
>>> bids.has_file_type(
        file_type=BidsFileType(
            suffix="T1w",
            data_type="anat",
            with_entities={"space": "MNI152NLin2009cSym"},
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
True
>>> bids.has_file_type(
        file_type=BidsFileType(
            suffix="T1w",
            data_type="anat",
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
RuntimeError
>>> bids.has_file_type(
        file_type=BidsFileType(
            suffix="FLAIR",
            data_type="anat",
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
False

build_path(file_type: BidsFileType, participant_id: str | None = None, session_id: str | None = None) → Path[source]¶

Builds the path to the file associated to the input file type and the potential participant and session ids.

Parameters:

file_type (BidsFileType) –
The BidsFileType containing the specifications of the path to create.

Note

The entities in the without_entities attribute of the BidsFileType are not used here.
participant_id (Optional[str], default=None) – The participant id (e.g., "sub-xxx"), if the file must be subject-specific.
session_id (Optional[str], default=None) – The session id (e.g., "ses-xxx"), if the file must be subject-specific.

Returns:

Path – The built path.

Examples

>>> from clinicadl.io.bids import Bids, BidsFileType
>>> bids = Bids("bids")
>>> bids.build_path(
        file_type=BidsFileType(
            suffix="T1w",
            data_type="anat",
            with_entities={"space": "MNI152NLin2009cSym", "res": "1x1x1},
            extension="nii",
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
Path("bids/sub-001/ses-M000/anat/sub-001_ses-M000_space-MNI152NLin2009cSym_res-1x1x1_T1w.nii")
>>> bids.build_path(
        file_type=BidsFileType(
            suffix="scans",
            extension=".tsv",
        ),
        participant_id="sub-001",
        session_id="ses-M000",
    )
Path("bids/sub-001/ses-M000/sub-001_ses-M000_scans.tsv")
>>> bids.build_path(
        file_type=BidsFileType(
            suffix="sessions",
            extension=".tsv",
        ),
        participant_id="sub-001",
    )
Path("bids/sub-001/sub-001_sessions.tsv")
>>> bids.build_path(
        file_type=BidsFileType(
            suffix="participants",
            extension=".tsv",
            with_entities={"space": "MNI152NLin2009cSym"},
        ),
    )
Path("bids/space-MNI152NLin2009cSym_participants.tsv")

get_participants_sessions_with(file_type: BidsFileType) → set[tuple[str, str]][source]¶

Finds all the (participant, session) pairs which have a file matching a specified file type.

In practice, it will get all the (participant, session) pairs for which has_file_type() returns True.

Parameters:: file_type (BidsFileType) – The BidsFileType to match.
Returns:: set[tuple[str, str]] – The (participant, session) pairs that have the specified file type.

get_all_participants_sessions() → set[tuple[str, str]][source]¶

Finds all the (participant, session) pairs in the BIDS-like directory.

Returns:: set[tuple[str, str]] – The (participant, session) pairs.