mrftools.Utilities.twixtools package

Submodules

mrftools.Utilities.twixtools.geometry module

class mrftools.Utilities.twixtools.geometry.Geometry(twix)

Bases: object

Get geometric information from twix dict

During initialization, information about slice geometry is copied from the supplied twix dict. Methods for conversion between the different coordinate systems Patient Coordinate System (PCS; Sag/Cor/Tra), Device Coordinate System (XYZ) and Gradient Coordinate System (GCS or PRS; Phase, Readout, Slice) are implemented (so far only rotation, i.e. won’t work for offcenter measurementes).

Examples

` import twixtools twix = twixtools.read_twix('meas.dat', parse_geometry=True, parse_data=False) x = [1,1,1] y = twix[-1]['geometry'].rps_to_xyz() @ x `

Based on work from Christian Mirkes and Ali Aghaeifar.

from_twix(twix)

get_inplane_rotation()

get_plane_orientation()

pcs_to_xyz()

prs_to_pcs()

prs_to_xyz()

rps_to_prs()

rps_to_xyz()

mrftools.Utilities.twixtools.hdr_def module

mrftools.Utilities.twixtools.helpers module

class mrftools.Utilities.twixtools.helpers.ObservableDict(*observers, **kwds)

Bases: dict

Simple class that holds an argument dictionary.

Triggers a call to .notify_change() of the observer class(es) whenever a key is changed (not when it is initialized)

mrftools.Utilities.twixtools.helpers.idea_version_check(f)

mrftools.Utilities.twixtools.map_twix module

mrftools.Utilities.twixtools.map_twix.list_indices(seq, item)

mrftools.Utilities.twixtools.map_twix.map_twix(input, verbose=True)

creates a list of measurements (or a single dict if input was dict) with data for each measurement mapped to a twix_array object.

input: string, int, list, or dict

If the filename or its measurement id are passed as a string or int, respectively, the corresponding twix file is first parsed using read_twix. Alternatively, it is possible to directly pass a scan list (as returned by read_twix) to map_twix or to pass only a dict that includes header information and mdb list of a single twix scan.

out: dict of twix_array objects

A twix_array object is created for each data category (as defined by twix_category) that is encountered in the input. The twix_array object includes the header information (twix_array.hdr) as well as access to the underlying data via array slicing of a virtual ‘k-space’-like array that is designed to closely mimick a numpy.ndarray object (and indeed returns a numpy.ndarray).

Read the data and then select only the twix_array object that contains image data: >>> twix = map_twix(filename) >>> im_array = twix[‘image’]

Now set a few optional flags that control additional features and determine the shape of the output array: >>> im_array.flags[‘remove_os’] = True # activate automatic os removal >>> im_array.flags[‘regrid’] = True # activate ramp sampling regridding >>> im_array.flags[‘average’][‘Rep’] = True # average all repetitions >>> im_array.flags[‘squeeze_singletons’] = True # squeezes singleton dims

Print all available flags and their values: >>> print(im_array.flags)

Print the shape of the data and the names of the active dimensions: >>> print(im_array.shape) >>> print(im_array.dims)

And finally read the data: >>> im_data = im_array[:]

Alternatively, we can for example only select the data for the first receiver channel: >>> im_data0 = im_array[…,0,:]

All standard array slicing operations should be supported.

class mrftools.Utilities.twixtools.map_twix.twix_array(mdb_list, hdr=None, flags=None)

Bases: object

Memory-mapped storage class for Siemens MRI raw data.

The twix array class constructs a virtual multi-dimensional array from a list of mdb objects, that tries to closely resemble a numpy.ndarray with standard array slicing operations. The selected array is then read from the twix file (all reading operations are handled by the Mdb class) and returned in the form of a multi-dimensional numpy.ndarray.

Note that additional flags can change the shape of the virtual array.

ndim: int

number of output dimensions. May change depending on flags.

shape: tuple

shape of the output array. May change depending on flags.

dims: list

List of names of output dimensions. May change depending on flags.

non_singleton_dims: list

Returns list of non-singleton dimensions.

dim_order: tuple

