Acquisition

See also

User guide on the acquisition process.

Acquisition Control

Acquisition Control Class.

class console.spcm_control.acquisition_control.AcquisitionControl(configuration_file: str, nexus_data_dir: str = '/home/runner/nexus-console', file_log_level: int = 20, console_log_level: int = 20)

Bases: object

Acquisition control class.

The main functionality of the acquisition control is to orchestrate transmit and receive cards using TxCard and RxCard instances.

post_processing(parameter: AcquisitionParameter) → None

Proces acquired NMR data.

Post processing contains the following steps (per readout sample size): (1) Scaling of receive data (2) Demodulation along readout dimensions (3) Decimation along readout dimension

Parameters:

parameter – Acquisition parameter

run(store_unprocessed: bool = False) → AcquisitionData

Run an acquisition job.

Parameters:

• store_unprocessed – Flag for whether to keep the raw, undecimated data after decimation

• realtime_proccessing – flag for processing the data in real time using the multiprocessing or using threading to process the data after it has all been acquired.

Raises:

• RuntimeError – The measurement cards are not setup properly

• ValueError – Missing raw data or missing averages

set_sequence(sequence: str | Sequence, parameter: AcquisitionParameter) → None

Set sequence and acquisition parameter.

Parameters:

• sequence – Path to pulseq sequence file.

• parameter – Set of acquisition parameters which are required for the acquisition.

Raises:

• AttributeError – Invalid sequence provided.

• FileNotFoundError – Invalid file ending of sequence file.

Acquisition Parameter

Interface class for acquisition parameters.

class console.interfaces.acquisition_parameter.AcquisitionParameter(larmor_frequency: float = 2000000.0, b1_scaling: float = 1.0, gradient_offset: ~console.interfaces.dimensions.Dimensions = <factory>, fov_scaling: ~console.interfaces.dimensions.Dimensions = <factory>, ddc_method: ~console.interfaces.enums.DDCMethod = DDCMethod.FIR, num_averages: int = 1, averaging_delay: float = 0.0, state_filepath: ~pathlib.Path | str = PosixPath('/home/runner/nexus-console/acquisition-parameter.state'), _initialized: bool = False)

Bases: object

Parameters to define an acquisition.

The acquisition parameters are defined in a dataclass which is hashable but still mutable. This allows to easily change parameters and detect updates by comparing the hash.

New instances of acquisition parameters are not saved automatically. Once the autosave flag is set by calling activate_autosave, the parameter state is written to a pickle file acquisition-parameter.state in the default_state_file_path on any mutation of the acquisition parameter instance. The autosave option can be deactivated calling deactivate_autosave. Manually storing the acquisition parameters to a specific directory can be achieved using the save method and providing the desired path.

averaging_delay: float = 0.0

Delay in seconds between acquisition averages.

b1_scaling: float = 1.0

Scaling of the B1 field (RF transmit power).

ddc_method: DDCMethod = 'finite-impulse-response-filter'

dict(use_strings: bool = False) → dict

Return acquisition parameters as dictionary.

Parameters:

• use_strings – boolean flag indicating if values of dictionary should be represented as strings, by default False

• optional – boolean flag indicating if values of dictionary should be represented as strings, by default False

Return type:

Acquisition parameter dictionary

fov_scaling: Dimensions

Field of view scaling for Gx, Gy and Gz.

gradient_offset: Dimensions

Gradient offset values in mV.

hash() → int

Return acquisition parameter integer hash.

larmor_frequency: float = 2000000.0

Larmor frequency in MHz.

classmethod load(filepath: Path | str | None = None) → AcquisitionParameter | None

Load acquisition parameter state from state file in-place.

Parameters:

• file_path – Path to acquisition parameter state file. If file_path is not a pickle file, i.e. ends with .pkl, the default state file designation acquisition-parameter.state is added.

• optional – Path to acquisition parameter state file. If file_path is not a pickle file, i.e. ends with .pkl, the default state file designation acquisition-parameter.state is added.

Return type:

Instance of acquisition parameters with state loaded from provided file_path.

Raises:

• FileNotFoundError – Provided file_path is not a pickle file or does not exist.

• EOFError – Provided state file is corrupted

num_averages: int = 1

Number of acquisition averages.

save(filepath: Path | str | None = None) → None

Save current acquisition parameter state.

Parameters:

• file_path – Path to the pickle state file, by default None. If None, the default state file path is taken which is <home>/nexus-console/acquisition-parameter.state Default state file path can be changed using the set_default_path method.

• optional – Path to the pickle state file, by default None. If None, the default state file path is taken which is <home>/nexus-console/acquisition-parameter.state Default state file path can be changed using the set_default_path method.

state_filepath: Path | str = PosixPath('/home/runner/nexus-console/acquisition-parameter.state')

Default file path for acquisition parameter state.

The decimation method can be specified by the following enum definition and dimensions are defined by the subsequent dataclass.

Definition of enums.

class console.interfaces.enums.DDCMethod(value)

Bases: str, Enum

Enum for DDC methods.

AVG = 'moving-average-filter'

CIC = 'cascaded-integrator-comb-filter'

FIR = 'finite-impulse-response-filter'

Interface class for dimensions.

class console.interfaces.dimensions.Dimensions(x: float | int, y: float | int, z: float | int)

Bases: object

Dataclass for definition of dimensional parameters.

dict() → dict[str, float | int]

Create dictionary of dimensions object.

classmethod from_dict(dim: dict[str, float | int]) → Dimensions

Create a dimensions instance from dictionary.

x: float | int

X dimension.

y: float | int

Y dimension.

z: float | int

Z dimension.

Acquisition Data

Interface class for acquisition data.

class console.interfaces.acquisition_data.AcquisitionData(receive_data: list[~console.interfaces.rx_data.RxData], acquisition_parameters: ~console.interfaces.acquisition_parameter.AcquisitionParameter, sequence: ~console.pulseq_interpreter.sequence_provider.SequenceProvider | ~pypulseq.Sequence.sequence.Sequence, session_path: str, meta: dict[str, ~typing.Any] = <factory>, _additional_numpy_data: dict = <factory>)

Bases: object

Parameters which define an acquisition.

acquisition_parameters: AcquisitionParameter

Acquisition parameters.

add_data(data: dict[str, ndarray]) → None

Add data to additional_data dictionary.

Parameters:

data – Data which is to be added to acquisition data.

add_info(info: dict[str, Any]) → None

Add entries to meta data dictionary.

Parameters:

info – Information as dictionary to be added.

meta: dict[str, Any]

Meta data dictionary for additional acquisition info. Dictionary is updated (extended) by post-init method with some general information.

receive_data: list[RxData]

A list containing a list of RxData objects which contain all of the receive data for the acquisition. The outer list contains the list of RxData for each average.

save(user_path: str | None = None, overwrite: bool = False) → None

Save all the acquisition data to a given data path.

Parameters:

• user_path – Optional user path, default is None. If provided, it is taken to store the acquisition data. Other wise a datetime-based folder is created.

• overwrite – Flag which indicates whether the acquisition data should be overwritten in case it already exists from a previous call to this function, default is False.

save_ismrmrd(header: ismrmrdHeader | str | Path, user_path: str | None = None)

Store acquisition data in (ISMR)MRD format.

sequence: SequenceProvider | Sequence

Sequence object used for the acquisition acquisition.

session_path: str

Directory the acquisition data will be stored in. Within the given storage_path a new directory with time stamp and sequence name will be created.