MDF4

asammdf tries to emulate the mdf structure using Python builtin data types.

The header attibute is an OrderedDict that holds the file metadata.

The groups attribute is a dictionary list with the following keys:

  • data_group : DataGroup object

  • channel_group : ChannelGroup object

  • channels : list of Channel objects with the same order as found in the mdf file

  • channel_conversions : list of ChannelConversion objects in 1-to-1 relation with the channel list

  • channel_sources : list of SourceInformation objects in 1-to-1 relation with the channels list

  • data_block : DataBlock object

  • texts : dictionay containing TextBlock objects used throughout the mdf

    • channels : list of dictionaries that contain TextBlock objects ralated to each channel

      • name_addr : channel name
      • comment_addr : channel comment

    • channel group : list of dictionaries that contain TextBlock objects ralated to each channel group

      • acq_name_addr : channel group acquisition comment
      • comment_addr : channel group comment

    • conversion_tab : list of dictionaries that contain TextBlock objects related to TABX and RTABX channel conversions

      • text_{n} : n-th text of the VTABR conversion
      • default_addr : default text

    • conversions : list of dictionaries that containt TextBlock obejcts related to channel conversions

      • name_addr : converions name
      • unit_addr : channel unit_addr
      • comment_addr : converison comment
      • formula_addr : formula text; only valid for algebraic conversions

    • sources : list of dictionaries that containt TextBlock obejcts related to channel sources

      • name_addr : source name
      • path_addr : source path_addr
      • comment_addr : source comment

The file_history attribute is a list of (FileHistory, TextBlock) pairs .

The channel_db attibute is a dictionary that holds the (data group index, channel index) pair for all signals. This is used to speed up the get_signal_by_name method.

The master_db attibute is a dictionary that holds the channel index of the master channel for all data groups. This is used to speed up the get_signal_by_name method.

API

class asammdf.mdf4.MDF4(name=None, load_measured_data=True, compression=False, version='4.00')

If the name exist it will be loaded otherwise an empty file will be created that can be later saved to disk

Parameters:

name : string

mdf file name

load_measured_data : bool

load data option; default True

  • if True the data group binary data block will be loaded in RAM
  • if False the channel data is read from disk on request

compression : bool

compression option for data group binary data block; default False

version : string

mdf file version (‘4.00’, ‘4.10’, ‘4.11’); default ‘4.00’

Attributes

name (string) mdf file name
groups (list) list of data groups
header (HeaderBlock) mdf file header
file_history (list) list of (FileHistory, TextBlock) pairs
comment (TextBlock) mdf file comment
identification (FileIdentificationBlock) mdf file start block
load_measured_data (bool) load measured data option
compression (bool) measured data compression option
version (int) mdf version
channels_db (dict) used for fast channel access by name; for each name key the value is a (group index, channel index) tuple
masters_db (dict) used for fast master channel access; for each group index key the value is the master channel index

Methods

append
attach
extract_attachment
get
info
remove
save
append(signals, source_info='Python')

Appends a new data group.

Parameters:

signals : list

list on Signal objects

acquisition_info : str

acquisition information; default ‘Python’

Examples

>>> # case 1 conversion type None
>>> s1 = np.array([1, 2, 3, 4, 5])
>>> s2 = np.array([-1, -2, -3, -4, -5])
>>> s3 = np.array([0.1, 0.04, 0.09, 0.16, 0.25])
>>> t = np.array([0.001, 0.002, 0.003, 0.004, 0.005])
>>> names = ['Positive', 'Negative', 'Float']
>>> units = ['+', '-', '.f']
>>> info = {}
>>> s1 = Signal(samples=s1, timstamps=t, unit='+', name='Positive')
>>> s2 = Signal(samples=s2, timstamps=t, unit='-', name='Negative')
>>> s3 = Signal(samples=s3, timstamps=t, unit='flts', name='Floats')
>>> mdf = MDF4('new.mf4')
>>> mdf.append([s1, s2, s3], 'created by asammdf v1.1.0')
>>> # case 2: VTAB conversions from channels inside another file
>>> mdf1 = MDF4('in.mf4')
>>> ch1 = mdf1.get("Channel1_VTAB")
>>> ch2 = mdf1.get("Channel2_VTABR")
>>> sigs = [ch1, ch2]
>>> mdf2 = MDF4('out.mf4')
>>> mdf2.append(sigs, 'created by asammdf v1.1.0')
attach(data, file_name=None, comment=None, compression=True, mime='application/octet-stream')

attach embedded attachment as application/octet-stream

Parameters:

data : bytes

data to be attached

file_name : str

string file name

comment : str

attachment comment

compression : bool

use compression for embedded attachment data

mime : str

mime type string
extract_attachment(index)

extract attachemnt index data. If it is an embedded attachment, then this method creates the new file according to the attachemnt file name information

Parameters:

index : int

attachment index
Returns:

data : bytes | str

attachment data
get(name=None, group=None, index=None, raster=None, samples_only=False)

Gets channel samples. Channel can be specified in two ways:

  • using the first positional argument name

    • if there are multiple occurances for this channel then the group argument can be used to select a specific group.
    • if there are multiple occurances for this channel and the group argument is None then a warning is issued

  • using the group number (keyword argument group) and the channel number (keyword argument index). Use info method for group and channel numbers

If the raster keyword argument is not None the output is interpolated accordingly

Parameters:

name : string

name of channel

group : int

0-based group index

index : int

0-based channel index

raster : float

time raster in seconds

samples_only : bool

if True return only the channel samples as numpy array; if False return a Signal object
Returns:

vals, t, unit, conversion : (numpy.array, numpy.array, string, dict | None)

The conversion is None exept for the VTAB and VTABR conversions. The conversion keys are:

  • for TABX conversion:

    • raw - numpy.array for X-axis
    • phys - numpy.array of strings for Y-axis
    • type - conversion type = CONVERSION_TYPE_TABX
    • default - default bytes value

  • for RTABX conversion:

    • lower - numpy.array for lower range
    • upper - numpy.array for upper range
    • phys - numpy.array of strings for Y-axis
    • type - conversion type =
    • default - default bytes value

The conversion information can be used by the append method for the info argument
Raises:

MdfError :

* if the channel name is not found

* if the group index is out of range

* if the channel index is out of range
info()

get MDF information as a dict

Examples

>>> mdf = MDF4('test.mdf')
>>> mdf.info()
remove(group=None, name=None)

Remove data group. Use group or name keyword arguments to identify the group’s index. group has priority

Parameters:

name : string

name of the channel inside the data group to be removed

group : int

data group index to be removed

Examples

>>> mdf = MDF4('test.mdf')
>>> mdf.remove(group=3)
>>> mdf.remove(name='VehicleSpeed')
save(dst=None)

Save MDF to dst. If dst is None the original file is overwritten