List of the standard dimension order (immutable).

hdr: dict

twix header information

flags: dict

Dict of optional flags. The following flags are currently supported: - ‘average’: dict of bools that determines which dimensions should

be averaged.

• ‘squeeze_ave_dims’: bool that determines whether averaged

  dimensions should be removed/squeezed from the array’s shape.

• ‘squeeze_singletons’: bool that determines whether singleton

  dimensions should be removed (‘True’ makes previous option irrelevant)

• ‘remove_os’: oversampling removal. Reduces the number of columns

  by a factor of two.

• ‘regrid’: bool that controls ramp-sampling regridding (if applicable)

• ‘skip_empty_lead’: skips to first line & partition that is found

  in mdb list (e.g. if first line counter is 10, the output array starts at line counter 10).

• ‘zf_missing_lines’: zero-fill k-space to include lines and partitions

  that are higher than the maximum counter found in the mdb list, but are still within the k-space matrix according to the twix header.

copy()

property dim_order

property dims

property flags

property lin_offset

property ndim

property non_singleton_dims

property par_offset

setCoilInfoTo(coilname, activate_flags=True)

property shape

property size

mrftools.Utilities.twixtools.mdb module

class mrftools.Utilities.twixtools.mdb.Mdb(fid=None, version_is_ve=True)

Bases: mrftools.Utilities.twixtools.mdb.Mdb_base

Memory-mapped storage class for Siemens MRI raw data.

The function read_twix parses the twix file and stores all information (such as counters as well as the position of the data within the twix file) in a list of Mdb objects.

data: This will read the data from disk and return a 2D numpy

array (channels x columns).

mdh: measurement data header, stored as a special numpy.dtype.

You can get information about the order of the stored information (counters and such) with print(mdh.dtype).

is_image_scan(self): check for an imaging scan.

is_flag_set(self, flag): check if a certain MDH flag is set.

set_flag(self, flag, val): set MDH flag to value val (True or False).

get_flags(self): returns a dict with bools for all MDH flags.

get_active_flags(self): returns a list of all active MDH flags.

convert_to_local(self): converts the Mdb to a Mdb_local object

(no memory-mapping) that allows for array manipulation. This makes it possible to to manipulate data before writing a new twix file using write_twix

convert_to_local()

property data

class mrftools.Utilities.twixtools.mdb.Mdb_base(version_is_ve=True)

Bases: object

add_flag(flag)

property block_len

property cAve

property cEco

property cLin

property cPar

property cPhs

property cRep

property cSeg

property cSet

property cSlc

clear_all_flags()

property data_len

property dma_len

get_active_flags()

get_flag(flag)

get_flags()

is_flag_set(flag)

is_image_scan()

remove_flag(flag)

set_flag(flag, val)

set_flags(flags)

set_pmutimestamp(value=None)

set_timestamp(value=None)

set_timestamps(value=None)

update_CRC()

write_to_file(fid)

class mrftools.Utilities.twixtools.mdb.Mdb_local(data=None, version_is_ve=True)

Bases: mrftools.Utilities.twixtools.mdb.Mdb_base

property data

mrftools.Utilities.twixtools.mdh_def module

class mrftools.Utilities.twixtools.mdh_def.Channel_header(**kwargs)

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

CRC

Structure/Union member

ChannelId

Structure/Union member

MeasUID

Structure/Union member

Reserved1

Structure/Union member

ScanCounter

Structure/Union member

SequenceTime

Structure/Union member

TypeAndChannelLength

Structure/Union member

Unused2

Structure/Union member

Unused3

Structure/Union member

class mrftools.Utilities.twixtools.mdh_def.CutOff

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

Post

Structure/Union member

Pre

Structure/Union member

class mrftools.Utilities.twixtools.mdh_def.LineCounter

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

Ave

Structure/Union member

Eco

Structure/Union member

Ida

Structure/Union member

Idb

Structure/Union member

Idc

Structure/Union member

Idd

Structure/Union member

Ide

Structure/Union member

Lin

Structure/Union member

Par

Structure/Union member

Phs

Structure/Union member

