API Reference#

This is the API reference for the protocol which might be helpful fo users who want to add their own parameters and acquisition protocol for MR data acquisition. The API is divided into two categories: the high-level API and the low-level API.

High-level API#

The high-level API is the most convenient way to add new parameters and acquisition protocols. It is based on the core API and provides a simple interface to add new parameters and protocols.

class RepetitionTime#

Bases: NumericParameter

Parameter specific class for RepetitionTime

__init__(value=Unspecified)#: Constructor.

class EchoTime#

Bases: MultiValueNumericParameter

Parameter specific class for EchoTime

__init__(value=Unspecified)#: constructor

class PhaseEncodingDirection#

Bases: CategoricalParameter

Parameter specific class for PhaseEncodingDirection

__init__(value=Unspecified)#: Constructor.

class MRImagingProtocol#

Bases: BaseImagingProtocol

Base class for all MR imaging protocols, including neuroimaging datasets

__init__( name='MRIProtocol', category='MR', filepath=None, type=ProtocolType.INFERRED_FROM_DATASET, )#: constructor

add(seq)#: Adds a new sequence to the current protocol

get_sequence_ids()#: Returns the list of sequence ids in the protocol

add_sequence_from_dict(seq_name, param_dict)#: Adds a sequence to the protocol from a dictionary

class SiemensMRImagingProtocol#

Bases: MRImagingProtocol

__init__( name='SiemensMRProtocol', category='MR', filepath=None, type=ProtocolType.USER_DEFINED, program_name=None, convert_ped=True, )#: constructor

from_xml(filepath=None)#: A function to parse the XML file and extract the parameters for each sequence

class ImagingSequence#

Bases: BaseSequence, ABC

Class representing an Imaging sequence

Although we would use it mostly for MR imaging sequences to start with it should be able to store any sequence captured by DICOM: CT, XRAY etc

__init__( name='MRI', dicom=None, imaging_params=None, required_params=None, path=None, )#: constructor

set_session_info(dicom)#: Sets the session information from the DICOM header. This is used to set the session_id, subject_id, run_id and timestamp

parse(dicom, params=None)#: Parses the parameter values from a given DICOM object or file.

from_dict(params_dict)#

Populates the sequence parameters from a dictionary.

Parameters:

params_dictdict: Dictionary containing the parameter names and values as key, value pairs.

set_echo_times(echo_times, echo_number=None)#: Sets the echo times for a multi-echo sequence.

Core API#

The core API is the low-level API which is used by the high-level API. It provides the basic functionality to add new parameters and acquisition protocols.

Main module containing the core classes.

class BaseParameter#

Bases: ABC

Base class for all parameters. A parameter is a container class for a single value (or a list of values), with a name, with methods to check for compliance and validity. For example, a parameter may represent imaging acquisition parameters of a sequence, e.g. RepetitionTime, EchoTime, PhaseEncodingDirection, etc.

Parameters:

namestr: Name of the parameter.
valueobject: Value of the parameter.
dtypetype: Data type of the parameter.
unitsstr: Units of the parameter. For example, 'ms' for milliseconds, 's' for seconds, etc.
stepsint: Incremental steps of the parameter. For example, 10 for a parameter that can take values such as 10, 20, 30, 40, etc.
rangetuple: Range of the parameter. For example, (0, 100) for a parameter that can take values between 0 and 100.
requiredbool: Whether the parameter is required or not.
severitystr: Importance of the parameter. For example, 'critical' for a parameter that is critical for acquisition, 'optional' for a parameter that is optional for acquisition.
dicom_tagstr: DICOM tag of the parameter. For example, '0018,0080' for RepetitionTime.
acronymstr: Acronym of the parameter. For example, 'TR' for RepetitionTime.

Methods

`compliant`(other, **kwargs)	Method to check if one parameter value is compatible w.r.t another, either in equality or within acceptable range, for that data type.
`get_value`()	Getter for the value of the parameter.

__init__( name='parameter', value=Unspecified, dtype=None, units='ms', steps=1, range=None, required=True, severity='critical', dicom_tag=None, acronym=None, )#: constructor

get_value()#: Getter for the value of the parameter.

compliant(other, **kwargs)#

Method to check if one parameter value is compatible w.r.t another, either in equality or within acceptable range, for that data type.

Parameters:

