razorback.signalset module

Classes to handle signals (raw data + meta data)

class razorback.signalset.Inventory(signalsets)

Bases: object

A container for SignalSet objects:

New signalsets can be added with append() and extend().

New inventories are obtained by filtering an inventory with extract_t(), select_channels() and filter().

A SignalSet gathering the inventory content can be created with pack().

Parameters:: signalsets (list of SignalSet objects)

See also

SignalSet

append(obj)

append one element

raise ValueError if obj is not a SignalSet.

extend(seq)

append all elements of a sequence

raise ValueError if elements of seq are not SignalSet.

extract_groups(group_tags): group_tags: [(new_tag, [*old_tags]), …]

extract_t(start, stop, exclude=False): return a new Inventory by applying extract_t() on the content

filter(*patterns)

return a new Inventory with channels matching one of the patterns

Patterns are Unix shell style:

‘*’ matches everything

‘?’ matches any single character

‘[seq]’ matches any character in seq

‘[!seq]’ matches any char not in seq

It’s basically using fnmatch.filter() with select_channels()

property intervals

merge()

pack(keep_multi_tags=True)

return a SignalSet that contains as much as possible of the content.

The rules to build the signalset are:

All the channels defined in the inventory must be present.

All the tags defined in the inventory must be present, unless keep_multi_tags is False, then only the tags targeting single channels are preserved.

Since the result is a SignalSet, it will be composed of disjoint synchronous runs, each run covering all the channels.

property sampling_rates

select_channels(*keys): return a new Inventory by applying select_channels() on the content

select_runs(runs)

property starts

property stops

property tags: set of all the available tags (str)

class razorback.signalset.SignalSet(tags, signal1, signal2, ...)

Bases: object

A tagged group of several synchronous signals.

A SignalSet is meant to gather distinct runs of the same channels. Each run is stored in a SyncSignal and channels are handled with Tags.

It is required that there is no time overlap between runs.

tags may be a Tags object or a dict-like object that will be converted as Tags.

Building SignalSet from others

SignalSet can be combined in two ways:

join(): same channels, union of time intervals

merge(): union of channels, intersection of time intervals

SignalSet can be reduced in three ways:

select_channels: same times, reduce channels

select_runs: same channels, reduce runs

extract_t(): same channels, reduce times (can have less runs)

Syntactic sugar

The merge/join operations can be performed with the intersection(&)/union(|) operators:

- s1 & s2  -->  s1.merge(s2)
- s1 | s2  -->  s1.join(s2)

A fully tagged subset of channels can be obtained through attribute access using tag names:

- s.Ex  -->  s.select_channels('Ex')

Selecting channels/runs can be performed through indexing:

- s[:]                                      -->  s
- s['Ex']                                   -->  s.select_channels('Ex')
- s[['Ex', 'Ey']]                           -->  s.select_channels(['Ex', 'Ey'])
- s[:, 0]                                   -->  s.select_runs(0)
- s[:, [0, 3]]                              -->  s.select_runs([0, 3])
- s[:, s.sampling_rates == 1024]            -->  s.select_runs(s.sampling_rates == 1024)
- s[['Ex', 'Ey'], s.sampling_rates <= 512]  -->  filtering on channels and sampling_rates

Parameters:

tags (Tags or dict) – will be converted as Tags, used to name one or more channels
signal*i* (SyncSignal or SignalSet) – a group of synchronous signals, channels are identified by indices (SyncSignal) or by tags (SignalSet).

See also

SyncSignal, Tags

Example

A SignalSet with 5 runs and 4 channels:

            run 0    run 1    run 2    run 3   run 4

channel 0   ~~~~~~~  ~~~~~~~  ~~~~~~~  ~~~~~~~ ~~~~~~~
channel 1   ~~~~~~~  ~~~~~~~  ~~~~~~~  ~~~~~~~ ~~~~~~~
channel 2   ~~~~~~~  ~~~~~~~  ~~~~~~~  ~~~~~~~ ~~~~~~~
channel 3   ~~~~~~~  ~~~~~~~  ~~~~~~~  ~~~~~~~ ~~~~~~~

There can’t be any missing signals: each channel has a signal in each run. Each run is a SyncSignal containing 4 signals.

Channels can be found by their indices but the tags allow to name groups of channels. If tags is set up as:

tags = Tags(4, Ex=0, Ey=1, Hx=2, Hy=3, E=(0, 1), H=(2, 3))

then one can retrieve one channel or a subset of channels with:

s.Ex  ->  new SignalSet with only channel 0
s.H   ->  new SignalSet with only channel 2 and 3

extract_t(start, stop, exclude=False)

return a SignalSet with reduced time intervals

If exclude=False, all times outside the given interval are skipped. If exclude=True, all times inside the given interval are skipped.

fourier_coefficients(freq, Nper, overlap, window, **kwds)

compute the fourier coefficients at freq of sliding windows

