The API documentation

This part of the documentation covers all the interfaces of trsfile.

Overview

This section gives an overview of the main classes and their descriptions.

trsfile.open(path, mode='r', **options)

Reads, modifies or creates a TraceSet with a specific storage engine (defaults to TrsEngine).

Parameters:
  • path (str) – path to the file or directory

  • mode (str) – mode how to open the file or directory (same as the default Python open)

  • options (dict(str, any)) – zero or more options that are passed down to the TraceSet and the storage engine. Available options can be found in the different storage engines. The storage engine can be selected with engine = 'TrsEngine' (default value).

Returns:

instance of a new or initialized TraceSet

Return type:

TraceSet

trsfile.trs_open(path, mode='r', **options)[source]

Reads, modifies or creates a TraceSet with a specific storage engine (defaults to TrsEngine).

Parameters:
  • path (str) – path to the file or directory

  • mode (str) – mode how to open the file or directory (same as the default Python open)

  • options (dict(str, any)) – zero or more options that are passed down to the TraceSet and the storage engine. Available options can be found in the different storage engines. The storage engine can be selected with engine = 'TrsEngine' (default value).

Returns:

instance of a new or initialized TraceSet

Return type:

TraceSet

class trsfile.trace.Trace(sample_coding, samples, parameters=None, title='trace', headers=None, raw_data: bytes = b'')[source]

The Trace class behaves like a list object were each item in the list is a sample of the trace.

When a Trace is initialized the samples are (optionally) converted to a numpy.array depending on the current type of the samples and the provided sample_coding.

class trsfile.trace_set.TraceSet(path, mode='r', **options)[source]

The TraceSet class behaves like a list object were each item in the list is a Trace.

Storing the TraceSet requires knowledge on the format which is resolved through the usage of storage engines (Engine).

class trsfile.engine.trs.TrsEngine(path, mode='x', **options)[source]

This engine supports .trs files from Riscure as specified in the “Trace set coding” document in Inspector.

This engine supports the following options:

Option

Description

headers

Dictionary containing zero or more headers, see trsfile.common.Header

live_update

Performs live update of the TRS file every N traces. True for updating after every trace and False for never.

padding_mode

Padding mode to use. The supported values are: trsfile.common.TracePadding.NONE (default) trsfile.common.TracePadding.AUTO

class trsfile.engine.file.FileEngine(path, mode='x', **options)[source]

This engine tries to save traces to disk in the most versatile and simple manner available. No known tools support this file format and serve only as an intermediate step to later convert it to a supported format.

This is can be useful when the trace length (number of samples) varies as this is often not supported in trace files.

After acquisition, the file can be converted to the proper format with the correct padding mode.

This engine supports the following options:

Option

Description

headers

Dictionary containing zero or more headers, see trsfile.common.Header

class trsfile.common.Header(value)[source]

All headers that are currently supported in the .trs file format as defined in the inspector manual (2018). The storage engine shall try to always store all headers regardless if they are used or not. However, some file formats will have no way of storing arbitrary headers. As such, optional headers can be dropped.

Some headers can be used by trsfile.trace_set.TraceSet or trsfile.trace.Trace to augment their functionality. An example of this is the trsfile.trace.Trace.get_key() method.

class trsfile.common.SampleCoding(value)[source]

Defines the encoding of all the samples in the trace. Bit 4 specifies if it is a float (1) or an integer (0), bits 0 to 3 specifies the length of the value. Finally, bits 5-7 are currently reserved and set to 000.

This class is just a simple lookup table.

class trsfile.common.TracePadding(value)[source]

Defines the padding mode of the samples in each trace. This can be helpful when not all traces will be the same length. This can be set in trsfile.open(), trsfile.trs_open()

Mode

Description

NONE

No padding will be used and an exception will be thrown when traces are not of the same length.

PAD

All traces will be padded with zeroes to the maximum trace length.

TRUNCATE

All traces will be truncated to the minimum trace length.

AUTO

Traces will be clipped or padded in the best possible way the storage engine supports. This could mean data is lost which because retroactive padding is not supported.

Common

class trsfile.common.Header(value)[source]

Bases: Enum

All headers that are currently supported in the .trs file format as defined in the inspector manual (2018). The storage engine shall try to always store all headers regardless if they are used or not. However, some file formats will have no way of storing arbitrary headers. As such, optional headers can be dropped.

Some headers can be used by trsfile.trace_set.TraceSet or trsfile.trace.Trace to augment their functionality. An example of this is the trsfile.trace.Trace.get_key() method.