Rep

Structure/Union member

Seg

Structure/Union member

Set

Structure/Union member

Sli

Structure/Union member

class mrftools.Utilities.twixtools.mdh_def.MyStruct

Bases: _ctypes.Structure

class mrftools.Utilities.twixtools.mdh_def.Scan_header(**kwargs)

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

ApplicationCounter

Structure/Union member

ApplicationMask

Structure/Union member

CRC

Structure/Union member

CenterCol

Structure/Union member

CenterLin

Structure/Union member

CenterPar

Structure/Union member

CoilSelect

Structure/Union member

Counter

Structure/Union member

CutOff

Structure/Union member

EvalInfoMask

Structure/Union member

FlagsAndDMALength

Structure/Union member

IceProgramPara

Structure/Union member

MeasUID

Structure/Union member

PMUTimeStamp

Structure/Union member

PTABPosDelay

Structure/Union member

PTABPosX

Structure/Union member

PTABPosY

Structure/Union member

PTABPosZ

Structure/Union member

ReadOutOffcentre

Structure/Union member

Reserved1

Structure/Union member

ReservedPara

Structure/Union member

SamplesInScan

Structure/Union member

ScanCounter

Structure/Union member

SliceData

Structure/Union member

SystemType

Structure/Union member

TimeSinceLastRF

Structure/Union member

TimeStamp

Structure/Union member

UsedChannels

Structure/Union member

class mrftools.Utilities.twixtools.mdh_def.SliceData

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

Quaternion

Structure/Union member

SlicePos

Structure/Union member

class mrftools.Utilities.twixtools.mdh_def.SlicePos

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

Cor

Structure/Union member

Sag

Structure/Union member

Tra

Structure/Union member

class mrftools.Utilities.twixtools.mdh_def.VB17_header(**kwargs)

Bases: mrftools.Utilities.twixtools.mdh_def.MyStruct

CenterCol

Structure/Union member

CenterLin

Structure/Union member

CenterPar

Structure/Union member

ChannelId

Structure/Union member

CoilSelect

Structure/Union member

Counter

Structure/Union member

CutOff

Structure/Union member

EvalInfoMask

Structure/Union member

FlagsAndDMALength

Structure/Union member

FreePara

Structure/Union member

IceProgramPara

Structure/Union member

MeasUID

Structure/Union member

PMUTimeStamp

Structure/Union member

PTABPosNeg

Structure/Union member

ReadOutOffcentre

Structure/Union member

SamplesInScan

Structure/Union member

ScanCounter

Structure/Union member

SliceData

Structure/Union member

TimeSinceLastRF

Structure/Union member

TimeStamp

Structure/Union member

UsedChannels

Structure/Union member

mrftools.Utilities.twixtools.mdh_def.add_flag(mdh, flag)

mrftools.Utilities.twixtools.mdh_def.clear_all_flags(mdh)

mrftools.Utilities.twixtools.mdh_def.get_active_flags(mdh)

mrftools.Utilities.twixtools.mdh_def.get_dma_len(mdh)

mrftools.Utilities.twixtools.mdh_def.get_flag(mdh, flag)

mrftools.Utilities.twixtools.mdh_def.get_flags(mdh)

mrftools.Utilities.twixtools.mdh_def.is_flag_set(mdh, flag)

mrftools.Utilities.twixtools.mdh_def.is_image_scan(mdh)

mrftools.Utilities.twixtools.mdh_def.remove_flag(mdh, flag)

mrftools.Utilities.twixtools.mdh_def.set_dma_len(mdh, dma_len)

mrftools.Utilities.twixtools.mdh_def.set_flag(mdh, flag, val)

mrftools.Utilities.twixtools.mdh_def.set_flags(mdh, flags)

mrftools.Utilities.twixtools.mdh_def.unpack_bits(infomask)

mrftools.Utilities.twixtools.quat module

mrftools.Utilities.twixtools.quat.directions_to_quaternion(read_dir, phase_dir, slice_dir)

mrftools.Utilities.twixtools.quat.quaternion_to_directions(quat)

mrftools.Utilities.twixtools.recon_helpers module

