psiaudio.buffer module

class SignalBuffer(fs, size, fill_value=nan, dtype=<class 'numpy.float64'>, n_channels=None)

Bases: object

Ringbuffer class that facilitates caching only what we need in memory.

This was written primarily for continuous plotting of data. If the time segment includes uncached data (e.g., prior to the oldest sample in the cache or after the newest sample in the cache), the segment will be padded with fill_value.

Parameters:

• fs (float) – Sampling rate of buffered signal.

• size (float) – Duration of buffer in seconds.

• fill_value (float, optional) – Value to fill missing or invalidated data with, by default np.nan.

• dtype (type, optional) – Data type of the buffer, by default np.double.

• n_channels (int, optional) – Number of channels for the buffer. If None, a 1D buffer is created. By default None.

append_data(data)

Append new data into the right-side of the buffer.

Parameters:

data (ndarray) – The data to append. Must have shape matching n_channels if specified.

Raises:

ValueError – If dimensions or channels of appended data are mismatched.

get_latest(lb, ub=0, fill_value=None)

Returns buffered data relative to the most recently-buffered sample.

Parameters:

• lb (float) – Time in seconds relative to the most recently-buffered sample. Usually will be a negative value.

• ub (float, optional) – Time in seconds relative to the most recently-buffered sample. Usually will be 0 or a negative value. By default 0.

• fill_value (float, optional) – If not None, specifies the value to pad uncached array sections. By default None.

Returns:

Array segment corresponding to the latest cached data.

Return type:

ndarray

Examples

Get the most recent 1 second of buffered data

>>> buffer.get_latest(-1)

Get the buffered data from -2 to -1 relative to current time.

>>> buffer.get_latest(-2, -1)

get_range(lb=None, ub=None)

Get buffered segment corresponding to the absolute time bounds.

Parameters:

• lb (float, optional) – Lower time bound in seconds. If None, uses the start time of the buffer.

• ub (float, optional) – Upper time bound in seconds. If None, uses the end time of the buffer.

Returns:

Array slice for the requested time range.

Return type:

ndarray

get_range_filled(lb, ub, fill_value)

Get buffered segment and pad missing data with fill_value.

Parameters:

• lb (float) – Lower time bound in seconds.

• ub (float) – Upper time bound in seconds.

• fill_value (float) – Value used to pad regions if they fall outside the cached range.

Returns:

Array slice representing the range requested.

Return type:

ndarray

get_range_samples(lb=None, ub=None)

Get buffered segment corresponding to the absolute sample bounds.

Parameters:

• lb (int, optional) – Lower bound in samples. If None, uses the first cached sample.

• ub (int, optional) – Upper bound in samples. If None, uses the most recent sample.

Returns:

Array slice within the buffer.

Return type:

ndarray

Raises:

IndexError – If lb or ub fall completely outside the buffered segment.

get_samples_lb()

Get the lower-bound index specifying the oldest cached sample.

Returns:

Lowest bounds sample index.

Return type:

int

get_samples_ub()

Get the upper-bound index specifying the most recent cached sample.

Returns:

Upper bounds sample index.

Return type:

int

get_time_lb()

Get the lowest valid time bounding the currently cached sequence.

Returns:

Lowest lower-bound time in seconds.

Return type:

float

get_time_ub()

Get the highest valid time bounding the currently cached sequence.

Returns:

Highest upper-bound time in seconds.

Return type:

float

invalidate(t)

Invalidate cached data after the specified time.

Parameters:

t (float) – Time in seconds beyond which data is invalidated.

invalidate_samples(i)

Invalidate cached data after the specified sample index.

Parameters:

i (int) – Sample index beyond which data is invalidated.

resize(size)

Resize buffer to hold the specified number of seconds.

Parameters:

size (float) – New size of the buffer in seconds.

Notes

• This does not allow you to add/remove channels.

• A request to decrease buffer size is ignored.

samples_to_index(i)

Convert absolute sample index to the index within the buffer.

Note that the resulting index can fall outside the populated buffered range.

Parameters:

i (int) – Absolute sample index.

Returns:

Index in the buffer.

Return type:

int

time_to_index(t)

Convert time to index in buffer.

Note that the index may fall out of the buffered range.

Parameters:

t (float) – Time in seconds.

Returns:

Index corresponding to the time.

Return type:

int

time_to_samples(t)

Convert time to samples (re acquisition start).

Parameters:

t (float) – Time in seconds.

Returns:

Number of samples.

Return type:

int