otherBaseParameter: The other parameter to compare with.
kwargsdict: Additional keyword arguments to be passed.

class MultiValueNumericParameter#

Bases: BaseParameter

Parameter subclass for parameters that can take multiple values, such as EchoTime, ImageOrientationPatient etc.

Parameters:

namestr: Name of the parameter.
valueobject: Value of the parameter.
dtypetype: Data type of the parameter.
unitsstr: Units of the parameter. For example, 'ms' for milliseconds, 's' for seconds, etc.
stepsint: Incremental steps of the parameter. For example, 10 for a parameter that can take values such as 10, 20, 30, 40, etc.
rangetuple: Range of the parameter. For example, (0, 100) for a parameter that can take values between 0 and 100.
requiredbool: Whether the parameter is required or not.
severitystr: Importance of the parameter. For example, 'critical' for a parameter that is critical for acquisition, 'optional' for a parameter that is optional for acquisition.
dicom_tagstr: DICOM tag of the parameter. For example, '0018,0080' for RepetitionTime.
acronymstr: Acronym of the parameter. For example, 'TR' for RepetitionTime.
orderedbool: Whether the parameter values are ordered or not. Some array types don't have any order like SequenceName, and SequenceVariant. Therefore ordered=False. as the values can be sorted. But others like ImageOrientation, ShimSetting etc. have an order, they cannot be sorted. Therefore ordered=True.

Methods

`compliant`(other, **kwargs)	Method to check if one parameter value is compatible w.r.t another, either in equality or within acceptable range, for that data type.
`get_value`()	Getter for the value of the parameter.

__init__( name, value, dicom_tag=None, acronym=None, units=None, range=None, steps=None, required=True, severity='critical', ordered=False, )#: Constructor. some array types don't have any order like EchoTime, and EchoNumber. So they can be sorted. But others cannot like ImageOrientation, ShimSetting etc. have an order, they cannot be sorted.

get_value()#: Getter for the value of the parameter. If the parameter has only one value, return that value, else return the list of values.

class NumericParameter#

Bases: BaseParameter

Parameter specific class for Numeric parameters such as RepetitionTime etc.

Parameters:

namestr: Name of the parameter.
valueobject: Value of the parameter.
dtypetype: Data type of the parameter.
unitsstr: Units of the parameter. For example, 'ms' for milliseconds, 's' for seconds, etc.
stepsint: Incremental steps of the parameter. For example, 10 for a parameter that can take values such as 10, 20, 30, 40, etc.
rangetuple: Range of the parameter. For example, (0, 100) for a parameter that can take values between 0 and 100.
requiredbool: Whether the parameter is required or not.
severitystr: Importance of the parameter. For example, 'critical' for a parameter that is critical for acquisition, 'optional' for a parameter that is optional for acquisition.
dicom_tagstr: DICOM tag of the parameter. For example, '0018,0080' for RepetitionTime.
acronymstr: Acronym of the parameter. For example, 'TR' for RepetitionTime.

Methods

`compliant`(other, **kwargs)	Method to check if one parameter value is compatible w.r.t another, either in equality or within acceptable range, for that data type.
`get_value`()	Getter for the value of the parameter.

__init__( name, value, dicom_tag=None, acronym=None, units=None, range=None, steps=None, required=True, severity='critical', )#: Constructor.

class MultiValueCategoricalParameter#

Bases: BaseParameter

Parameter specific class for parameters that can take multiple string values, such as e.g., SequenceVariant = ['SK', 'SP'], ImageType = ['ORIGINAL', 'PRIMARY', 'AXIAL'] etc.

Parameters:

namestr: Name of the parameter.
valueobject: Value of the parameter.
dtypetype: Data type of the parameter.
unitsstr: Units of the parameter. For example, 'ms' for milliseconds, 's' for seconds, etc.
stepsint
Incremental steps of the parameter. For example, 10 for a parameter that can take: values such as 10, 20, 30, 40, etc.
rangetuple: Range of the parameter. For example, (0, 100) for a parameter that can take values between 0 and 100.
requiredbool: Whether the parameter is required or not.
severitystr: Importance of the parameter. For example, 'critical' for a parameter that is critical for acquisition, 'optional' for a parameter that is optional for acquisition.
dicom_tagstr: DICOM tag of the parameter. For example, '0018,0080' for RepetitionTime.
acronymstr: Acronym of the parameter. For example, 'TR' for RepetitionTime.
allowed_valuestuple: Valid values for the parameter.