mrftools.Utilities.twixtools.recon_helpers.calc_regrid_traj(prot, ncol=None)

mrftools.Utilities.twixtools.recon_helpers.perform_regrid(data, rs_traj, ro_shift=0)

mrftools.Utilities.twixtools.recon_helpers.remove_oversampling(data, x_was_in_timedomain=True)

mrftools.Utilities.twixtools.recon_helpers.to_freqdomain(data, x_in_timedomain=True, axis=- 1)

mrftools.Utilities.twixtools.recon_helpers.to_timedomain(data, x_in_timedomain=False, axis=- 1)

mrftools.Utilities.twixtools.twixprot module

mrftools.Utilities.twixtools.twixprot.parse_ascconv(buffer)

mrftools.Utilities.twixtools.twixprot.parse_buffer(buffer)

mrftools.Utilities.twixtools.twixprot.parse_twix_hdr(file)

mrftools.Utilities.twixtools.twixprot.parse_xprot(buffer)

mrftools.Utilities.twixtools.twixprot.try_cast(value, key)

mrftools.Utilities.twixtools.twixprot.update_ascconv(prot, key, value, last_string=None)

mrftools.Utilities.twixtools.twixtools module

twixtools: provides reading and limited writing capability of Siemens MRI raw

data files (.dat).

@author: Philipp Ehses (philipp.ehses@dzne.de)

mrftools.Utilities.twixtools.twixtools.construct_multiheader(scanlist)

mrftools.Utilities.twixtools.twixtools.del_from_mdb_list(mdb_list, function)

helper function to safely remove multiple items from mdb_list at once :param mdb_list: :type mdb_list: input list of mdbs :param function: :type function: function used to filter mdbs

Example

Remove all mdbs from mdb_list which have the flag ‘noname60’ set to True. >>> del_from_mdb_list(mdb_list, lambda mdb: mdb.is_flag_set(‘noname60’))

mrftools.Utilities.twixtools.twixtools.fix_scancounters(mdb_list, start_cnt=1)

makes sure that all ScanCounter in mdb_list are consecutive integers This is necessary if mdbs are added/removed to/from a mdb_list.

mrftools.Utilities.twixtools.twixtools.read_twix(infile, include_scans=None, parse_prot=True, parse_data=True, parse_geometry=True, verbose=True, keep_syncdata_and_acqend=False)

Function for reading siemens twix raw data files.

Parameters

• infile (filename or measurement id of .dat file) –

• include_scans (list of scan numbers or None, optional) – By default, all scans in a multi-raid file are parsed.

• parse_prot (bool, optional) – By default, the protocol information is parsed. (this is also highly recommended)

• parse_data (bool, optional) – Set to False to parse only protocol information.

• parse_geometry (bool, optional) – Set to False to skip creation of transformation matrix from data coordinates to physical coordinates.

• verbose (bool, optional) – Switch progress and other messages on or off.

• keep_syncdata_and_acqend (bool, optional) – By default, syncdata and acqend blocks are not included in the mdb list. These blocks are helpful for twix writing, but unnecessary otherwise.

Returns

out –

The twix scans themselves consist of a dict with these elements:

• hdr: dict of parsed ascconv and XProtocol header information

• hdr_str: header bytearray (used by write_twix)

• mdb: list of measurement data blocks – here is the MRI data use help(twixtools.mdb.Mdb) for more information

• geometry: dict containing geometry information about the scan use help(twixtools.geometry) for more information

Return type

list of twix scan(s)

mrftools.Utilities.twixtools.twixtools.write_twix(scanlist, outfile, version_is_ve=True)

Function for writing siemens twix raw data files.

Parameters

• scanlist (list of twix scan(s)) –

• outfile (output filename for twix file (.dat)) –

• version_is_ve (bool that determines what whether to write a VA/VB) – or VD/VE compatible twix file. IMPORTANT: This tool does not allow for conversion between versions. This bool should be set to the original twix file version! IMPORTANT: write_twix currently only supports VE twix files!

mrftools.Utilities.twixtools.twixzip module

Module contents