coeffs, discrete_window_data = signal.fourier_coefficients(freq, Nper, overlap, window)

The result include the calibration functions specified in the signal set:

calibrated_coeff = coeff / calib

Parameters:

freq (scalar) – the frequency of the Fourier transform
Nper (int) – number of period in each window window length = Nper / freq * sampling_freq
overlap (float) – must be in [0 ; 0.5] the overlap ratio between windows
window (array or function) – window function to apply before Fourier transform None means no windowing

Returns:

coeffs (list of arrays) – fourier coefficients of each signal of the signal set
discrete_window_data (tuple of list of integer) – data of the sliding discrete window discrete_window_data = (l_Nw, l_Lw, l_shift) l_Nw: number of windows for each run l_Lw: length of the window for each run l_shift: index shift beetwen windows for each run

property intervals: intervals of the runs

join(*others)

return a SignalSet joining different signal sets of the same channels

alias: a | b -> a.join(b)

Join is based on tag names: all the signal sets must have the same tag names. The resulting time intervals are the union of the given signal set intervals.

It is possible to join with a SyncSignal (which has no tags), in this case the order of the data are supposed to match with the SignalSet tags.

merge(*others)

return a SignalSet merging channels of given signal sets

alias: a & b -> a.merge(b)

Merge is based on tag names: the given signal sets can’t have common tag names.

The resulting intervals are the common parts of all the given signal set intervals.

Signal sets sharing an interval must be synchronous.

merge_consecutive_runs()

return a new SignalSet where consecutive runs are merged into one.

!!! calibrations taken from the first run

property nb_channels: number of channels

property nb_runs: number of runs

property sampling_rates: sampling rates of the runs

select_channels(channels)

return a SignalSet containing the selected channels

channels can be one identifier or a sequence of identifiers. An identifier can be a tag name (str) or an index (integer). channels can also be a slice.

select_runs(runs)

return a SignalSet containing the selected runs

runs can be an index (integer), an array of index, a slice or an array of bool. In each case, the behavior is similar to indexing a 1d numpy array.

property signals

the sorted sequence of runs

Type:: tuple of SyncSignal objects

property sizes: sizes of the runs

property starts: starts of the runs

property stops: stops of the runs

property tags: tags mapping names to channel indices

class razorback.signalset.SyncSignal(signals, sampling_rate, start=0, calibrations=None)

Bases: object

A group of synchronous signals.

Signals are said synchronous when they have the same sampling rate, and the same start and stop times.

Parameters:

signals (list of arrays) – the time signals, they all must have the same length
sampling_rate (float) – frequency of sampling (Hz)
start (float) – starting time (seconds) [default = 0.0]
calibrations (list of functions) – must have the same length than signals [default = None] no calibration needed

property calibrations: tuple of calibration functions for each signal channel

property data: tuple of signal data

extract_i(i_start, i_stop, strict=True, include_last=False): new SyncSignal from (i_start, i_stop) indices

extract_t(start, stop, strict=False)

return SyncSignal reduced on (start, stop) time interval

If ‘strict=True’, start and stop time must be in the original interval or an error is raised.

fourier_coefficients(freq, Nper, overlap, window, **kwds)

compute the fourier coefficients at freq of sliding windows

coeffs, discrete_window_data = signal.fourier_coefficients(freq, Nper, overlap, window)

The result include the calibration functions specified in the signal set:

calibrated_coeff = coeff / calib

Parameters:

freq (scalar) – the frequency of the Fourier transform
Nper (int) – number of period in each window window length = Nper / freq * sampling_freq
overlap (float) – must be in [0 ; 0.5] the overlap ratio between windows
window (array or function) – window function to apply before Fourier transform None means no windowing

Returns:

coeffs (list of arrays) – fourier coefficients of each signal of the signal set
discrete_window_data (tuple of integer) – data of the sliding discrete window discrete_window_data = (Nw, Lw, shift) Nw: number of windows Lw: length of the window shift: index shift beetwen windows

property interval: the time interval of the signal set

property sampling_rate: sampling rate of the signal

select(*indices): return a SyncSignal composed of selected channels

property signals

tuple of synchronous signal groups handled

here it’s just (self,)

property size: length of each signal data

property start: start time of the signal

property stop: stop time of the signal

class razorback.signalset.Tags(n, name1=idx1, name2=idx2, ...)

class razorback.signalset.Tags(name1=idx1, name2=idx2, ...)

Bases: TagsBase

Tags handle mappings between names and groups of indices.

A Tags object behaves like a dict but its keys must be legal string names and its values are tuples of integers in a fixed range. New entries of a Tags object are converted in tuples if needed then their content is checked to belong in the fixed range.

Item access can be emulated through attribute access:

tags.name1 –> tags[‘name1’]

tags.name1 = idx1 –> tags[‘name1’] = idx1

Tags also implements the union (|) operator according to the SignalSet class:

tags | signal -> SignalSet(tags, signal)