clinicaio.models.entity
=======================

.. py:module:: clinicaio.models.entity


Classes
-------

.. autoapisummary::

   clinicaio.models.entity.Label
   clinicaio.models.entity.Index
   clinicaio.models.entity.Entity
   clinicaio.models.entity.SubjectEntity
   clinicaio.models.entity.SessionEntity
   clinicaio.models.entity.AcquisitionEntity
   clinicaio.models.entity.SpaceEntity
   clinicaio.models.entity.TracerEntity
   clinicaio.models.entity.DescriptionEntity
   clinicaio.models.entity.ResolutionEntity
   clinicaio.models.entity.RunEntity
   clinicaio.models.entity.SuffixEntity
   clinicaio.models.entity.SUVREntity
   clinicaio.models.entity.BIDSPath


Module Contents
---------------

.. py:class:: Label(value: Union[str, enum.Enum])

   Bases: :py:obj:`collections.UserString`


   All the operations on a read-only sequence.

   Concrete subclasses must override __new__ or __init__,
   __getitem__, and __len__.


   .. py:method:: validate(value: Union[str, enum.Enum]) -> str
      :classmethod:



.. py:class:: Index(value: int, length_as_string: int = 1)

   Bases: :py:obj:`collections.UserString`


   All the operations on a read-only sequence.

   Concrete subclasses must override __new__ or __init__,
   __getitem__, and __len__.


   .. py:method:: validate(value: int, length_as_string: int) -> str
      :classmethod:



.. py:class:: Entity

   .. py:attribute:: key
      :type:  Label


   .. py:attribute:: value
      :type:  Union[Label, Index]


   .. py:method:: __str__() -> str


.. py:class:: SubjectEntity(value: str)

   Bases: :py:obj:`Entity`


   A person or animal participating in the study.


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: SessionEntity(value: str)

   Bases: :py:obj:`Entity`


   A logical grouping of neuroimaging and behavioral data consistent across subjects. 
   Session can (but doesn't have to) be synonymous to a visit in a longitudinal study. 
   In general, subjects will stay in the scanner during one session. 
   However, for example, if a subject has to leave the scanner room and then be re-positioned 
   on the scanner bed, the set of MRI acquisitions will still be considered as a session 
   and match sessions acquired in other subjects. Similarly, in situations where different 
   data types are obtained over several visits (for example fMRI on one day followed by DWI 
   the day after) those can be grouped in one session.

   Defining multiple sessions is appropriate when several identical or similar data 
   acquisitions are planned and performed on all -or most- subjects, often in the 
   case of some intervention between sessions (for example, training).


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: AcquisitionEntity(value: str)

   Bases: :py:obj:`Entity`


   The acq-<label> entity corresponds to a custom label the user MAY use to distinguish a different 
   set of parameters used for acquiring the same modality.

   For example, this should be used when a study includes two T1w images - one full brain low 
   resolution and one restricted field of view but high resolution. In such case two files 
   could have the following names: sub-01_acq-highres_T1w.nii.gz and sub-01_acq-lowres_T1w.nii.gz; 
   however, the user is free to choose any other label than highres and lowres as long as they are 
   consistent across subjects and sessions.

   In case different sequences are used to record the same modality (for example, RARE and FLASH for T1w) 
   this field can also be used to make that distinction. The level of detail at which the distinction 
   is made (for example, just between RARE and FLASH, or between RARE, FLASH, and FLASHsubsampled) remains 
   at the discretion of the researcher.


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: SpaceEntity(value: str)

   Bases: :py:obj:`Entity`


   The space-<label> entity can be used to indicate the way in which electrode positions are interpreted 
   (for EEG/MEG/iEEG data) or the spatial reference to which a file has been aligned (for MRI data). 
   The <label> MUST be taken from one of the modality specific lists in the Coordinate Systems Appendix. 
   For example, for iEEG data, the restricted keywords listed under iEEG Specific Coordinate Systems are 
   acceptable for <label>.

   For EEG/MEG/iEEG data, this entity can be applied to raw data, but for other data types, it is restricted to derivative data.


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: TracerEntity(value: str)

   Bases: :py:obj:`Entity`


   This entity represents the "TracerName" metadata field. 
   Therefore, if the trc-<label> entity is present in a filename, 
   "TracerName" MUST be defined in the associated metadata. 
   Please note that the <label> does not need to match the actual value of the field.


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: DescriptionEntity(value: str)

   Bases: :py:obj:`Entity`


   When necessary to distinguish two files that do not otherwise have a distinguishing entity, 
   the desc-<label> entity SHOULD be used.

   This entity is only applicable to derivative data.


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: ResolutionEntity(value: str)

   Bases: :py:obj:`Entity`


   Resolution of regularly sampled N-dimensional data.

   This entity represents the "Resolution" metadata field. Therefore, if the res-<label> 
   entity is present in a filename, "Resolution" MUST also be added in the JSON file, 
   to provide interpretation.

   This entity is only applicable to derivative data.



   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: RunEntity(value: int)

   Bases: :py:obj:`Entity`


   The run-<index> entity is used to distinguish separate data acquisitions with the same 
   acquisition parameters and (other) entities.

   If several data acquisitions (for example, MRI scans or EEG recordings) with the same acquisition 
   parameters are acquired in the same session, they MUST be indexed with the run-<index> entity: 
   _run-1, _run-2, _run-3, and so on (only nonnegative integers are allowed as run indices).

   If different entities apply, such as a different session indicated by ses-<label>, 
   or different acquisition parameters indicated by acq-<label>, then run is not needed to distinguish 
   the scans and MAY be omitted.


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: SuffixEntity(value: Union[str, enum.Enum])

   Bases: :py:obj:`Label`


   All the operations on a read-only sequence.

   Concrete subclasses must override __new__ or __init__,
   __getitem__, and __len__.


.. py:class:: SUVREntity(value: str)

   Bases: :py:obj:`Entity`


   .. py:attribute:: key


   .. py:attribute:: value


.. py:class:: BIDSPath

   .. py:attribute:: subject
      :type:  SubjectEntity


   .. py:attribute:: session
      :type:  SessionEntity


   .. py:attribute:: modality
      :type:  clinicaio.models.enum.Modality


   .. py:attribute:: entities
      :type:  Optional[list[Entity]]


   .. py:attribute:: suffix
      :type:  Optional[SuffixEntity]


   .. py:attribute:: extension
      :type:  Optional[clinicaio.models.enum.Extension]


   .. py:method:: get_image() -> pathlib.Path