ACQUISITION_COUPLING_OF_SCOPE = 86
ACQUISITION_DEVICE_ID = 89
ACQUISITION_FREQUENCY_FILTER = 91
ACQUISITION_INPUT_IMPEDANCE = 88
ACQUISITION_OFFSET_OF_SCOPE = 87
ACQUISITION_RANGE_FILTER = 92
ACQUISITION_RANGE_OF_SCOPE = 85
ACQUISITION_TYPE_FILTER = 90
DESCRIPTION = 71
EXTERNAL_CLOCK_BASE = 103
EXTERNAL_CLOCK_FREQUENCY = 102
EXTERNAL_CLOCK_MULTIPLIER = 98
EXTERNAL_CLOCK_PHASE_SHIFT = 99
EXTERNAL_CLOCK_RESAMPLER_ENABLED = 101
EXTERNAL_CLOCK_RESAMPLER_MASK = 100
EXTERNAL_CLOCK_THRESHOLD = 97
EXTERNAL_CLOCK_USED = 96
GO_LAST_TRACE = 106
INPUT_LENGTH = 110
INPUT_OFFSET = 107
KEY_LENGTH = 112
KEY_OFFSET = 109
LABEL_X = 73
LABEL_Y = 74
LENGTH_DATA = 68
LOGARITHMIC_SCALE = 78
NUMBER_OF_ENABLED_CHANNELS = 113
NUMBER_OF_USED_OSCILLOSCOPES = 114
NUMBER_SAMPLES = 66
NUMBER_TRACES = 65
NUMBER_VIEW = 104
OFFSET_X = 72
OUTPUT_LENGTH = 111
OUTPUT_OFFSET = 108
SAMPLE_CODING = 67
SCALE_X = 75
SCALE_Y = 76
TITLE_SPACE = 69
TRACE_BLOCK = 95
TRACE_OFFSET = 77
TRACE_OVERLAP = 105
TRACE_PARAMETER_DEFINITIONS = 119
TRACE_SET_PARAMETERS = 118
TRACE_TITLE = 70
TRS_VERSION = 79
XY_MEASUREMENTS_PER_SPOT = 117
XY_SCAN_HEIGHT = 116
XY_SCAN_WIDTH = 115
classmethod get_mandatory()[source]
classmethod has_value(tag)[source]
class trsfile.common.SampleCoding(value)[source]

Bases: Enum

Defines the encoding of all the samples in the trace. Bit 4 specifies if it is a float (1) or an integer (0), bits 0 to 3 specifies the length of the value. Finally, bits 5-7 are currently reserved and set to 000.

This class is just a simple lookup table.

BYTE = 1
FLOAT = 20
INT = 4
SHORT = 2
property is_float
class trsfile.common.TracePadding(value)[source]

Bases: Enum

Defines the padding mode of the samples in each trace. This can be helpful when not all traces will be the same length. This can be set in trsfile.open(), trsfile.trs_open()

Mode

Description

NONE

No padding will be used and an exception will be thrown when traces are not of the same length.

PAD

All traces will be padded with zeroes to the maximum trace length.

TRUNCATE

All traces will be truncated to the minimum trace length.

AUTO

Traces will be clipped or padded in the best possible way the storage engine supports. This could mean data is lost which because retroactive padding is not supported.

AUTO = 3
NONE = 0
PAD = 1
TRUNCATE = 2

Trace

class trsfile.trace.Trace(sample_coding, samples, parameters=None, title='trace', headers=None, raw_data: bytes = b'')[source]

Bases: object

The Trace class behaves like a list object were each item in the list is a sample of the trace.

When a Trace is initialized the samples are (optionally) converted to a numpy.array depending on the current type of the samples and the provided sample_coding.

get_input()[source]
get_key()[source]
get_output()[source]

TraceSet

class trsfile.trace_set.TraceSet(path, mode='r', **options)[source]

Bases: object

The TraceSet class behaves like a list object were each item in the list is a Trace.

Storing the TraceSet requires knowledge on the format which is resolved through the usage of storage engines (Engine).

append(trace)[source]
close()[source]
extend(traces)[source]
get_header(header)[source]
get_headers()[source]
insert(index, trace)[source]
is_closed()[source]
reverse()[source]
update_header(header, value)[source]
update_headers(headers)[source]

Storage Engines

The TraceSet behaves like a list (it is a list of Traces). Each Trace also behaves like a list (it is a list of samples). This is all on a conceptual level and the storage engine specifies how this conceptual model is translated to a specific file format. This behavior also makes it easy to convert from any (supported) file format to another one.

TrsEngine

class trsfile.engine.trs.TrsEngine(path, mode='x', **options)[source]

Bases: Engine

This engine supports .trs files from Riscure as specified in the “Trace set coding” document in Inspector.

This engine supports the following options:

Option

Description

headers

Dictionary containing zero or more headers, see trsfile.common.Header

live_update

Performs live update of the TRS file every N traces. True for updating after every trace and False for never.

