rtCommon.bidsIncremental
bidsIncremental.py
Implements the BIDS Incremental data type used for streaming BIDS data between different applications.
Module Contents
Classes
Attributes
- rtCommon.bidsIncremental.logger
- class rtCommon.bidsIncremental.BidsIncremental(image: nibabel.Nifti1Image, imageMetadata: dict, datasetDescription: dict = None)
- ENTITIES
- REQUIRED_IMAGE_METADATA = ['subject', 'task', 'suffix', 'datatype', 'RepetitionTime']
BIDS Incremental data format suitable for streaming BIDS Archives
- _imgMetadata
Store dataset description
- __str__()
Return str(self).
- __eq__(other)
Return self==value.
- __getstate__()
- __setstate__(state)
- _preprocessMetadata(imageMetadata: dict) dict
Pre-process metadata to extract any additonal metadata that might be embedded in the provided metadata, like ProtocolName, and ensure that certain metadata values (e.g., RepetitionTime) are within BIDS-specified ranges.
- Parameters
imageMetadata – Metadata dictionary provided to BIDS incremental to search for additional, embedded metadata
- Returns
- Original dictionary with all embedded metadata added explicitly and
values within BIDS-specified ranges.
- _exceptIfMissingMetadata(imageMetadata: dict) None
Ensure that all required metadata is present.
- Parameters
imageMetadata – Metadata dictionary to check for missing metadata
- Raises
MissingMetadataError – If not all required metadata is present.
- _postprocessMetadata(imageMetadata: dict) dict
Post-process metadata once all required fields are given (e.g., to create derived fields like ‘TaskName’ from ‘task’).
- Parameters
imageMetadata – Metadata dictionary to post-process.
- Returns
Metadata dictionary with derived fields set.
- static createImageMetadataDict(subject: str, task: str, suffix: str, datatype: str, repetitionTime: int)
Creates an image metadata dictionary for a BIDS-I with all of the basic required fields using the correct key names.
- Parameters
subject – Subject ID (e.g., ‘01’)
task – Task ID (e.g., ‘story’)
suffix – Imaging method (e.g., ‘bold’)
datatype – Data type (e.g., ‘func’ or ‘anat’)
repetitionTime – TR time, in seconds, used for the imaging run
- Returns
Dictionary with the provided information ready for use in a BIDS-I
- classmethod findMissingImageMetadata(imageMeta: dict) list
Creates a list of all required metadata fields that the argument dictionary is missing.
- Parameters
imageMeta – Metadata dictionary to check for missing fields
- Returns
List of required fields missing in the provided dictionary.
Examples
>>> meta = {'subject': '01', 'task': 'test', 'suffix': 'bold', 'datatype': 'func'} >>> BidsIncremental.findMissingImageMetadata(meta) ['RepetitionTime']
- classmethod isCompleteImageMetadata(imageMeta: dict) bool
Verifies that all required metadata fields for BIDS-I construction are present in the dictionary.
- Parameters
imageMeta – The dictionary with the metadata fields
- Returns
True if all required fields are present in the dictionary, False otherwise.
Examples
>>> meta = {'subject': '01', 'task': 'test', 'suffix': 'bold', 'datatype': 'func'} >>> BidsIncremental.isCompleteImageMetadata(meta) False
- _exceptIfNotBids(entityName: str) None
Raise an exception if the argument is not a valid BIDS entity
- getMetadataField(field: str, strict: bool = False) Any
Get value for the field in the incremental’s metadata, if it exists.
- Parameters
field – Metadata field to retrieve a value for.
default – Default value to return if field is not present.
strict – Only allow getting fields that are defined as BIDS entities in the standard.
- Returns
Entity’s value, or None if the entity isn’t present in the metadata.
- Raises
ValueError – If ‘strict’ is True and ‘field’ is not a BIDS entity.
KeyError – If the field is not present in the Incremental’s metadata and not default value is provided.
Examples
>>> incremental.getMetadataField('task') 'faces' >>> incremental.getMetadataField('RepetitionTime') 1.5 >>> incremental.getMetadataField('RepetitionTime', strict=True) ValueError: RepetitionTime is not a valid BIDS entity name
- setMetadataField(field: str, value: Any, strict: bool = False) None
Set metadata field to provided value in Incremental’s metadata.
- Parameters
field – Metadata field to set value for.
value – Value to set for the provided entity.
strict – Only allow setting fields that are defined as BIDS entities in the standard.
- Raises
ValueError – If ‘strict’ is True and ‘field’ is not a BIDS entity.
- removeMetadataField(field: str, strict: bool = False) None
Remove a piece of metadata from the incremental’s metadata.
- Parameters
field – BIDS entity name to retrieve a value for.
strict – Only allow removing fields that are defined as BIDS entities in the standard.
- Raises
ValueError – If ‘strict’ is True and ‘field’ is not a BIDS entity.
RuntimeError – If the field to be removed is required by the Incremental.
- getImageMetadata()
- getSuffix() str
- getDatatype() str
func or anat
- getEntities() dict
- getImageDimensions() tuple
- getImageHeader()
- getImageData() numpy.ndarray
- makeBidsFileName(extension: rtCommon.bidsCommon.BidsFileExtension) str
Create the a BIDS-compatible file name based on the metadata. General format of the filename, per BIDS standard 1.4.1, is as follows (items in [square brackets] are considered optional):
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] [_ce-<label>] [_dir-<label>][_rec-<label>][_run-<index>] [_echo-<index>]_<contrast_label >.ext
- Parameters
extension – The extension for the file, e.g., ‘nii’ for images or ‘json’ for metadata
- Returns
Filename from metadata according to BIDS standard 1.4.1.
- getDatasetName() str
- getImageFileName() str
- getMetadataFileName() str
- getEventsFileName() str
- getImageFilePath() str
- getMetadataFilePath() str
- getEventsFilePath() str
- getDataDirPath() str
Path to where this incremental’s data would be in a BIDS archive, relative to the archive root.
- Returns
Path string relative to root of the imaginary dataset.
Examples
>>> print(bidsi.getDataDirPath()) sub-01/ses-2011/anat
- getAcquisitionTime() datetime.datetime.time
Returns the acquisition time as a datetime.time
- getRepetitionTime() float
Returns the TR repetition time in seconds
- timeToNextTr(clockSkew, now=None) float
Based on acquisition time returns seconds to next TR start
- writeToDisk(datasetRoot: str, onlyData=False) None
Writes the incremental’s data to a directory on disk. NOTE: The directory is assumed to be empty, and no checks are made for data that would be overwritten.
- Parameters
datasetRoot – Path to the root of the BIDS archive to be written to.
onlyData – Only write out the NIfTI image and sidecar metadata (Default False). Useful if writing an incremental out to an existing archive and you don’t want to overwrite existing README or dataset_description.json files.
Examples
>>> from bidsArchive import BidsArchive >>> incremental = BidsIncremental(image, metadata) >>> root = '/tmp/emptyDirectory' >>> incremental.writeToDisk(root) >>> archive = BidsArchive(root) >>> print(archive) Root: /tmp/emptyDirectory | Subjects: 1 | Sessions: 1 | Runs: 1