API¶

MDF¶

This class acts as a proxy for the MDF2, MDF3 and MDF4 classes. All attribute access is delegated to the underlying _mdf attribute (MDF2, MDF3 or MDF4 object). See MDF3 and MDF4 for available extra methods (MDF2 and MDF3 share the same implementation).

An empty MDF file is created if the name argument is not provided. If the name argument is provided then the file must exist in the filesystem, otherwise an exception is raised.

The best practice is to use the MDF as a context manager. This way all resources are released correctly in case of exceptions.

with MDF(r'test.mdf') as mdf_file:
    # do something

Unified access to MDF v3 and v4 files. Underlying _mdf’s attributes and methods are linked to the MDF object via setattr. This is done to expose them to the user code and for performance considerations.

Parameters:

namestr | BytesIO | zipfile.ZipFile | bz2.BZ2File | gzip.GzipFile, optional: MDF file name (if provided it must be a real file name), file-like object or compressed file opened as a Python object.

Changed in version 6.2.0: Added support for zipfile.ZipFile, bz2.BZ2File and gzip.GzipFile.
versionstr, default ‘4.10’: MDF file version from (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’, ‘3.30’, ‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’). This argument is only used for MDF objects created from scratch; for MDF objects created from a file the version is set to file version.
channelsiterable, optional: Channel names that will be used for selective loading. This can dramatically improve the file loading time. Default is None -> load all channels.

Added in version 6.1.0.

Changed in version 6.3.0: Make the default None.
use_display_namesbool, default True: For MDF v4 files, parse the XML channel comment to search for the display name; XML parsing is quite expensive so setting this to False can decrease the loading times very much.
remove_source_from_channel_namesbool, default False: Remove source from channel names (“SpeedXCP3” -> “Speed”).
raise_on_multiple_occurrencesbool, default True: Raise MdfException when there are multiple channel occurrences in the file and the get call is ambiguous.

Added in version 7.0.0.
temporary_folderstr | path-like, optional: Folder to use for temporary files.

Added in version 7.0.0.
process_bus_loggingbool, default True: Controls whether the bus processing of MDF v4 files is done when the file is loaded.

Added in version 8.0.0.
ignore_invalidation_bitsbool, default False: Ingore all invalidation bits when extracting signals from the file.

Added in version 8.7.0.

Examples

>>> mdf = MDF(version='3.30')  # new MDF object with version 3.30
>>> mdf = MDF('path/to/file.mf4')  # MDF loaded from file
>>> mdf = MDF(BytesIO(data))  # MDF from file contents
>>> mdf = MDF(zipfile.ZipFile('data.zip'))  # MDF creating using the first valid MDF from archive
>>> mdf = MDF(bz2.BZ2File('path/to/data.bz2', 'rb'))  # MDF from bz2 object
>>> mdf = MDF(gzip.GzipFile('path/to/data.gzip', 'rb'))  # MDF from gzip object

