Signals in Notebooks

The sample module introduces the Sample and Waveform classes, a collection of utilities specially intended for analysis of signals in notebooks, although they are also suitable for use outside these.

In this context, a sample is a collection of waveforms, each sample is stored in a directory, managed by SampleManager, with the following structure:

samples
    sample_000
        waveform_000.npz
        waveform_001.npz
        ...
    sample_001
        waveform_000.npz
        waveform_001.npz
        ...
    ...

Each waveform is a .npz file generated with numpy.savez_compressed() with additional metadata.

Each sample in the samples directory is identified by an integer number, and similarly each waveform in each sample is identified by an integer number. For example notebooks where Sample, SampleManager and Waveform are used refer to the other/notebook folders in the repository.

class Waveform

Utility class to handle a waveforms within Sample.

__init__(sid, wid, path)

Class constructor.

Parameters:

wid (int) – The waveform identifier.
path (str) – The path to the waveform file.

property sid: int

The sample identifier of the sample that contains this waveform.

Return type:: int
Returns:: Sample identifier.

property wid: int

The waveform identifier within the sample.

Return type:: int
Returns:: Waveform identifier.

property hvalues: ndarray[Any, dtype[float64]]

The values of the horizontal axis.

Return type:: ndarray[Any, dtype[float64]]
Returns:: The array with the values.

property vvalues: ndarray[Any, dtype[float64]]

The values of the vertical axis.

Return type:: ndarray[Any, dtype[float64]]
Returns:: The array with the values.

property meta: dict[str, Any]

Dictionary with the metadata of the waveform.

Return type:: dict[str, Any]
Returns:: Metadata of the waveform.

class Sample

Sample class with its underlying instances of Waveform for each waveform.

__init__(sid, waveforms)

Class constructor.

Parameters:

sid (int) – The sample identifier.
waveforms (Sequence[Waveform]) – The waveforms for the sample.

property sid: int

The sample identifier for the sample.

Return type:: int
Returns:: The sample identifier.

property waveforms: dict[int, Waveform]

A dictionary with the waveforms, where the keys are waveform identifiers and the values are the waveforms.

Return type:: dict[int, Waveform]
Returns:: Dictionary with the waveforms for the sample.

class SampleManager

Manages the samples in the given root directory.

__init__(root)

Class constructor.

Parameters:: root (str) – Root directory where the samples are located.
Raises:: SignalError – The root directory does not exist.

static plot(row_0, *args, path=None, mode=Mode.LINEAR, points=(), levels=(), row_1=(), row_2=(), row_3=(), cursors=(), **kwargs)

Shortcut for complex plots related to samples, refer to implementation and code snippets for more details.

Parameters:

row_0 (Sequence[tuple[Literal['signal', 'state_levels', 'edges'], Union[tuple[float, float, float, str, str, Signal], tuple[float, float, float, Signal, StateLevels], tuple[float, float, float, Signal, Sequence[Edge]]]]]) – Plot items for the first row.
args – The arguments to pass to the plotter, see Plotter.plot().
path (Optional[str]) – Path where to save the resulting plot, see Plotter.plot(), or None for notebooks.
mode (Mode) – The mode of operation of the plotter, see Plotter.plot().
points (Sequence[Literal['begin', 'intermediate', 'end']]) – When plotting edges, the point of the edges to plot, defaults to all.
levels (Sequence[Literal['highest', 'high', 'high_runt', 'intermediate', 'low_runt', 'low', 'lowest']]) – When plotting state levels, the levels to plot, defaults to all.
row_1 (Sequence[tuple[Literal['signal', 'state_levels', 'edges'], Union[tuple[float, float, float, str, str, Signal], tuple[float, float, float, Signal, StateLevels], tuple[float, float, float, Signal, Sequence[Edge]]]]]) – Plot items for the second row, if any.
row_2 (Sequence[tuple[Literal['signal', 'state_levels', 'edges'], Union[tuple[float, float, float, str, str, Signal], tuple[float, float, float, Signal, StateLevels], tuple[float, float, float, Signal, Sequence[Edge]]]]]) – Plot items for the third row, if any.
row_3 (Sequence[tuple[Literal['signal', 'state_levels', 'edges'], Union[tuple[float, float, float, str, str, Signal], tuple[float, float, float, Signal, StateLevels], tuple[float, float, float, Signal, Sequence[Edge]]]]]) – Plot items for the fourth row, if any.
cursors (Sequence[Cursor]) – Cursors for the plot.
kwargs – The keyword arguments to pass to the plotter, see Plotter.plot().

Raises:

SignalError – An item identifier is invalid or not recognized.

get_sids()

Obtains the existing sample identifiers in the root folder.

Return type:: tuple[int, …]
Returns:: The sample identifiers.

get_wids(sid)

Obtains the waveform identifiers of a sample in the root folder.

Parameters:: sid (int) – The sample identifier.
Return type:: tuple[int, …]
Returns:: The waveform identifiers for the sample.

new(sid, waveforms, overwrite=False)

Creates a new sample with the data for the waveforms provided in the format below:

{
    "wid": "An integer with the waveform identifier",
    "vvalues": "Numpy array with values for the vertical axis of a signal",
    "hvalues": "Numpy array with values for the horizontal axis of a signal"
}

Any other value in the waveform dictionary is stored in the .npz file as metadata.

Parameters:

sid (int) – The sample identifier of the new sample.
waveforms (Sequence[dict[str, Any]]) – The waveforms for the sample following the format described above for each.
overwrite (bool) – Overwrite the sample if it exists, if False then raise exception instead.

Raises:

SignalError – The specified sample already exists and overwrite was set to False.
SignalError – At least one of the waveforms is not in the correct format.

Return type:

Sample

Returns:

The sample created.

load(sid)

Loads the specified sample from the root folder.

Parameters:: sid (int) – The sample identifier.
Raises:: SignalError – The sample specified does not exist.
Return type:: Sample
Returns:: The sample with its waveforms.

save(sid, sample, overwrite=False)

Saves the save to the root folder, overwriting a previous sample if it exists.

Parameters:

sid (int) – The sample identifier.
sample (Sample) – The sample to save.
overwrite (bool) – Overwrite the sample if it exists, if False then raise exception instead.

Return type:

Sample

Returns:

The sample that was just saved.