padding_mode

Padding mode to use. The supported values are: trsfile.common.TracePadding.NONE (default) trsfile.common.TracePadding.AUTO

close()[source]

Closes the open file handle if it is opened

get_traces(index: Union[slice, int]) List[Trace][source]

Retrieves zero or more traces from the trace set

Parameters:

index (slice, int) – the slice or index that specifies which traces to get

Returns:

a list of zero or more traces from the trace set

Return type:

Trace, list[Trace]

has_trace_data() bool[source]
is_closed()[source]

Returns if the file backing the trace set is closed

Returns:

True if the file is closed, otherwise False

Return type:

boolean

length()[source]

Returns the total number of traces

Returns:

total number of traces

Return type:

int

read_parameter_data() TraceParameterMap[source]
set_traces(index: Union[slice, int], traces: List[Trace]) None[source]

Inserts zero or more traces into the trace set

Parameters:
  • index (slice, int) – the slice or index that specifies were to insert traces

  • traces (Trace, list[Trace]) – zero or more traces to insert into the trace set

Returns:

None

update_headers(headers: Dict[Header, Any])[source]

Updates zero or more headers

Parameters:

headers (dict(Header, any)) – dictionary of header, value pairs to update

Returns:

a list of the headers that changed

Return type:

list[Header]

update_headers_with_traces_metadata(traces: List[Trace]) None[source]

FileEngine

class trsfile.engine.file.FileEngine(path, mode='x', **options)[source]

Bases: Engine

This engine tries to save traces to disk in the most versatile and simple manner available. No known tools support this file format and serve only as an intermediate step to later convert it to a supported format.

This is can be useful when the trace length (number of samples) varies as this is often not supported in trace files.

After acquisition, the file can be converted to the proper format with the correct padding mode.

This engine supports the following options:

Option

Description

headers

Dictionary containing zero or more headers, see trsfile.common.Header

INFO_FILE = 'traceset.pickle'
close()[source]

Closes the file backing the trace set. It also could perform the final writes to synchronize the file with the trace set.

Returns:

None

del_traces(index)[source]

Deletes zero or more traces from the trace set

Parameters:

index (slice, int) – the slice or index that specifies which traces to delete

Returns:

None

get_traces(index)[source]

Retrieves zero or more traces from the trace set

Parameters:

index (slice, int) – the slice or index that specifies which traces to get

Returns:

a list of zero or more traces from the trace set

Return type:

Trace, list[Trace]

is_closed()[source]

Returns if the file backing the trace set is closed

Returns:

True if the file is closed, otherwise False

Return type:

boolean

length()[source]

Returns the total number of traces

Returns:

total number of traces

Return type:

int

set_traces(index, traces)[source]

Inserts zero or more traces into the trace set

Parameters:
  • index (slice, int) – the slice or index that specifies were to insert traces

  • traces (Trace, list[Trace]) – zero or more traces to insert into the trace set

Returns:

None

update_headers(headers)[source]

Updates zero or more headers

Parameters:

headers (dict(Header, any)) – dictionary of header, value pairs to update

Returns:

a list of the headers that changed

Return type:

list[Header]

Engine

class trsfile.engine.engine.Engine(path, mode='x', **options)[source]

Bases: object

close()[source]

Closes the file backing the trace set. It also could perform the final writes to synchronize the file with the trace set.

Returns:

None

del_traces(index)[source]

Deletes zero or more traces from the trace set

Parameters:

index (slice, int) – the slice or index that specifies which traces to delete

Returns:

None

get_traces(index)[source]

Retrieves zero or more traces from the trace set

Parameters:

index (slice, int) – the slice or index that specifies which traces to get

Returns:

a list of zero or more traces from the trace set

Return type:

Trace, list[Trace]

is_closed()[source]

Returns if the file backing the trace set is closed

Returns:

True if the file is closed, otherwise False

Return type:

boolean

is_read_only()[source]

Returns if the trace set is read-only

Returns:

True if the file is read-only, otherwise False

Return type:

boolean

length()[source]

Returns the total number of traces

Returns:

total number of traces

Return type:

int

read_only = False
set_traces(index, traces)[source]

Inserts zero or more traces into the trace set

Parameters:
  • index (slice, int) – the slice or index that specifies were to insert traces

  • traces (Trace, list[Trace]) – zero or more traces to insert into the trace set

Returns:

None

update_header(header, value)[source]

Updates one specific header

Parameters:
  • header (Header) – header to update

  • value (any) – value of the header to update

Returns:

a list of the headers that changed

Return type:

list[Header]

update_headers(headers)[source]

Updates zero or more headers

Parameters:

headers (dict(Header, any)) – dictionary of header, value pairs to update

Returns:

a list of the headers that changed

Return type:

list[Header]