cleanup_timestamps(minimum: float, maximum: float, exp_min: int = -15, exp_max: int = 15, version: str | Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30', '4.00', '4.10', '4.11', '4.20', '4.30'] | None = None, progress: Callable[[int, int], None] | Any | None = None) → MDF[source]¶

Clean up timestamps and convert MDF to other version.

Added in version 5.22.0.

Parameters:

minimumfloat: Minimum plausible timestamp.
maximumfloat: Maximum plausible timestamp.
exp_minint, default -15: Minimum plausible exponent used for the timestamps float values.
exp_maxint, default 15: Maximum plausible exponent used for the timestamps float values.
versionstr, optional: New MDF file version from (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’, ‘3.30’, ‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’); default is None and in this case the original file version is used.

Returns:

outMDF: New MDF object.

static concatenate(files: Sequence[MDF | FileLike | str | PathLike[str]], version: str | Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30', '4.00', '4.10', '4.11', '4.20', '4.30'] = '4.10', sync: bool = True, add_samples_origin: bool = False, direct_timestamp_continuation: bool = False, progress: Any | None = None, **kwargs: Unpack[_ConcatenateKwargs]) → MDF[source]¶

Concatenate several files. The files must have the same internal structure (same number of groups, and same channels in each group).

The order of the input files is always preserved, only the samples’ timestamps are influenced by the sync argument.

Parameters:

fileslist | tuple: List of MDF file names or MDF, zipfile.ZipFile, bz2.BZ2File or gzip.GzipFile instances.

Changed in version 6.2.0: Added support for zipfile.ZipFile, bz2.BZ2File and gzip.GzipFile.
versionstr, default ‘4.10’: Merged file version.
syncbool, default True: Sync the files based on the start of measurement. The order of the input files is preserved, only the samples’ timestamps are influenced by this argument.
add_samples_originbool, default False: Option to create a new “__samples_origin” channel that will hold the index of the measurement from where each timestamp originated.
direct_timestamp_continuationbool, default False: The timestamps from the next file will be added right after the last timestamp from the previous file.

Added in version 6.0.0.
use_display_namesbool, default False: Use display name instead of standard channel name, if available.
process_bus_loggingbool, default True: Controls whether the bus processing of MDF v4 files is done when the file is loaded.

Added in version 8.1.0.

Returns:

concatenatedMDF: New MDF object with concatenated channels.

Raises:

MdfException: If there are inconsistencies between the files.

Examples

>>> conc = MDF.concatenate(
    [
        'path/to/file.mf4',
        MDF(BytesIO(data)),
        MDF(zipfile.ZipFile('data.zip')),
        MDF(bz2.BZ2File('path/to/data.bz2', 'rb')),
        MDF(gzip.GzipFile('path/to/data.gzip', 'rb')),
    ],
    version='4.00',
    sync=False,
)

Configure MDF parameters.

The default values for the options are the following:

read_fragment_size = 256 MB
write_fragment_size = 4 MB
use_display_names = True
single_bit_uint_as_bool = False
integer_interpolation = 0 (repeat previous sample)
float_interpolation = 1 (linear interpolation)
raise_on_multiple_occurrences = True
temporary_folder = “”
fill_0_for_missing_computation_channels = False

Parameters:

from_otherMDF, optional

Copy configuration options from other MDF.

Added in version 6.2.0.

read_fragment_sizeint, optional

Size hint of split data blocks. If the initial size is smaller, then no data list is used. The actual split size depends on the data groups’ records size.

write_fragment_sizeint, optional

Size hint of split data blocks. If the initial size is smaller, then no data list is used. The actual split size depends on the data groups’ records size. Maximum size is 4 MB to ensure compatibility with CANape.

use_display_namesbool, optional

Search for display name in the Channel XML comment.

single_bit_uint_as_boolbool, optional

Return single bit channels as np.bool arrays.

integer_interpolationint, optional

Interpolation mode for integer channels.

0 - repeat previous sample
1 - linear interpolation
2 - hybrid interpolation: channels with integer data type (raw values) that have a conversion that outputs float values will use linear interpolation, otherwise the previous sample is used

Changed in version 6.2.0: Added hybrid interpolation mode.

float_interpolationint, optional

Interpolation mode for float channels.

0 - repeat previous sample
1 - linear interpolation

Added in version 6.2.0.

raise_on_multiple_occurrencesbool, optional

Raise MdfException when there are multiple channel occurrences in the file and the get call is ambiguous.

Added in version 6.2.0.

temporary_folderstr, optional

Default folder for temporary files.

Added in version 7.0.0.

fill_0_for_missing_computation_channelsbool, optional

When a channel required by a computed channel is missing, then fill with 0 values. If False, then the computation will fail and the computed channel will be marked as not existing.

Added in version 7.1.0.

convert(version: str | Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30', '4.00', '4.10', '4.11', '4.20', '4.30'], progress: Any | None = None) → MDF[source]¶

Convert MDF to other version.

Parameters:

versionstr: New MDF file version from (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’, ‘3.30’, ‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’).

Returns:

outMDF: New MDF object.

cut(start: float | None = None, stop: float | None = None, whence: int = 0, version: str | Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30', '4.00', '4.10', '4.11', '4.20', '4.30'] | None = None, include_ends: bool = True, time_from_zero: bool = False, inplace: bool = False, progress: Any | None = None) → MDF[source]¶

Cut MDF. start and stop are absolute values or values relative to the first timestamp depending on the whence argument.

Parameters:

startfloat, optional

Start time; default is None. If None, the start of the measurement is used.

stopfloat, optional

Stop time; default is None. If None, the end of the measurement is used.

whenceint, default 0

How to search for the start and stop values.

0 : absolute
1 : relative to first timestamp

versionstr, optional

New MDF file version from (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’, ‘3.30’, ‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’); default is None and in this case the original file version is used.

include_endsbool, default True

Include the start and stop timestamps after cutting the signal. If start and stop are not found in the original timestamps, then the new samples will be computed using interpolation.

time_from_zerobool, default False

Start timestamps from 0s in the cut measurement.

inplacebool, default False

Cut the measurement inplace modifying the original MDF object. This argument overrides the arguments version (gets set to self.version), include_ends (gets set to False) and time_from_zero (gets set to False) and is done only for MDF v4 files.

Added in version 8.7.0.

Returns:

outMDF: New MDF object.

export(fmt: Literal['asc', 'csv', 'hdf5', 'mat', 'parquet'], filename: str | PathLike[str] | None = None, progress: Any | None = None, **kwargs: Unpack[_ExportKwargs]) → None[source]¶

Export MDF to other formats. The MDF file name is used if available, otherwise the filename argument must be provided.

The pandas export option was removed. You should use the method to_dataframe instead.

Parameters:

fmtstr

Can be one of the following:

csv : CSV export that uses the ‘,’ delimiter. This option will generate a new csv file for each data group (<MDFNAME>_DataGroup_<cntr>.csv)
hdf5 : HDF5 file output; each MDF data group is mapped to an HDF5 group with the name ‘DataGroup_<cntr>’ (where <cntr> is the index)
mat : Matlab .mat version 4, 5 or 7.3 export. If single_time_base=False, the channels will be renamed in the mat file to ‘D<cntr>_<channel name>’. The channel group master will be renamed to ‘DM<cntr>_<channel name>’ (<cntr> is the data group index starting from 0)
parquet : export to Apache parquet format
asc : Vector ASCII format for bus logging

Added in version 7.3.3.

filenamestr | path-like, optional

Export file name.

Other Parameters:

single_time_basebool, default False

Resample all channels to common time base.

rasterfloat | array-like | str, optional

Time raster for resampling. Valid if single_time_base is True. It can be:

a float step value
a channel name whose timestamps will be used as raster (starting with asammdf 5.5.0)
an array (starting with asammdf 5.5.0)

See resample for examples of using this argument.

time_from_zerobool, default True

Adjust time channel to start from 0.

use_display_namesbool, default True

Use display name instead of standard channel name, if available.

empty_channels{‘skip’, ‘zeros’}, default ‘skip’

Behaviour for channels without samples.

format{‘5’, ‘4’, ‘7.3’}, default ‘5’

Only valid for mat export.

oned_as{‘row’, ‘column’}, default ‘row’

Only valid for mat export.

reduce_memory_usagebool, default False

Reduce memory usage by converting all float columns to float32 and searching for minimum dtype that can represent the values found in integer columns.

compressionstr | bool, optional

Compression to be used.

for parquet : ‘GZIP’, ‘SNAPPY’ or ‘LZ4’
for hfd5 : ‘gzip’, ‘lzf’ or ‘szip’
for mat : bool

Added in version 8.1.0: Added LZ4 compression after changing to pyarrow.

time_as_datebool, default False

Export time as local timezone datetime; only valid for CSV export.

Added in version 5.8.0.

ignore_value2text_conversionsbool, default False

Valid only for the channels that have value to text conversions and if raw=False. If this is True, then the raw numeric values will be used, and the conversion will not be applied.

Added in version 5.8.0.

rawbool, default False

Export all channels using the raw values.

Added in version 6.0.0.

delimiterstr, default ‘,’

Only valid for CSV: see cpython documentation for csv.Dialect.delimiter.

Added in version 6.2.0.

doublequotebool, default True

Only valid for CSV: see cpython documentation for csv.Dialect.doublequote.

Added in version 6.2.0.

escapecharstr, default ‘”’

Only valid for CSV: see cpython documentation for csv.Dialect.escapechar.

Added in version 6.2.0.

lineterminatorstr, default ‘\r\n’

Only valid for CSV: see cpython documentation for csv.Dialect.lineterminator.

Added in version 6.2.0.

quotecharstr, default ‘”’

Only valid for CSV: see cpython documentation for csv.Dialect.quotechar.

Added in version 6.2.0.

quotingstr, default ‘MINIMAL’

Only valid for CSV: see cpython documentation for csv.Dialect.quoting. Use the last part of the quoting constant name.

Added in version 6.2.0.

add_unitsbool, default False

Only valid for CSV: add the channel units on the second row of the CSV file.

Added in version 7.1.0.

extract_bus_logging(database_files: dict[Literal['CAN', 'LIN'], Iterable[tuple[str | PathLike[str] | CanMatrix, int]]], version: str | Literal['4.00', '4.10', '4.11', '4.20', '4.30'] | None = None, ignore_value2text_conversion: bool = True, prefix: str = '', progress: Callable[[int, int], None] | Any | None = None) → MDF[source]¶

Extract all possible CAN signals using the provided databases.

Changed in version 6.0.0: Renamed from extract_can_logging.

Parameters:

database_filesdict: Each key will contain an iterable of database files for that bus type. The supported bus types are “CAN” and “LIN”. The iterables will contain the (database, valid bus) pairs. The database can be a str, pathlib.Path or canmatrix.CanMatrix object. The valid bus is an integer specifying for which bus channel the database can be applied; 0 means any bus channel.

Changed in version 6.0.0: Added canmatrix.CanMatrix type.

Changed in version 6.3.0: Added bus channel filter.
versionstr, optional: Output file version.
ignore_value2text_conversionbool, default True: Ignore value to text conversions.

Added in version 5.23.0.
prefixstr, default ‘’: Prefix that will be added to the channel group names and signal names in the output file.

Added in version 6.3.0.

Returns:

mdfMDF: New MDF object that contains the succesfully extracted signals.

Examples

Extract CAN and LIN bus logging.

>>> mdf = asammdf.MDF(r'bus_logging.mf4')
>>> databases = {
...     "CAN": [("file1.dbc", 0), ("file2.arxml", 2)],
...     "LIN": [("file3.dbc", 0)],
... }
>>> extracted = mdf.extract_bus_logging(database_files=databases)

Extract just LIN bus logging.

>>> mdf = asammdf.MDF(r'bus_logging.mf4')
>>> databases = {
...     "LIN": [("file3.dbc", 0)],
... }
>>> extracted = mdf.extract_bus_logging(database_files=databases)

Return new MDF object that contains only the channels listed in the channels argument.

Parameters:

channelslist

List of items to be selected; each item can be:

a channel name string
(channel name, group index, channel index) list or tuple
(channel name, group index) list or tuple
(None, group index, channel index) list or tuple

versionstr, optional

New MDF file version from (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’, ‘3.30’, ‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’); default is None and in this case the original file version is used.

Returns:

mdfMDF: New MDF object.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> t = np.arange(5)
>>> s = np.ones(5)
>>> mdf = MDF()
>>> mdf.configure(raise_on_multiple_occurrences=False)
>>> for i in range(4):
...     sigs = [Signal(s * (i * 10 + j), t, name='SIG') for j in range(1, 4)]
...     mdf.append(sigs)

Select channel “SIG” (the first occurrence, which is group 0 index 1), channel “SIG” from group 3 index 1, channel “SIG” from group 2 (the first occurrence, which is index 1), and channel from group 1 index 2.

>>> filtered = mdf.filter(['SIG', ('SIG', 3, 1), ['SIG', 2], (None, 1, 2)])
>>> for gp_nr, ch_nr in filtered.channels_db['SIG']:
...     print(filtered.get(group=gp_nr, index=ch_nr))
<Signal SIG:
        samples=[ 1.  1.  1.  1.  1.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">
<Signal SIG:
        samples=[ 31.  31.  31.  31.  31.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">
<Signal SIG:
        samples=[ 21.  21.  21.  21.  21.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">
<Signal SIG:
        samples=[ 12.  12.  12.  12.  12.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">

get_group(index: int, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, time_from_zero: bool = True, empty_channels: Literal['skip', 'zeros'] = 'skip', use_display_names: bool = False, time_as_date: bool = False, reduce_memory_usage: bool = False, raw: bool | dict[str, bool] = False, ignore_value2text_conversions: bool = False, only_basenames: bool = False) → DataFrame[source]¶

Get channel group as a pandas DataFrame. If there are multiple occurrences for the same channel name, then a counter will be used to make the names unique (<original_name>_<counter>).

Parameters:

indexint

Channel group index.

rasterfloat | array-like | str, optional

New raster that can be:

a float step value
a channel name whose timestamps will be used as raster (starting with asammdf 5.5.0)
an array (starting with asammdf 5.5.0)

See resample for examples of using this argument.

time_from_zerobool, default True

Adjust time channel to start from 0.

empty_channels{‘skip’, ‘zeros’}, default ‘skip’

Behaviour for channels without samples.

Added in version 5.8.0.

use_display_namesbool, default False

Use display name instead of standard channel name, if available.

time_as_datebool, default False

The DataFrame index will contain the datetime timestamps according to the measurement start time. If True, then the argument time_from_zero will be ignored.

reduce_memory_usagebool, default False

Reduce memory usage by converting all float columns to float32 and searching for minimum dtype that can represent the values found in integer columns.

rawbool | dict, default False

The DataFrame will contain the raw channel values.

Added in version 5.7.0.

Changed in version 8.0.0: Provide individual raw mode based on a dict. The dict keys are channel names and each value is a boolean that sets whether to return raw samples for that channel. The key ‘__default__’ is mandatory and sets the raw mode for all channels not specified.

ignore_value2text_conversionsbool, default False

Valid only for the channels that have value to text conversions and if raw=False. If this is True, then the raw numeric values will be used, and the conversion will not be applied.

Added in version 5.8.0.

only_basenamesbool, default False

Use just the field names, without prefix, for structures and channel arrays.

Added in version 5.13.0.

Returns:

dataframepandas.DataFrame: Channel group data.

iter_channels(skip_master: bool = True, copy_master: bool = True, raw: bool | dict[str, bool] = False) → Iterator[Signal][source]¶

Generator that yields a Signal for each non-master channel.

Parameters:

skip_masterbool, default True: Do not yield master channels.
copy_masterbool, default True: Copy master for each yielded channel.
rawbool | dict, default False: Return raw channels instead of converted.

Changed in version 8.0.0: Provide individual raw mode based on a dict. The dict keys are channel names and each value is a boolean that sets whether to return raw samples for that channel. The key ‘__default__’ is mandatory and sets the raw mode for all channels not specified.

iter_get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | None = None, samples_only: Literal[False] = False, raw: bool = False) → Iterator[Signal][source]¶

iter_get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | None = None, *, samples_only: Literal[True], raw: bool = False) → Iterator[tuple[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[Any]] | None]]

Iterator over a channel.

This is usefull in case of large files with a small number of channels.

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

Parameters:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.
rasterfloat, optional: Time raster in seconds.
samples_onlybool, default False: If True, return only the channel samples as np.ndarray; if False, return a Signal object.
rawbool, default False: Return channel samples without applying the conversion rule.

iter_groups(raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, time_from_zero: bool = True, empty_channels: Literal['skip', 'zeros'] = 'skip', use_display_names: bool = False, time_as_date: bool = False, reduce_memory_usage: bool = False, raw: bool | dict[str, bool] = False, ignore_value2text_conversions: bool = False, only_basenames: bool = False) → Iterator[DataFrame][source]¶

Generator that yields channel groups as pandas DataFrames. If there are multiple occurrences for the same channel name inside a channel group, then a counter will be used to make the names unique (<original_name>_<counter>).

Parameters:

rasterfloat | array-like | str, optional

New raster that can be:

a float step value
a channel name whose timestamps will be used as raster (starting with asammdf 5.5.0)
an array (starting with asammdf 5.5.0)

See resample for examples of using this argument.

Added in version 5.21.0.

time_from_zerobool, default True

Adjust time channel to start from 0.

empty_channels{‘skip’, ‘zeros’}, default ‘skip’

Behaviour for channels without samples.

Added in version 5.21.0.

use_display_namesbool, default False

Use display name instead of standard channel name, if available.

Added in version 5.21.0.

time_as_datebool, default False

The DataFrame index will contain the datetime timestamps according to the measurement start time. If True, then the argument time_from_zero will be ignored.

reduce_memory_usagebool, default False

Reduce memory usage by converting all float columns to float32 and searching for minimum dtype that can represent the values found in integer columns.

Added in version 5.21.0.

rawbool | dict, default False

The DataFrame will contain the raw channel values.

Added in version 5.21.0.

Changed in version 8.0.0: Provide individual raw mode based on a dict. The dict keys are channel names and each value is a boolean that sets whether to return raw samples for that channel. The key ‘__default__’ is mandatory and sets the raw mode for all channels not specified.

ignore_value2text_conversionsbool, default False

Valid only for the channels that have value to text conversions and if raw=False. If this is True, then the raw numeric values will be used, and the conversion will not be applied.

Added in version 5.21.0.

only_basenamesbool, default False

Use just the field names, without prefix, for structures and channel arrays.

Added in version 5.21.0.

iter_to_dataframe(channels: Sequence[str | tuple[str | None, int, int] | tuple[str, int]] | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, time_from_zero: bool = True, empty_channels: Literal['skip', 'zeros'] = 'skip', use_display_names: bool = False, time_as_date: bool = False, reduce_memory_usage: bool = False, raw: bool | dict[str, bool] = False, ignore_value2text_conversions: bool = False, use_interpolation: bool = True, only_basenames: bool = False, chunk_ram_size: int = 209715200, interpolate_outwards_with_nan: bool = False, numeric_1D_only: bool = False, progress: Callable[[int, int], None] | Any | None = None) → Iterator[DataFrame][source]¶

Generator that yields pandas DataFrames that should not exceed 200 MB of RAM.

Added in version 5.15.0.

Parameters:

channelslist, optional

List of items to be selected; each item can be:

a channel name string
(channel name, group index, channel index) list or tuple
(channel name, group index) list or tuple
(None, group index, channel index) list or tuple

The default is to select all channels.

rasterfloat | array-like | str, optional

New raster that can be:

a float step value
a channel name whose timestamps will be used as raster (starting with asammdf 5.5.0)
an array (starting with asammdf 5.5.0)

See resample for examples of using this argument.

time_from_zerobool, default True

Adjust time channel to start from 0.

empty_channels{‘skip’, ‘zeros’}, default ‘skip’

Behaviour for channels without samples.

use_display_namesbool, default False

Use display name instead of standard channel name, if available.

time_as_datebool, default False

The DataFrame index will contain the datetime timestamps according to the measurement start time. If True, then the argument time_from_zero will be ignored.

reduce_memory_usagebool, default False

Reduce memory usage by converting all float columns to float32 and searching for minimum dtype that can represent the values found in integer columns.

rawbool | dict, default False

The columns will contain the raw values.

Changed in version 8.0.0: Provide individual raw mode based on a dict. The dict keys are channel names and each value is a boolean that sets whether to return raw samples for that channel. The key ‘__default__’ is mandatory and sets the raw mode for all channels not specified.

ignore_value2text_conversionsbool, default False

Valid only for the channels that have value to text conversions and if raw=False. If this is True, then the raw numeric values will be used, and the conversion will not be applied.

use_interpolationbool, default True

Option to perform interpolations when multiple timestamp rasters are present. If False, then DataFrame columns will be automatically filled with NaNs where the DataFrame index values are not found in the current column’s timestamps.

only_basenamesbool, default False

Use just the field names, without prefix, for structures and channel arrays.

chunk_ram_sizeint, default 200 * 1024 * 1024 (= 200 MB)

Desired DataFrame RAM usage in bytes.

interpolate_outwards_with_nanbool, default False

Use NaN values for the samples that lie outside of the original signal’s timestamps.

numeric_1D_onlybool, default False

Only keep the 1D-columns that have numeric values.

Added in version 7.0.0.

Yields:

dataframepandas.DataFrame: Pandas DataFrames that should not exceed 200 MB of RAM.

master_using_raster(raster: float | str | ndarray[tuple[Any, ...], dtype[Any]], endpoint: bool = False) → ndarray[tuple[Any, ...], dtype[Any]][source]¶

Get single master based on the raster.

Parameters:

rasterfloat: New raster.
endpointbool, default False: Include maximum timestamp in the new master.

Returns:

masternp.ndarray: New master.

resample(raster: float | str | ndarray[tuple[Any, ...], dtype[Any]], version: str | Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30', '4.00', '4.10', '4.11', '4.20', '4.30'] | None = None, time_from_zero: bool = False, progress: Callable[[int, int], None] | Any | None = None) → MDF[source]¶

Resample all channels using the given raster. See configure to select the interpolation method for integer and float channels.

Parameters:

rasterfloat | array-like | str

New raster that can be:

a float step value
a channel name whose timestamps will be used as raster (starting with asammdf 5.5.0)
an array (starting with asammdf 5.5.0)

versionstr, optional

New MDF file version from (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’, ‘3.30’, ‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’); default is None and in this case the original file version is used.

time_from_zerobool, default False

Start timestamps from 0s in the resampled measurement.

Returns:

mdfMDF: New MDF object with resampled channels.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> mdf = MDF()
>>> sig = Signal(name='S1', samples=[1, 2, 3, 4], timestamps=[1, 2, 3, 4])
>>> mdf.append(sig)
>>> sig = Signal(name='S2', samples=[1, 2, 3, 4], timestamps=[1.1, 3.5, 3.7, 3.9])
>>> mdf.append(sig)

Resample to a float step value.

>>> resampled = mdf.resample(raster=0.1)
>>> resampled.select(['S1', 'S2'])
[<Signal S1:
        samples=[1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 4]
        timestamps=[1.  1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 2.  2.1 2.2 2.3 2.4 2.5 2.6 2.7
  2.8 2.9 3.  3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 4. ]
        unit=""
        comment="">,
 <Signal S2:
        samples=[1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 3 3 4 4]
        timestamps=[1.  1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 2.  2.1 2.2 2.3 2.4 2.5 2.6 2.7
  2.8 2.9 3.  3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 4. ]
        unit=""
        comment="">
]

Resample to the timestamps of one of the channels.

>>> resampled = mdf.resample(raster='S2')
>>> resampled.select(['S1', 'S2'])
[<Signal S1:
        samples=[1 3 3 3]
        timestamps=[1.1 3.5 3.7 3.9]
        unit=""
        comment="">,
 <Signal S2:
        samples=[1 2 3 4]
        timestamps=[1.1 3.5 3.7 3.9]
        unit=""
        comment="">
]

Resample to an arbitrary array of timestamps.

>>> resampled = mdf.resample(raster=[1.9, 2.0, 2.1])
>>> resampled.select(['S1', 'S2'])
[<Signal S1:
        samples=[1 2 2]
        timestamps=[1.9 2.  2.1]
        unit=""
        comment="">,
 <Signal S2:
        samples=[1 1 1]
        timestamps=[1.9 2.  2.1]
        unit=""
        comment="">
]

Resample to the timestamps of one of the channels, and adjust the timestamps to start at 0.

>>> resampled = mdf.resample(raster='S2', time_from_zero=True)
>>> resampled.select(['S1', 'S2'])
[<Signal S1:
        samples=[1 3 3 3]
        timestamps=[0.  2.4 2.6 2.8]
        unit=""
        comment="">,
 <Signal S2:
        samples=[1 2 3 4]
        timestamps=[0.  2.4 2.6 2.8]
        unit=""
        comment="">
]

static scramble(name: str | PathLike[str], skip_attachments: bool = False, progress: Callable[[int, int], None] | Any | None = None, **kwargs: Never) → Path[source]¶

Scramble text blocks and keep original file structure.

Parameters:

namestr | path-like: File name.
skip_attachmentsbool, default False: Skip scrambling of attachments data if True.

Added in version 5.9.0.

Returns:

namepathlib.Path: Name of scrambled file.

search(pattern: str, mode: Literal['plain', 'regex', 'wildcard'] | SearchMode = SearchMode.plain, case_insensitive: bool = False) → list[str][source]¶

Search channels.

Added in version 7.0.0.

Parameters:

patternstr

Search pattern.

mode{‘plain’, ‘regex’, ‘wildcard’} or SearchMode, default SearchMode.plain

Search mode.

plain : normal name search
regex : regular expression based search
wildcard : wildcard based search

case_insensitivebool, default False

Case sensitivity for the channel name search.

Returns:

channelslist[str]: Names of the channels.

Raises:

ValueError: Unsupported search mode.

Examples

>>> mdf = MDF(file_name)
>>> mdf.search('*veh*speed*', case_insensitive=True, mode='wildcard')  # case insensitive wildcard based search
['vehicleAverageSpeed', 'vehicleInstantSpeed', 'targetVehicleAverageSpeed', 'targetVehicleInstantSpeed']
>>> mdf.search('^vehicle.*Speed$', case_insensitive=False, mode='regex')  # case sensitive regex based search
['vehicleAverageSpeed', 'vehicleInstantSpeed']

select(channels: Sequence[str | tuple[str | None, int, int] | tuple[str, int]], record_offset: int = 0, raw: bool | dict[str, bool] = False, copy_master: bool = True, ignore_value2text_conversions: bool = False, record_count: int | None = None, validate: bool = False) → list[Signal][source]¶

Retrieve the channels listed in the channels argument as Signal objects.

Note

The dataframe argument was removed in version 5.8.0, use the to_dataframe method instead.

Parameters:

channelslist

List of items to be selected; each item can be:

a channel name string
(channel name, group index, channel index) list or tuple
(channel name, group index) list or tuple
(None, group index, channel index) list or tuple

record_offsetint, optional

Record number offset; optimization to get the last part of signal samples.

rawbool | dict, default False

Get raw channel samples.

Changed in version 8.0.0: Provide individual raw mode based on a dict. The dict keys are channel names and each value is a boolean that sets whether to return raw samples for that channel. The key ‘__default__’ is mandatory and sets the raw mode for all channels not specified.

copy_masterbool, default True

Option to get a new timestamps array for each selected Signal or to use a shared array for channels of the same channel group.

ignore_value2text_conversionsbool, default False

Valid only for the channels that have value to text conversions and if raw=False. If this is True, then the raw numeric values will be used, and the conversion will not be applied.

Changed in version 5.8.0.

record_countint, optional

Number of records to read; default is None and in this case all available records are used.

validatebool, default False

Consider the invalidation bits.

Added in version 5.16.0.

Returns:

signalslist: List of Signal objects based on the input channel list.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> t = np.arange(5)
>>> s = np.ones(5)
>>> mdf = MDF()
>>> mdf.configure(raise_on_multiple_occurrences=False)
>>> for i in range(4):
...     sigs = [Signal(s * (i * 10 + j), t, name='SIG') for j in range(1, 4)]
...     mdf.append(sigs)

Select channel “SIG” (the first occurrence, which is group 0 index 1), channel “SIG” from group 3 index 1, channel “SIG” from group 2 (the first occurrence, which is index 1), and channel from group 1 index 2.

>>> mdf.select(['SIG', ('SIG', 3, 1), ['SIG', 2], (None, 1, 2)])
[<Signal SIG:
        samples=[ 1.  1.  1.  1.  1.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">,
 <Signal SIG:
        samples=[ 31.  31.  31.  31.  31.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">,
 <Signal SIG:
        samples=[ 21.  21.  21.  21.  21.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">,
 <Signal SIG:
        samples=[ 12.  12.  12.  12.  12.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">
]

static stack(files: Sequence[MDF | FileLike | str | PathLike[str]], version: str | Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30', '4.00', '4.10', '4.11', '4.20', '4.30'] = '4.10', sync: bool = True, progress: Any | None = None, **kwargs: Unpack[_StackKwargs]) → MDF[source]¶

Stack several files and return the stacked MDF object.

Parameters:

fileslist | tuple: List of MDF file names or MDF, zipfile.ZipFile, bz2.BZ2File or gzip.GzipFile instances.

Changed in version 6.2.0: Added support for zipfile.ZipFile, bz2.BZ2File and gzip.GzipFile.
versionstr, default ‘4.10’: Merged file version.
syncbool, default True: Sync the files based on the start of measurement.
use_display_namesbool, default False: Use display name instead of standard channel name, if available.
process_bus_loggingbool, default True: Controls whether the bus processing of MDF v4 files is done when the file is loaded.

Added in version 8.1.0.

Returns:

stackedMDF: New MDF object with stacked channels.

Examples

>>> stacked = MDF.stack(
    [
        'path/to/file.mf4',
        MDF(BytesIO(data)),
        MDF(zipfile.ZipFile('data.zip')),
        MDF(bz2.BZ2File('path/to/data.bz2', 'rb')),
        MDF(gzip.GzipFile('path/to/data.gzip', 'rb')),
    ],
    version='4.00',
    sync=False,
)

property start_time: datetime¶

Getter and setter of the measurement start timestamp.

Returns:

timestampdatetime.datetime: Start timestamp.

to_dataframe(channels: Sequence[str | tuple[str | None, int, int] | tuple[str, int]] | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, time_from_zero: bool = True, empty_channels: Literal['skip', 'zeros'] = 'skip', use_display_names: bool = False, time_as_date: bool = False, reduce_memory_usage: bool = False, raw: bool | dict[str, bool] = False, ignore_value2text_conversions: bool = False, use_interpolation: bool = True, only_basenames: bool = False, interpolate_outwards_with_nan: bool = False, numeric_1D_only: bool = False, progress: Callable[[int, int], None] | Any | None = None, use_polars: Literal[False] = False) → DataFrame[source]¶

to_dataframe(channels: Sequence[str | tuple[str | None, int, int] | tuple[str, int]] | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, time_from_zero: bool = True, empty_channels: Literal['skip', 'zeros'] = 'skip', use_display_names: bool = False, time_as_date: bool = False, reduce_memory_usage: bool = False, raw: bool | dict[str, bool] = False, ignore_value2text_conversions: bool = False, use_interpolation: bool = True, only_basenames: bool = False, interpolate_outwards_with_nan: bool = False, numeric_1D_only: bool = False, progress: Callable[[int, int], None] | Any | None = None, use_polars: Literal[True] = False) → pl.DataFrame

to_dataframe(channels: Sequence[str | tuple[str | None, int, int] | tuple[str, int]] | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, time_from_zero: bool = True, empty_channels: Literal['skip', 'zeros'] = 'skip', use_display_names: bool = False, time_as_date: bool = False, reduce_memory_usage: bool = False, raw: bool | dict[str, bool] = False, ignore_value2text_conversions: bool = False, use_interpolation: bool = True, only_basenames: bool = False, interpolate_outwards_with_nan: bool = False, numeric_1D_only: bool = False, progress: Callable[[int, int], None] | Any | None = None, use_polars: bool = False) → pd.DataFrame | 'pl.DataFrame'

Generate a pandas DataFrame.

Parameters:

channelslist, optional

List of items to be selected; each item can be:

a channel name string
(channel name, group index, channel index) list or tuple
(channel name, group index) list or tuple
(None, group index, channel index) list or tuple

The default is to select all channels.

rasterfloat | array-like | str, optional

New raster that can be:

a float step value
a channel name whose timestamps will be used as raster (starting with asammdf 5.5.0)
an array (starting with asammdf 5.5.0)

See resample for examples of using this argument.

time_from_zerobool, default True

Adjust time channel to start from 0.

empty_channels{‘skip’, ‘zeros’}, default ‘skip’

Behaviour for channels without samples.

use_display_namesbool, default False

Use display name instead of standard channel name, if available.

time_as_datebool, default False

The DataFrame index will contain the datetime timestamps according to the measurement start time. If True, then the argument time_from_zero will be ignored.

reduce_memory_usagebool, default False

Reduce memory usage by converting all float columns to float32 and searching for minimum dtype that can represent the values found in integer columns.

rawbool | dict, default False

The columns will contain the raw values.

Added in version 5.7.0.

Changed in version 8.0.0: Provide individual raw mode based on a dict. The dict keys are channel names and each value is a boolean that sets whether to return raw samples for that channel. The key ‘__default__’ is mandatory and sets the raw mode for all channels not specified.

ignore_value2text_conversionsbool, default False

Valid only for the channels that have value to text conversions and if raw=False. If this is True, then the raw numeric values will be used, and the conversion will not be applied.

Added in version 5.8.0.

use_interpolationbool, default True

Option to perform interpolations when multiple timestamp rasters are present. If False, then DataFrame columns will be automatically filled with NaNs where the DataFrame index values are not found in the current column’s timestamps.

Added in version 5.11.0.

only_basenamesbool, default False

Use just the field names, without prefix, for structures and channel arrays.

Added in version 5.13.0.

interpolate_outwards_with_nanbool, default False

Use NaN values for the samples that lie outside of the original signal’s timestamps.

Added in version 5.15.0.

numeric_1D_onlybool, default False

Only keep the 1D-columns that have numeric values.

use_polarsbool, default False

Return polars.DataFrame instead of pandas.DataFrame.

Added in version 8.1.0.

Returns:

dataframepandas.DataFrame or polars.DataFrame: Channel data.

whereis(channel: str, source_name: str | None = None, source_path: str | None = None, acq_name: str | None = None) → tuple[tuple[int, int], ...][source]¶

Get occurrences of channel name in the file.

Parameters:

channelstr: Channel name string.
source_namestr, optional: Filter occurrences on source name.
source_pathstr, optional: Filter occurrences on source path.
acq_namestr, optional: Filter occurrences on channel group acquisition name.

Added in version 6.0.0.

Returns:

tuple[tuple[int, int], …]: (gp_idx, cn_idx) pairs.

Examples

>>> mdf = MDF(file_name)
>>> mdf.whereis('VehicleSpeed')  # "VehicleSpeed" exists in the file
((1, 2), (2, 4))
>>> mdf.whereis('VehicleSPD')  # "VehicleSPD" doesn't exist in the file
()

MDF3¶

class asammdf.blocks.mdf_v3.MDF3(name: str | PathLike[str] | FileLike | None = None, version: Literal['2.00', '2.10', '2.14', '3.00', '3.10', '3.20', '3.30'] = '3.30', channels: list[str] | None = None, **kwargs: Unpack[Kwargs])[source]

The header attribute is a HeaderBlock.

The groups attribute is a list of Group objects, each one with the following attributes:

data_group - DataGroup object
channel_group - ChannelGroup object
channels - list of Channel objects with the same order as found in the MDF file
channel_dependencies - list of ChannelArrayBlock objects in case of channel arrays; list of Channel objects in case of structure channel composition
data_blocks - list of DataBlockInfo objects, each one containing address, type, size and other information about the block
data_location- integer code for data location (original file, temporary file or memory)
data_block_addr - list of raw samples starting addresses
data_block_type - list of codes for data block type
data_block_size - list of raw samples block size
sorted - sorted indicator flag
record_size - dict that maps record IDs to record sizes in bytes
size - total size of data block for the current group
trigger - Trigger object for current group

Parameters:

namestr | path-like | file-like, optional: MDF file name (if provided it must be a real file name) or file-like object.
versionstr, default ‘3.30’: MDF file version (‘2.00’, ‘2.10’, ‘2.14’, ‘3.00’, ‘3.10’, ‘3.20’ or ‘3.30’).
callbackfunction, optional: Function to call to update the progress; the function must accept two arguments (the current progress and maximum progress value).

Attributes:

channels_dbdict: Used for fast channel access by name; for each name key the value is a list of (group index, channel index) tuples.
groupslist: List of data group dicts.
headerHeaderBlock: MDF file header.
identificationFileIdentificationBlock: MDF file start block.
last_call_infodict | None: A dict to hold information about the last called method.

Added in version 5.12.0.
masters_dbdict: Used for fast master channel access; for each group index key the value is the master channel index.
namepathlib.Path: MDF file name.
versionstr: MDF version.

add_trigger(group: int, timestamp: float, pre_time: float = 0, post_time: float = 0, comment: str = '') → None[source]

Add trigger to data group.

Parameters:

groupint: Group index.
timestampfloat: Trigger time.
pre_timefloat, default 0: Trigger pre time.
post_timefloat, default 0: Trigger post time.
commentstr, optional: Trigger comment.

append(signals: list[Signal] | Signal, acq_name: str | None = None, acq_source: Source | None = None, comment: str = 'Python', common_timebase: bool = False, units: dict[str, str] | None = None) → int[source]

append(signals: DataFrame, acq_name: str | None = None, acq_source: Source | None = None, comment: str = 'Python', common_timebase: bool = False, units: dict[str, str] | None = None) → None

Append a new data group.

For channel dependencies type Signals, the samples attribute must be a np.recarray.

Parameters:

signalslist | Signal | pandas.DataFrame: List of Signal objects, or a single Signal object, or a pandas DataFrame object. All bytes columns in the DataFrame must be latin-1 encoded.
acq_namestr, optional: Channel group acquisition name.
acq_sourceSource, optional: Channel group acquisition source.
commentstr, default ‘Python’: Channel group comment.
common_timebasebool, default False: Flag to hint that the signals have the same timebase. Only set this if you know for sure that all appended channels share the same time base.
unitsdict, optional: Will contain the signal units mapped to the signal names when appending a pandas DataFrame.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> import pandas as pd

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])
>>> s1 = Signal(samples=s1, timestamps=t, unit='+', name='Positive')
>>> s2 = Signal(samples=s2, timestamps=t, unit='-', name='Negative')
>>> s3 = Signal(samples=s3, timestamps=t, unit='flts', name='Floats')
>>> mdf = MDF(version='3.30')
>>> mdf.append([s1, s2, s3], comment='created by asammdf')

Case 2: VTAB conversions from channels inside another file.

>>> mdf1 = MDF('in.mdf')
>>> ch1 = mdf1.get("Channel1_VTAB")
>>> ch2 = mdf1.get("Channel2_VTABR")
>>> mdf2 = MDF('out.mdf')
>>> mdf2.append([ch1, ch2], comment='created by asammdf')
>>> df = pd.DataFrame.from_dict({'s1': np.array([1, 2, 3, 4, 5]), 's2': np.array([-1, -2, -3, -4, -5])})
>>> units = {'s1': 'V', 's2': 'A'}
>>> mdf2.append(df, units=units)

close() → None[source]: Call this just before the object is not used anymore to clean up the temporary file and close the file object.

extend(index: int, signals: Sequence[tuple[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[bool]] | None]]) → None[source]

Extend a group with new samples.

signals contains (values, invalidation_bits) pairs for each extended signal. Since MDF3 does not support invalidation bits, the second item of each pair must be None. The first pair is the master channel’s pair, and the next pairs must respect the same order in which the signals were appended. The samples must have raw or physical values according to the signals used for the initial append.

Parameters:

indexint: Group index.
signalssequence: Sequence of (np.ndarray, None) tuples.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> 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])
>>> s1 = Signal(samples=s1, timestamps=t, unit='+', name='Positive')
>>> s2 = Signal(samples=s2, timestamps=t, unit='-', name='Negative')
>>> s3 = Signal(samples=s3, timestamps=t, unit='flts', name='Floats')
>>> mdf = MDF(version='3.30')
>>> mdf.append([s1, s2, s3], comment='created by asammdf')
>>> t = np.array([0.006, 0.007, 0.008, 0.009, 0.010])
>>> mdf.extend(0, [(t, None), (s1.samples, None), (s2.samples, None), (s3.samples, None)])

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, samples_only: Literal[False] = False, data: tuple[bytes, int, int | None] | None = None, raw: bool = False, ignore_invalidation_bits: bool = False, record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → Signal[source]

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, *, samples_only: Literal[True], data: tuple[bytes, int, int | None] | None = None, raw: bool = False, ignore_invalidation_bits: bool = False, record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → tuple[ndarray[tuple[Any, ...], dtype[Any]], None]

Get channel samples.

The channel can be specified in two ways:

Using the first positional argument name.
- If there are multiple occurrences for this channel, then the group and index arguments can be used to select a specific group.
- If there are multiple occurrences for this channel and either the group or index arguments 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:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.
rasterfloat, optional: Time raster in seconds.
samples_onlybool, default False: If True, return only the channel samples as np.ndarray; if False, return a Signal object.
databytes, optional: Prevent redundant data read by providing the raw data group samples.
rawbool, default False: Return channel samples without applying the conversion rule.
ignore_invalidation_bitsbool, default False: Only defined to have the same API with the MDF v4.
record_offsetint, optional: If data=None, use this to select the record offset from which the group data should be loaded.
record_countint, optional: Number of records to read; default is None and in this case all available records are used.
skip_channel_validationbool, default False: Skip validation of channel name, group index and channel index. If True, the caller has to make sure that the group and index arguments are provided and are correct.

Added in version 7.0.0.

Returns:

res(np.ndarray, None) | Signal

Returns Signal if samples_only=False (default option), otherwise returns a (np.ndarray, None) tuple (for compatibility with MDF v4 class).

The Signal samples are:

np.recarray for channels that have CDBLOCK or BYTEARRAY type channels
np.ndarray for all the rest

Raises:

MdfException

if the channel name is not found
if the group index is out of range
if the channel index is out of range
if there are multiple channel occurrences in the file and the arguments name, group, index are ambiguous. This behaviour can be turned off by setting raise_on_multiple_occurrences to False.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> t = np.arange(5)
>>> s = np.ones(5)
>>> mdf = MDF(version='3.30')
>>> for i in range(4):
...     sigs = [Signal(s * (i * 10 + j), t, name='Sig') for j in range(1, 4)]
...     mdf.append(sigs)

Specifying only the channel name is not enough when there are multiple channels with that name.

>>> mdf.get('Sig')
MdfException: Multiple occurrences for channel "Sig": ((0, 1), (0, 2),
(0, 3), (1, 1), (1, 2), (1, 3), (2, 1), (2, 2), (2, 3), (3, 1), (3, 2),
(3, 3)). Provide both "group" and "index" arguments to select another
data group

In this case, adding the group number is also not enough since there are multiple channels with that name in that group.

>>> mdf.get('Sig', 1)
MdfException: Multiple occurrences for channel "Sig": ((1, 1), (1, 2),
(1, 3)). Provide both "group" and "index" arguments to select another
data group

Get the channel named “Sig” from group 1, channel index 2.

>>> mdf.get('Sig', 1, 2)
<Signal Sig:
        samples=[ 12.  12.  12.  12.  12.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">

Get the channel from group 2 and channel index 1.

>>> mdf.get(None, 2, 1)
<Signal Sig:
        samples=[ 21.  21.  21.  21.  21.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">
>>> mdf.get(group=2, index=1)
<Signal Sig:
        samples=[ 21.  21.  21.  21.  21.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">

get_channel_comment(name: str | None = None, group: int | None = None, index: int | None = None) → str[source]

Get channel comment.

The channel can be specified in two ways:

Using the first positional argument name.
- If there are multiple occurrences for this channel, then the group and index arguments can be used to select a specific group.
- If there are multiple occurrences for this channel and either the group or index arguments 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.

Parameters:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.

Returns:

commentstr: Found channel comment.

get_channel_name(group: int, index: int) → str[source]

Get channel name.

Parameters:

groupint: 0-based group index.
indexint: 0-based channel index.

Returns:

namestr: Found channel name.

get_channel_unit(name: str | None = None, group: int | None = None, index: int | None = None) → str[source]

Get channel unit.

The channel can be specified in two ways:

Using the first positional argument name.
- If there are multiple occurrences for this channel, then the group and index arguments can be used to select a specific group.
- If there are multiple occurrences for this channel and either the group or index arguments 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.

Parameters:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.

Returns:

unitstr: Found channel unit.

get_master(index: int, data: tuple[bytes, int, int | None] | None = None, record_offset: int = 0, record_count: int | None = None, one_piece: bool = False) → ndarray[tuple[Any, ...], dtype[Any]][source]

Get master channel samples for the given group.

Parameters:

indexint: Group index.
data(bytes, int), optional: (data block raw bytes, fragment offset).
record_offsetint, optional: If data=None, use this to select the record offset from which the group data should be loaded.
record_countint, optional: Number of records to read; default is None and in this case all available records are used.

Returns:

tnp.ndarray: Master channel samples.

info() → dict[str, object][source]

Get MDF information as a dict.

Examples

>>> mdf = MDF('test.mdf')
>>> mdf.info()

iter_get_triggers() → Iterator[TriggerInfoDict][source]

Generator that yields triggers.

Yields:

trigger_infodict

Trigger information with the following keys:

comment : trigger comment
time : trigger time
pre_time : trigger pre time
post_time : trigger post time
index : trigger index
group : data group index of trigger

save(dst: str | PathLike[str], overwrite: bool = False, compression: Literal[0, 1, 2, 3, 4, 5] | v4c.CompressionAlgorithm = 0, progress: Any | None = None, add_history_block: bool = True) → Path[source]

Save MDF to dst. If overwrite is True, then the destination file is overwritten, otherwise the file name is appended with ‘.<cntr>’, where ‘<cntr>’ is the first counter that produces a new file name that does not already exist in the filesystem.

Parameters:

dststr | path-like: Destination file name.
overwritebool, default False: Overwrite flag.
compressionint, optional: Does nothing for MDF version 3; introduced here to share the same API as MDF version 4 files.

Returns:

output_filepathlib.Path: Path to saved file.

property start_time: datetime

Getter and setter of the measurement start timestamp.

Returns:

timestampdatetime.datetime: Start timestamp.

MDF4¶

class asammdf.blocks.mdf_v4.MDF4(name: str | PathLike[str] | FileLike | None = None, version: Literal['4.00', '4.10', '4.11', '4.20', '4.30'] = '4.10', channels: list[str] | None = None, **kwargs: Unpack[Kwargs])[source]

The header attribute is a HeaderBlock.

The groups attribute is a list of Group objects, each one with the following attributes:

data_group - DataGroup object
channel_group - ChannelGroup object
channels - list of Channel objects with the same order as found in the MDF file
channel_dependencies - list of ChannelArrayBlock objects in case of channel arrays; list of Channel objects in case of structure channel composition
data_blocks - list of DataBlockInfo objects, each one containing address, type, size and other information about the block
data_location - integer code for data location (original file, temporary file or memory)
data_block_addr - list of raw samples starting addresses
data_block_type - list of codes for data block type
data_block_size - list of raw samples block size
sorted - sorted indicator flag
record_size - dict that maps record IDs to record sizes in bytes (including invalidation bytes)
param - row size used for transposition, in case of transposed zipped blocks

Parameters:

namestr | path-like | file-like, optional: MDF file name (if provided it must be a real file name) or file-like object.
versionstr, default ‘4.10’: MDF file version (‘4.00’, ‘4.10’, ‘4.11’, ‘4.20’).
use_display_namesbool, default True: Parse the XML channel comment to search for the display name; XML parsing is quite expensive so setting this to False can decrease the loading times very much.
remove_source_from_channel_namesbool, default False: Remove source from channel names (“SpeedXCP3” -> “Speed”).
compact_vlsd (False)bool, optional: Use slower method to save the exact sample size for VLSD channels.
column_storagebool, default True: Use column storage for MDF version >= 4.20.
passwordbytes | str, optional: Use this password to decode encrypted attachments.

Attributes:

attachmentslist: List of file attachments.
channels_dbdict: Used for fast channel access by name; for each name key the value is a list of (group index, channel index) tuples.
eventslist: List event blocks.
file_historylist: List of (FileHistory, TextBlock) pairs.
groupslist: List of data group dicts.
headerHeaderBlock: MDF file header.
identificationFileIdentificationBlock: MDF file start block.
last_call_infodict | None: A dict to hold information about the last called method.

Added in version 5.12.0.
masters_dbdict: Used for fast master channel access; for each group index key the value is the master channel index.
namepathlib.Path: MDF file name.
versionstr: MDF version.

append(signals: DataFrame, acq_name: str | None = None, acq_source: Source | None = None, comment: str = 'Python', common_timebase: bool = False, units: dict[str, str] | None = None) → None[source]

append(signals: list[Signal] | Signal, acq_name: str | None = None, acq_source: Source | None = None, comment: str = 'Python', common_timebase: bool = False, units: dict[str, str] | None = None) → int

Append a new data group.

For channel dependencies type Signals, the samples attribute must be a np.recarray.

Parameters:

signalslist | Signal | pandas.DataFrame: List of Signal objects, or a single Signal object, or a pandas DataFrame object. All bytes columns in the DataFrame must be utf-8 encoded.
acq_namestr, optional: Channel group acquisition name.
acq_sourceSource, optional: Channel group acquisition source.
commentstr, default ‘Python’: Channel group comment.
common_timebasebool, default False: Flag to hint that the signals have the same timebase. Only set this if you know for sure that all appended channels share the same time base.
unitsdict, optional: Will contain the signal units mapped to the signal names when appending a pandas DataFrame.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> import pandas as pd

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])
>>> s1 = Signal(samples=s1, timestamps=t, unit='+', name='Positive')
>>> s2 = Signal(samples=s2, timestamps=t, unit='-', name='Negative')
>>> s3 = Signal(samples=s3, timestamps=t, unit='flts', name='Floats')
>>> mdf = MDF(version='4.10')
>>> mdf.append([s1, s2, s3], comment='created by asammdf')

Case 2: VTAB conversions from channels inside another file.

>>> mdf1 = MDF('in.mf4')
>>> ch1 = mdf1.get("Channel1_VTAB")
>>> ch2 = mdf1.get("Channel2_VTABR")
>>> mdf2 = MDF('out.mf4')
>>> mdf2.append([ch1, ch2], comment='created by asammdf')
>>> mdf2.append(ch1, comment='just a single channel')
>>> df = pd.DataFrame.from_dict({'s1': np.array([1, 2, 3, 4, 5]), 's2': np.array([-1, -2, -3, -4, -5])})
>>> units = {'s1': 'V', 's2': 'A'}
>>> mdf2.append(df, units=units)

attach(data: bytes, file_name: str | PathLike[str] | None = None, hash_sum: bytes | None = None, comment: str = '', compression: bool = True, mime: str = 'application/octet-stream', embedded: bool = True, password: str | bytes | None = None, compression_type: str = 'deflate') → int[source]

Attach embedded attachment as application/octet-stream.

Parameters:

databytes: Data to be attached.
file_namestr | path-like, optional: File name.
hash_sumbytes, optional: MD5 of the data.
commentstr, optional: Attachment comment.
compressionbool, default True: Use compression for embedded attachment data.
mimestr, default ‘application/octet-stream’: Mime type.
embeddedbool, default True: Attachment is embedded in the file.
passwordstr | bytes, optional: Password used to encrypt the data using AES256 encryption.

Added in version 7.0.0.
compression_typestr, default “deflate”: compression type starting with MDF v4.30. Can be “deflate”, “lz4” or “zstd”

Added in version 8.8.0.

Returns:

indexint: New attachment index.

close() → None[source]: Call this just before the object is not used anymore to clean up the temporary file and close the file object.

extend(index: int, signals: Sequence[tuple[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[bool]] | None]]) → None[source]

Extend a group with new samples.

signals contains (values, invalidation_bits) pairs for each extended signal. The first pair is the master channel’s pair, and the next pairs must respect the same order in which the signals were appended. The samples must have raw or physical values according to the signals used for the initial append.

Parameters:

indexint: Group index.
signalssequence: Sequence of (np.ndarray, np.ndarray) tuples.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> 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])
>>> s1 = Signal(samples=s1, timestamps=t, unit='+', name='Positive')
>>> s2 = Signal(samples=s2, timestamps=t, unit='-', name='Negative')
>>> s3 = Signal(samples=s3, timestamps=t, unit='flts', name='Floats')
>>> mdf = MDF(version='4.10')
>>> mdf.append([s1, s2, s3], comment='created by asammdf')
>>> t = np.array([0.006, 0.007, 0.008, 0.009, 0.010])

Extend without invalidation bits.

>>> mdf.extend(0, [(t, None), (s1.samples, None), (s2.samples, None), (s3.samples, None)])

Extend with some invalidation bits.

>>> s1_inv = np.array([0, 0, 0, 1, 1], dtype=bool)
>>> mdf.extend(0, [(t, None), (s1.samples, s1_inv), (s2.samples, None), (s3.samples, None)])

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, samples_only: Literal[False] = False, data: Fragment | None = None, raw: bool = False, ignore_invalidation_bits: bool = False, record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → Signal[source]

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, *, samples_only: Literal[True], data: Fragment | None = None, raw: bool = False, ignore_invalidation_bits: Literal[False] = False, record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → tuple[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[bool]] | None]

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, *, samples_only: Literal[True], data: Fragment | None = None, raw: bool = False, ignore_invalidation_bits: Literal[True], record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → tuple[ndarray[tuple[Any, ...], dtype[Any]], None]

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, *, samples_only: Literal[True], data: Fragment | None = None, raw: bool = False, ignore_invalidation_bits: bool = False, record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → tuple[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[bool]] | None]

get(name: str | None = None, group: int | None = None, index: int | None = None, raster: float | str | ndarray[tuple[Any, ...], dtype[Any]] | None = None, samples_only: bool = False, data: Fragment | None = None, raw: bool = False, ignore_invalidation_bits: bool = False, record_offset: int = 0, record_count: int | None = None, skip_channel_validation: bool = False) → Signal | tuple[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[bool]] | None]

Get channel samples. The raw data group samples are not loaded to memory so it is advised to use filter or select instead of performing several get calls.

The channel can be specified in two ways:

Using the first positional argument name.
- If there are multiple occurrences for this channel, then the group and index arguments can be used to select a specific group.
- If there are multiple occurrences for this channel and either the group or index arguments 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:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.
rasterfloat, optional: Time raster in seconds.
samples_onlybool, default False: If True, return only the channel samples as np.ndarray; if False, return a Signal object.
dataFragment, optional: Prevent redundant data read by providing the raw data group samples.
rawbool, default False: Return channel samples without applying the conversion rule.
ignore_invalidation_bitsbool, default False: Option to ignore invalidation bits.
record_offsetint, optional: If data=None, use this to select the record offset from which the group data should be loaded.
record_countint, optional: Number of records to read; default is None and in this case all available records are used.
skip_channel_validationbool, default False: Skip validation of channel name, group index and channel index. If True, the caller has to make sure that the group and index arguments are provided and are correct.

Added in version 7.0.0.

Returns:

res(np.ndarray, np.ndarray) | Signal

Returns Signal if samples_only=False (default option), otherwise returns a (np.ndarray, np.ndarray) tuple of samples and invalidation bits. If invalidation bits are not used or if ignore_invalidation_bits is False, then the second item will be None.

The Signal samples are:

np.recarray for channels that have composition/channel array address or for channels of type CANOPENDATE, CANOPENTIME
np.ndarray for all the rest

Raises:

MdfException

if the channel name is not found
if the group index is out of range
if the channel index is out of range
if there are multiple channel occurrences in the file and the arguments name, group, index are ambiguous. This behaviour can be turned off by setting raise_on_multiple_occurrences to False.

Examples

>>> from asammdf import MDF, Signal
>>> import numpy as np
>>> t = np.arange(5)
>>> s = np.ones(5)
>>> mdf = MDF(version='4.10')
>>> for i in range(4):
...     sigs = [Signal(s * (i * 10 + j), t, name='Sig') for j in range(1, 4)]
...     mdf.append(sigs)

Specifying only the channel name is not enough when there are multiple channels with that name.

>>> mdf.get('Sig')
MdfException: Multiple occurrences for channel "Sig": ((0, 1), (0, 2),
(0, 3), (1, 1), (1, 2), (1, 3), (2, 1), (2, 2), (2, 3), (3, 1), (3, 2),
(3, 3)). Provide both "group" and "index" arguments to select another
data group

In this case, adding the group number is also not enough since there are multiple channels with that name in that group.

>>> mdf.get('Sig', 1)
MdfException: Multiple occurrences for channel "Sig": ((1, 1), (1, 2),
(1, 3)). Provide both "group" and "index" arguments to select another
data group

Get the channel named “Sig” from group 1, channel index 2.

>>> mdf.get('Sig', 1, 2)
<Signal Sig:
        samples=[ 12.  12.  12.  12.  12.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">

Get the channel from group 2 and channel index 1.

>>> mdf.get(None, 2, 1)
<Signal Sig:
        samples=[ 21.  21.  21.  21.  21.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">
>>> mdf.get(group=2, index=1)
<Signal Sig:
        samples=[ 21.  21.  21.  21.  21.]
        timestamps=[ 0.  1.  2.  3.  4.]
        unit=""
        comment="">

get_bus_signal(bus: Literal['CAN', 'LIN'], name: str, database: CanMatrix | str | PathLike[str] | None = None, ignore_invalidation_bits: bool = False, data: Fragment | None = None, raw: bool = False, ignore_value2text_conversion: bool = True) → Signal[source]

Get a signal decoded from a raw bus logging. The currently supported buses are CAN and LIN (LDF databases are not supported, they need to be converted to DBC and fed to this function).

Added in version 6.0.0.

Parameters:

busstr: “CAN” or “LIN”.
namestr: Signal name.
databasestr | path-like | CanMatrix, optional: Path of external CAN/LIN database file (.dbc or .arxml) or canmatrix.CanMatrix.

Changed in version 6.0.0: db and database arguments were merged into this single argument.
ignore_invalidation_bitsbool, default False: Option to ignore invalidation bits.
dataFragment, optional: Data bytes as a Fragment.
rawbool, default False: Return channel samples without applying the conversion rule.
ignore_value2text_conversionbool, default True: Return channel samples without values that have a description in .dbc or .arxml file.

Returns:

sigSignal: Signal object with the physical values.

get_can_signal(name: str, database: CanMatrix | str | PathLike[str] | None = None, ignore_invalidation_bits: bool = False, data: Fragment | None = None, raw: bool = False, ignore_value2text_conversion: bool = True) → Signal[source]

Get CAN message signal. You can specify an external CAN database path or a canmatrix database object that has already been loaded from a file.

The signal name can be specified in the following ways:

CAN<ID>.<MESSAGE_NAME>.<SIGNAL_NAME> - the ID value starts from 1 and must match the ID found in the measurement (the source CAN bus ID). Example: CAN1.Wheels.FL_WheelSpeed
CAN<ID>.CAN_DataFrame_<MESSAGE_ID>.<SIGNAL_NAME> - the ID value starts from 1 and the MESSAGE_ID is the decimal message ID as found in the database. Example: CAN1.CAN_DataFrame_218.FL_WheelSpeed
<MESSAGE_NAME>.<SIGNAL_NAME> - in this case the first occurrence of the message name and signal are returned (the same message could be found on multiple CAN buses; for example on CAN1 and CAN3). Example: Wheels.FL_WheelSpeed
CAN_DataFrame_<MESSAGE_ID>.<SIGNAL_NAME> - in this case the first occurrence of the message name and signal are returned (the same message could be found on multiple CAN buses; for example on CAN1 and CAN3). Example: CAN_DataFrame_218.FL_WheelSpeed
<SIGNAL_NAME> - in this case the first occurrence of the signal name is returned (the same signal name could be found in multiple messages and on multiple CAN buses). Example: FL_WheelSpeed

Parameters:

namestr: Signal name.
databasestr | path-like | CanMatrix, optional: Path of external CAN database file (.dbc or .arxml) or canmatrix.CanMatrix.

Changed in version 6.0.0: db and database arguments were merged into this single argument.
ignore_invalidation_bitsbool, default False: Option to ignore invalidation bits.
dataFragment, optional: Data bytes as a Fragment.
rawbool, default False: Return channel samples without applying the conversion rule.
ignore_value2text_conversionbool, default True: Return channel samples without values that have a description in .dbc or .arxml file.

Returns:

sigSignal: Signal object with the physical values.

get_channel_comment(name: str | None = None, group: int | None = None, index: int | None = None) → str[source]

Get channel comment.

The channel can be specified in two ways:

Using the first positional argument name.
- If there are multiple occurrences for this channel, then the group and index arguments can be used to select a specific group.
- If there are multiple occurrences for this channel and either the group or index arguments 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.

Parameters:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.

Returns:

commentstr: Found channel comment.

get_channel_name(group: int, index: int) → str[source]

Get channel name.

Parameters:

groupint: 0-based group index.
indexint: 0-based channel index.

Returns:

namestr: Found channel name.

get_channel_unit(name: str | None = None, group: int | None = None, index: int | None = None) → str[source]

Get channel unit.

The channel can be specified in two ways:

Using the first positional argument name.
- If there are multiple occurrences for this channel, then the group and index arguments can be used to select a specific group.
- If there are multiple occurrences for this channel and either the group or index arguments 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.

Parameters:

namestr, optional: Name of channel.
groupint, optional: 0-based group index.
indexint, optional: 0-based channel index.

Returns:

unitstr: Found channel unit.

get_invalidation_bits(group_index: int, pos_invalidation_bit: int, fragment: Fragment, one_piece: bool = False) → InvalidationArray | None[source]

Get invalidation indexes of the channels in the given group.

Parameters:

group_indexint: Group index.
pos_invalidation_bitint: Channel invalidation bit position.
fragmentFragment: Data bytes as a Fragment.
one_piecebool: onley one piece was given in the get call

Returns:

invalidation_bitsiterable: Iterable of valid channel indexes; if all are valid None is returned.

get_lin_signal(name: str, database: CanMatrix | str | Path | None = None, ignore_invalidation_bits: bool = False, data: Fragment | None = None, raw: bool = False, ignore_value2text_conversion: bool = True) → Signal[source]

Get LIN message signal. You can specify an external LIN database path or a canmatrix database object that has already been loaded from a file.

The signal name can be specified in the following ways:

LIN_Frame_<MESSAGE_ID>.<SIGNAL_NAME> - Example: LIN_Frame_218.FL_WheelSpeed
<MESSAGE_NAME>.<SIGNAL_NAME> - Example: Wheels.FL_WheelSpeed
<SIGNAL_NAME> - Example: FL_WheelSpeed

Added in version 6.0.0.

Parameters:

namestr: Signal name.
databasestr | path-like | CanMatrix, optional: Path of external LIN database file (.dbc, .arxml or .ldf) or canmatrix.CanMatrix.
ignore_invalidation_bitsbool, default False: Option to ignore invalidation bits.
dataFragment, optional: Data bytes as a Fragment.
rawbool, default False: Return channel samples without applying the conversion rule.
ignore_value2text_conversionbool, default True: Return channel samples without values that have a description in .dbc, .arxml or .ldf file.

Returns:

sigSignal: Signal object with the physical values.

get_master(index: int, data: Fragment | None = None, record_offset: int = 0, record_count: int | None = None, one_piece: bool = False) → ndarray[tuple[Any, ...], dtype[Any]][source]

Get master channel samples for the given group.

Parameters:

indexint: Group index.
dataFragment, optional: Data bytes as a Fragment.
record_offsetint, optional: If data=None, use this to select the record offset from which the group data should be loaded.
record_countint, optional: Number of records to read; default is None and in this case all available records are used.

Returns:

t, virtual_master_conversion(np.ndarray, ChannelConversion | None): Master channel samples and virtual master conversion.

info() → dict[str, object][source]

Get MDF information as a dict.

Examples

>>> mdf = MDF('test.mdf')
>>> mdf.info()

save(dst: FileLike | str | PathLike[str], overwrite: bool = False, compression: Literal[0, 1, 2, 3, 4, 5] | CompressionAlgorithm = CompressionAlgorithm.NO_COMPRESSION, progress: Any | None = None, add_history_block: bool = True) → Path[source]

Save MDF to dst. If overwrite is True, then the destination file is overwritten, otherwise the file name is appended with ‘.<cntr>’, where ‘<cntr>’ is the first counter that produces a new file name that does not already exist in the filesystem.

Parameters:

dststr | path-like | file-like

Destination file name.

overwritebool, default False

Overwrite flag.

compressionint, default 0

Use compressed data blocks; valid since MDF version 4.10.

0 - no compression
1 - deflate (slower, but produces smaller files)
2 - transposition + deflate (slowest, but produces the smallest files)
3 - zstd (a bit slower than lz4 but double compression ratio)
4 - transposition + zstd (a bit slower than lz4 but double compression ratio)
5 - lz4 (fastest speed but lower compression ratio compared to zstd)
6 - transposition + lz4 (fastest speed but lower compression ratio compared to zstd)

Changed in version 8.8.0: added zstd and lz4 compression options; only available for MDF version >= 4.30

add_history_blockbool, default True

Option to add file history block.

Returns:

output_filepathlib.Path: Path to saved file.

property start_time: datetime

Getter and setter of the measurement start timestamp.

Returns:

timestampdatetime.datetime: Start timestamp.

Signal¶

The Signal represents a channel described by its samples and timestamps. It can perform arithmetic operations against other Signal objects or numeric types. The operations are computed in respect to the timestamps (time-correct). The non-float signals are not interpolated, instead the last value relative to the current timestamp is used. samples, timestamps and name are mandatory arguments.

Parameters:

samplesarray-like: Signal samples.
timestampsarray-like: Signal timestamps.
unitstr, optional: Signal unit.
namestr: Signal name.
conversiondict | channel conversion block, optional: Dict that contains extra conversion information about the signal.
commentstr, optional: Signal comment.
rawbool, default True: Signal samples are raw values, with no physical conversion applied. Deprecated
master_metadatatuple, optional: Master name and sync type.
display_namesdict, optional: Display names used by MDF version 3.
attachmenttuple, optional: Channel attachment and name from MDF version 4.
sourceSource, optional: Source information named tuple.
bit_countint, optional: Bit count; useful for integer channels.
invalidation_bitsarray-like, optional: Channel invalidation bits.
encodingstr, optional: Encoding for string signals.
flagsint, optional: Flags for user-defined attributes and stream sync.

astype(np_type: DTypeLike) → Signal[source]¶

Return a new Signal with samples of dtype np_type.

Parameters:

np_typenp.dtype: New numpy dtype.

Returns:

signalSignal: New Signal with the samples of dtype np_type.

copy() → Signal[source]¶: Copy all attributes to a new Signal.

cut(start: float | None = None, stop: float | None = None, include_ends: bool = True, integer_interpolation_mode: Literal[0, 1, 2] | IntegerInterpolation = IntegerInterpolation.REPEAT_PREVIOUS_SAMPLE, float_interpolation_mode: Literal[0, 1] | FloatInterpolation = FloatInterpolation.LINEAR_INTERPOLATION) → Signal[source]¶

Cut the signal according to the start and stop values, by using the insertion indexes in the signal’s time axis.

Parameters:

startfloat, optional

Start timestamp for cutting.

stopfloat, optional

Stop timestamp for cutting.

include_endsbool, default True

Include the start and stop timestamps after cutting the signal. If start and stop are not found in the original timestamps, then the new samples will be computed using interpolation.

integer_interpolation_modeint, default 0

Interpolation mode for integer signals.

0 - repeat previous sample
1 - linear interpolation
2 - hybrid interpolation: channels with integer data type (raw values) that have a conversion that outputs float values will use linear interpolation, otherwise the previous sample is used

Added in version 6.2.0.

float_interpolation_modeint, default 1

Interpolation mode for float channels.

0 - repeat previous sample
1 - linear interpolation

Added in version 6.2.0.

Returns:

resultSignal: New Signal cut from the original.

Examples

>>> from asammdf import Signal
>>> import numpy as np
>>> old_sig = Signal(np.arange(0.03, 100, 0.05), np.arange(0.03, 100, 0.05), name='SIG')
>>> new_sig = old_sig.cut(1.0, 10.5)
>>> new_sig.timestamps[0], new_sig.timestamps[-1]
(1.0, 10.5)

>>> new_sig = old_sig.cut(1.0, 10.5, include_ends=False)
>>> new_sig.timestamps[0], new_sig.timestamps[-1]
(1.03, 10.48)

>>> new_sig = old_sig.cut(1.0, 10.5, float_interpolation_mode=0)
>>> new_sig.samples[0], new_sig.samples[-1]
(0.98, 10.48)

extend(other: Signal) → Signal[source]¶

Extend Signal with samples from another Signal.

Parameters:

otherSignal

Returns:

signalSignal: New extended Signal.

interp(new_timestamps: ndarray[tuple[Any, ...], dtype[Any]] | list[float], integer_interpolation_mode: Literal[0, 1, 2] | IntegerInterpolation = IntegerInterpolation.REPEAT_PREVIOUS_SAMPLE, float_interpolation_mode: Literal[0, 1] | FloatInterpolation = FloatInterpolation.LINEAR_INTERPOLATION) → Signal[source]¶

Return a new Signal interpolated using the new_timestamps.

Parameters:

new_timestampsnp.ndarray | list

Timestamps used for interpolation.

integer_interpolation_modeint, default 0

Interpolation mode for integer signals.

0 - repeat previous sample
1 - linear interpolation
2 - hybrid interpolation: channels with integer data type (raw values) that have a conversion that outputs float values will use linear interpolation, otherwise the previous sample is used

Added in version 6.2.0.

float_interpolation_modeint, default 1

Interpolation mode for float channels.

0 - repeat previous sample
1 - linear interpolation

Added in version 6.2.0.

Returns:

signalSignal: New interpolated Signal.

physical(copy: bool = True, ignore_value2text_conversions: bool = False) → Signal[source]¶

Get the scaled (physical) samples values.

Parameters:

copybool, default True: Copy the samples and timestamps in the returned Signal.

Added in version 7.4.0.
ignore_value2text_conversionsbool, default False: Make sure that the output signal has numeric samples by ignoring the value to text conversions.

Added in version 8.3.0.

Returns:

physSignal: New Signal with scaled (physical) values.

plot(validate: bool = True) → None[source]¶

Plot Signal samples. Pyqtgraph is used if it is available; in this case see the GUI plot documentation to see the available commands.

Parameters:

validatebool, default True: Apply the invalidation bits.

raw(copy=False)[source]¶

Get the raw samples values Parameters ———- copy : bool, default True

Copy the samples and timestamps in the returned Signal.

Returns:

physSignal: New Signal with raw values.

scaled(copy: bool = True, ignore_value2text_conversions: bool = False) → Signal¶

Get the scaled (physical) samples values.

Parameters:

copybool, default True: Copy the samples and timestamps in the returned Signal.

Added in version 7.4.0.
ignore_value2text_conversionsbool, default False: Make sure that the output signal has numeric samples by ignoring the value to text conversions.

Added in version 8.3.0.

Returns:

physSignal: New Signal with scaled (physical) values.

validate(copy: bool = True) → Signal[source]¶

Apply invalidation bits if they are available for this signal.

Parameters:

copybool, default True: Return a copy of the result.

Added in version 5.12.0.

API¶

MDF¶

MDF3¶

MDF version 2 & 3 blocks¶

MDF4¶

MDF version 4 blocks¶

Signal¶

Table of Contents

Previous topic

Next topic

This Page