clinicaio.image_query.ImageQuery

clinicaio.image_query.ImageQuery#

class clinicaio.image_query.ImageQuery(*, subjects: Iterable[clinicaio.types.SubjectId] | None = None, sessions: Iterable[clinicaio.types.SessionId] | None = None, sub_ses: list[tuple[clinicaio.types.SubjectId, clinicaio.types.SessionId]] | dict[clinicaio.types.SubjectId, set[clinicaio.types.SessionId]] | None = None, data_type: clinicaio.types.DataType | str | None = None, entities: clinicaio.entities.EntitiesLike = None, suffix: str | None = None)#

Creates an image query filtering data structure for later use with clinicaio.dataset.BIDSDataset.query_images(), clinicaio.dataset.BIDSDataset.query_images_nifti_paths() or clinicaio.dataset.BIDSDataset.query_images_companions_paths() for example.

Parameters:

  • subjects (Optional[Iterable[clinicaio.types.SubjectId]]) – The subjects (by their IDs) to specifically keep. If empty, includes all of them.

  • session – The subjects (by their IDs) to specifically keep. If empty, includes all of them. Together with the subjects, it forms a cartesian-product for filtering, meaning that subjects and sessions are filtered independently, not pair-wise.

  • sub_ses (Optional[list[tuple[clinicaio.types.SubjectId, clinicaio.types.SessionId]] | dict[clinicaio.types.SubjectId, set[clinicaio.types.SessionId]]]) – The subject/session pairs to keep. This is a cross-product, meaning that only a given subject/session pair matching one of the exact provided ones will match. It must not be specified at the same time as subjects or sessions.

  • data_type (Optional[clinicaio.types.DataType | str]) – The data type of the image. If None, all of them are kept.

  • entities (clinicaio.entities.EntitiesLike) – The entities to specifically look for in the images. For convenience it can also be specified either in a dictionary form, or a list of "<key>-<value>", or as a fully-formed BIDS entities string "<key1>-<value1>_..._<keyN>-<valueN>".

  • suffix (Optional[str]) – The suffix to specifically look for in the images. If None, all of them are kept. This is a wildcard pattern using the syntax supported by fnmatch.fnmatchcase().

  • sessions (Optional[Iterable[clinicaio.types.SessionId]])

Raises:

ValueError – if both query.sub_ses and either query.subjects``or ``query.sessions are specified at the same time: the former operates on a cross-product basis, while the later two operate on a cartesian-product when combined, so it does not make much sense to have both at the same time

Examples

ImageQuery(subjects=["sub-ADNI027S0074"])
ImageQuery(subjects={"sub-ADNI027S0074"})
ImageQuery(sub_ses={"sub-ADNI027S0074": {"ses-A"}})
ImageQuery(sub_ses={"sub-ADNI027S0074": {"ses-A", "ses-B"}})
ImageQuery(sub_ses=[("sub-ADNI027S0074", "ses-A"), ("sub-AIBL1234", "ses-B")])
ImageQuery(data_type=DataType.PET)
ImageQuery(data_type="pet")
ImageQuery(entities={"trc": "11CPIB", "task": "rest"})
ImageQuery(entities=["trc-11CPIB", "task-rest"])
ImageQuery(entities="trc-11CPIB_task-rest")
ImageQuery(suffix="T1w")

Or as a more exhaustive example:

image_query = ImageQuery(
        subjects={"sub-ADNI027S0074"},
        sessions={"ses-M000"},
        data_type=DataType.PET,
        entities={"trc": "18FFDG", "rec": "coregiso8"},
        suffix="pet",
)
images = dataset.query_images(image_query)

Cartesian vs cross-product of subjects/sessions:

ImageQuery(subjects={"sub-A", "sub-B"}, sessions={"ses-1", "ses-3"}
# will match the images marked as X:
#      1  2  3  < ses-*
#    A X     X
#    B X     X
#    C
# ^sub-*

ImageQuery(sub_ses={"sub-A": {"ses-1"}, "sub-B": {"ses-3"}})
ImageQuery(sub_ses=[("sub-A", "ses-1"), ("sub-B", "ses-3")]
# will match the images marked as X:
#      1  2  3  < ses-*
#    A X
#    B       X
#    C
# ^sub-*
subjects: set[clinicaio.types.SubjectId]#
sessions: set[clinicaio.types.SessionId]#
sub_ses: dict[clinicaio.types.SubjectId, set[clinicaio.types.SessionId]]#
data_type: clinicaio.types.DataType | None#
entities: clinicaio.entities.Entities#
suffix: str | None#