Methods

`compliant`(other, **kwargs)	Method to check if one parameter value is compatible w.r.t another, either in equality or within acceptable range, for that data type.
`get_value`()	Getter for the value of the parameter.

__init__( name, value, dicom_tag=None, acronym=None, dtype=typing.Iterable, required=True, severity='critical', units=None, range=None, allowed_values=(), )#: Constructor.

class CategoricalParameter#

Bases: BaseParameter

Parameter specific class for parameters that can take a single string value, such as SeriesDescription, ProtocolName, PhaseEncodingDirection etc.

Parameters:

namestr: Name of the parameter.
valueobject: Value of the parameter.
dtypetype: Data type of the parameter.
unitsstr: Units of the parameter. For example, 'ms' for milliseconds, 's' for seconds, etc.
dicom_tagstr: DICOM tag of the parameter. For example, '0018,0080' for RepetitionTime.
acronymstr: Acronym of the parameter. For example, 'TR' for RepetitionTime.
requiredbool: Whether the parameter is required or not.
severitystr: Importance of the parameter. For example, 'critical' for a parameter that is critical for acquisition, 'optional' for a parameter that is optional for acquisition.
allowed_valuestuple: Valid values for the parameter.

Methods

`compliant`(other, **kwargs)	Method to check if one parameter value is compatible w.r.t another, either in equality or within acceptable range, for that data type.
`get_value`()	Getter for the value of the parameter.

__init__( name, value, dicom_tag=None, acronym=None, dtype=<class 'str'>, required=True, severity='critical', units=None, allowed_values=(), )#: Constructor.

class BaseSequence#

Bases: MutableMapping

Container to capture imaging parameter values for a given sequence. A sequence is defined as a set of parameters implemented as a dict. A sequence is mutable, i.e. parameters and their values can be modified.

Parameters:

namestr: Name of the sequence.
paramsdict: Dictionary of parameters and their values.
pathstr: Path to the sequence on disk.

Examples

from protocol import BaseSequence, BaseParameter
# adding a parameter to a sequence
seq = BaseSequence()
parameter = BaseParameter(name='RepetitionTime', value=2.0)
seq.add(parameter)

# Checking if parameters of two sequences are same
if seq1.compliant(seq2):
    # they are compliant
else:
    # not compliant

# Retrieving a parameter value
param = seq['RepetitionTime']
# print the value
print(param.get_value())

Methods

`add`(param_list)	method to add new parameters; overwrite previous values if exists.
`clear`()
`compliant`(other[, rtol, decimals, ...])	Method to check if one sequence is compatible w.r.t another, either in equality or within acceptable range, for each parameter.
`get`(k[,d])
`get_session_info`()	method to get metadata to the sequence
`items`()
`keys`()
`pop`(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised.
`popitem`()	as a 2-tuple; but raise KeyError if D is empty.
`setdefault`(k[,d])
`update`([E, ]**F)	If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
`values`()

__init__( name: str = 'Sequence', params: dict | None = None, path: str | None = None, )#: constructor

get_session_info()#: method to get metadata to the sequence

add( param_list: BaseParameter | Iterable[BaseParameter], )#: method to add new parameters; overwrite previous values if exists.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.#

compliant(other, rtol=0, decimals=None, include_params=None)#

Method to check if one sequence is compatible w.r.t another, either in equality or within acceptable range, for each parameter.

Parameters:

otherBaseSequence: The other sequence to compare with.
rtolfloat: Relative tolerance. The relative difference is equal to rtol * abs(b). Default is 0.
decimalsint: Number of decimal places to consider for comparison. Default is 3.
include_paramslist: List of parameters to include while comparing two sequences. Default is all parameters.

class BaseProtocol#

Bases: ABC

Base class for all protocols.

A protocol is a sequence, except it is not mutable, to serve as a reference.

Parameters:

namestr: Name of the protocol.

__init__(name='Protocol')#: constructor

class BaseImagingProtocol#

Bases: BaseProtocol

Base class for all imaging protocols such as MRI / neuroimaging.

Parameters:

namestr: Name of the protocol.
categorystr: Category of the protocol. For example, 'MR' for MRI, 'CT' for CT, etc. It should be one of the supported imaging modalities.

__init__(name='ImagingProtocol', category='MR')#: constructor