`lprocess`#

Implement classes for use in live processing applications.

Some of these classes might move to the Acoular module in the future.

`TimeSamplesPhantom`	Propagate signal-processing blocks with a user-defined time delay.
`TimeOutPresenter`	Present live Acoular output through a Bokeh `ColumnDataSource`.
`CalibHelper`	Calibrate individual source channels.
`TimeSamplesPlayback`(args, *kwargs)	Naive class implementation to allow audio playback of .h5 file contents.

class spectacoular.lprocess.TimeSamplesPhantom#

Bases: MaskedTimeSamples, BaseSpectacoular

Propagate signal-processing blocks with a user-defined time delay.

This class delivers existing blocks of data at a configurable time interval. It can be used to simulate a measurement while reading the data from file.

time_delay#: Defines the delay with which the individual data blocks are propagated. Defaults to 1/sample_freq

collect_samples#: Indicates if samples are collected, helper trait to break result loop

trait_widget_mapper: ClassVar[dict[str, type]] = {'basename': <class 'bokeh.models.widgets.inputs.TextInput'>, 'file': <class 'bokeh.models.widgets.inputs.TextInput'>, 'invalid_channels': <class 'bokeh.models.widgets.tables.DataTable'>, 'num_channels': <class 'bokeh.models.widgets.inputs.NumericInput'>, 'num_samples': <class 'bokeh.models.widgets.inputs.NumericInput'>, 'sample_freq': <class 'bokeh.models.widgets.inputs.NumericInput'>, 'start': <class 'bokeh.models.widgets.inputs.NumericInput'>, 'stop': <class 'bokeh.models.widgets.inputs.NumericInput'>}#: dictionary containing the mapping between a class trait attribute and a Bokeh widget. Keys: name of the trait attribute. Values: Bokeh widget.

trait_widget_args: ClassVar[dict[str, dict[str, object]]] = {'basename': {'disabled': True}, 'file': {'disabled': False}, 'invalid_channels': {'columns': [TableColumn(id='p1025', ...)], 'disabled': False, 'editable': True}, 'num_channels': {'disabled': True, 'mode': 'int'}, 'num_samples': {'disabled': True, 'mode': 'int'}, 'sample_freq': {'disabled': True, 'mode': 'float'}, 'start': {'disabled': False, 'mode': 'int'}, 'stop': {'disabled': False, 'mode': 'int'}}#: dictionary containing arguments that belongs to a widget that is created from a trait attribute and should be considered when the widget is built. For example: {“traitname”:{‘disabled’:True,’background_color’:’red’,…}}.

result(num=128)#

Python generator that yields the output block-wise.

Parameters:

numinteger, defaults to 128: This parameter defines the size of the blocks to be yielded (i.e. the number of samples per block) .

Returns:

Samples in blocks of shape (num, num_channels).: The last block may be shorter than num.

get_widgets(trait_widget_mapper=None, trait_widget_args=None)#

Create a mapping between several class trait attributes and Bokeh widgets.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes via the bokehview module. For each attribute provided, it builds a corresponding Bokeh widget.

The function handles multiple cases of View construction:

Default View: the function is called as a method by a BaseSpectacoular derived instance without specifying trait_widget_mapper and trait_widget_args explicitly as function arguments. In this case, the default widget mapping, defined in bokehview, will be used:
```
from spectacoular import RectGrid
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(grid.get_widgets().values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))
```
No Predefined View: get_widgets() is called and a HasTraits derived instance is given as the first argument to the function without any further arguments. In this case, a default mapping is created from all editable traits to create the view.

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(get_widgets(grid).values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))

Custom View: get_widgets() is called by a BaseSpectacoular derived instance and an explicit mapping is given. In this case, the instance attributes (self.trait_widget_mapper, self.trait_widget_args) are superseded.

from spectacoular import RectGrid
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(grid.get_widgets(
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

The same functionality can also be used with HasTraits-derived classes that are not part of SpectAcoular:

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(get_widgets(grid,
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

Parameters:

trait_widget_mapperdict, optional

contains the desired mapping of a variable name (dict key) to a Bokeh widget type (dict value), by default {}

trait_widget_argsdict, optional

contains the desired widget kwargs (dict values) for each variable name (dict key),: by default {}

Returns:

dict: A dictionary containing the variable names as the key and the Bokeh widget instance as value.

set_widgets(**kwargs)#

Set instances of Bokeh widgets to certain trait attributes.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes in bokehview.py. It allows to reference an existing widget to a certain class trait attribute. Expects a class traits name as parameter and the widget instance as value.

For example:

>>> from spectacoular import RectGrid
>>> from bokeh.models.widgets import Select
>>>
>>> rg = RectGrid()
>>> sl = Select(value='10.0')
>>> rg.set_widgets(x_max=sl)

The value of the trait attribute changes to the widgets value when it is different.

Parameters:

**kwargs: The name of the class trait attributes. Depends on the class.

Returns:

None.

start#: Index of the first sample to be considered valid. Default is 0.

stop#: Index of the last sample to be considered valid. If None, all remaining samples from the start index onward are considered valid. Default is None.

invalid_channels#: List of channel indices to be excluded from processing. Default is [].

channels#: A mask or index array representing valid channels. Automatically updated based on the invalid_channels and num_channels_total attributes.

num_channels_total#: Total number of input channels, including invalid channels. (read-only).

num_samples_total#: Total number of samples, including invalid samples. (read-only).

num_channels#: Number of valid input channels after excluding invalid_channels. (read-only)

num_samples#: Number of valid time-domain samples, based on start and stop indices. (read-only)

digest#: A unique identifier for the samples, based on its properties. (read-only)

file#: Full path to the .h5 file containing time-domain data.

basename#: Basename of the .h5 file, set automatically from the file attribute.

data#: A 2D NumPy array containing the time-domain data, shape (num_samples, num_channels).

metadata#: Metadata loaded from the HDF5 file, if available.

sample_freq#: Sampling frequency of the signal, defaults to 1.0

class spectacoular.lprocess.TimeOutPresenter#

Bases: TimeOut, BasePresenter

Present live Acoular output through a Bokeh ColumnDataSource.

This TimeOut-derived class updates the ColumnDataSource from its result method and can be used for automatic presentation of live data.

cdsource#: Bokeh’s ColumnDataSource, updated from result loop

result(num)#

Python generator that yields the output block-wise.

Parameters:

numinteger, defaults to 128: This parameter defines the size of the blocks to be yielded (i.e. the number of samples per block) .

Returns:

Samples in blocks of shape (num, num_channels).: The last block may be shorter than num.

get_widgets(trait_widget_mapper=None, trait_widget_args=None)#

Create a mapping between several class trait attributes and Bokeh widgets.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes via the bokehview module. For each attribute provided, it builds a corresponding Bokeh widget.

The function handles multiple cases of View construction:

Default View: the function is called as a method by a BaseSpectacoular derived instance without specifying trait_widget_mapper and trait_widget_args explicitly as function arguments. In this case, the default widget mapping, defined in bokehview, will be used:
```
from spectacoular import RectGrid
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(grid.get_widgets().values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))
```
No Predefined View: get_widgets() is called and a HasTraits derived instance is given as the first argument to the function without any further arguments. In this case, a default mapping is created from all editable traits to create the view.

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(get_widgets(grid).values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))

Custom View: get_widgets() is called by a BaseSpectacoular derived instance and an explicit mapping is given. In this case, the instance attributes (self.trait_widget_mapper, self.trait_widget_args) are superseded.

from spectacoular import RectGrid
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(grid.get_widgets(
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

The same functionality can also be used with HasTraits-derived classes that are not part of SpectAcoular:

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(get_widgets(grid,
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

Parameters:

trait_widget_mapperdict, optional

contains the desired mapping of a variable name (dict key) to a Bokeh widget type (dict value), by default {}

trait_widget_argsdict, optional

contains the desired widget kwargs (dict values) for each variable name (dict key),: by default {}

Returns:

dict: A dictionary containing the variable names as the key and the Bokeh widget instance as value.

set_widgets(**kwargs)#

Set instances of Bokeh widgets to certain trait attributes.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes in bokehview.py. It allows to reference an existing widget to a certain class trait attribute. Expects a class traits name as parameter and the widget instance as value.

For example:

>>> from spectacoular import RectGrid
>>> from bokeh.models.widgets import Select
>>>
>>> rg = RectGrid()
>>> sl = Select(value='10.0')
>>> rg.set_widgets(x_max=sl)

The value of the trait attribute changes to the widgets value when it is different.

Parameters:

**kwargs: The name of the class trait attributes. Depends on the class.

Returns:

None.

update(**optional_items)#

Update the cdsource attribute.

No processing happens here, since BasePresenter only represents a base class to derive other classes from.

source#: Data source; Generator or derived object.

sample_freq#: Sampling frequency of output signal, as given by source.

num_channels#: Number of channels in output, as given by source.

num_samples#: Number of samples in output, as given by source.

digest#: A unique identifier for the generator, based on its properties. (read-only)

trait_widget_mapper#: dictionary containing the mapping between a class trait attribute and a Bokeh widget. Keys: name of the trait attribute. Values: Bokeh widget.

trait_widget_args#: dictionary containing arguments that belongs to a widget that is created from a trait attribute and should be considered when the widget is built. For example: {“traitname”:{‘disabled’:True,’background_color’:’red’,…}}.

class spectacoular.lprocess.CalibHelper#

Bases: TimeOut, BaseSpectacoular

Calibrate individual source channels.

source#: Data source; Average or derived object.

file#: Name of the file to be saved. If none is given, the name will be automatically generated from a time stamp.

magnitude#: calibration level (e. g. dB or Pa) of calibration device

calibdata#: calibration values determined during evaluation of result(). array of floats with dimension (num_channels, 2)

calibfactor#: calibration factor determined during evaluation of save(). array of floats with dimension (num_channels)

buffer_size#: max elements/averaged blocks to calculate calibration value.

calibstd#: channel-wise allowed standard deviation of calibration values in buffer

delta#: minimum allowed difference in magnitude between the channel to be calibrated and remaining channels.

digest#: A unique identifier for the generator, based on its properties. (read-only)

trait_widget_mapper: ClassVar[dict[str, type]]#: dictionary containing the mapping between a class trait attribute and a Bokeh widget. Keys: name of the trait attribute. Values: Bokeh widget.

trait_widget_args: ClassVar[dict[str, dict[str, object]]]#: dictionary containing arguments that belongs to a widget that is created from a trait attribute and should be considered when the widget is built. For example: {“traitname”:{‘disabled’:True,’background_color’:’red’,…}}.

to_pa(level)#: Convert a sound level to pressure in pascal.

adjust_calib_values()#: Resize calibration arrays to match the number of source channels.

create_filename()#: Create a default filename for calibration output if none is set.

save()#: Save the current calibration factors as an XML file.

result(num)#

Python generator that yields the output block-wise.

Parameters:

numinteger, defaults to 128: This parameter defines the size of the blocks to be yielded (i.e. the number of samples per block) .

Returns:

Samples in blocks of shape (num, num_channels).: The last block may be shorter than num.

get_widgets(trait_widget_mapper=None, trait_widget_args=None)#

Create a mapping between several class trait attributes and Bokeh widgets.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes via the bokehview module. For each attribute provided, it builds a corresponding Bokeh widget.

The function handles multiple cases of View construction:

Default View: the function is called as a method by a BaseSpectacoular derived instance without specifying trait_widget_mapper and trait_widget_args explicitly as function arguments. In this case, the default widget mapping, defined in bokehview, will be used:
```
from spectacoular import RectGrid
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(grid.get_widgets().values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))
```
No Predefined View: get_widgets() is called and a HasTraits derived instance is given as the first argument to the function without any further arguments. In this case, a default mapping is created from all editable traits to create the view.

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(get_widgets(grid).values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))

Custom View: get_widgets() is called by a BaseSpectacoular derived instance and an explicit mapping is given. In this case, the instance attributes (self.trait_widget_mapper, self.trait_widget_args) are superseded.

from spectacoular import RectGrid
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(grid.get_widgets(
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

The same functionality can also be used with HasTraits-derived classes that are not part of SpectAcoular:

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(get_widgets(grid,
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

Parameters:

trait_widget_mapperdict, optional

contains the desired mapping of a variable name (dict key) to a Bokeh widget type (dict value), by default {}

trait_widget_argsdict, optional

contains the desired widget kwargs (dict values) for each variable name (dict key),: by default {}

Returns:

dict: A dictionary containing the variable names as the key and the Bokeh widget instance as value.

set_widgets(**kwargs)#

Set instances of Bokeh widgets to certain trait attributes.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes in bokehview.py. It allows to reference an existing widget to a certain class trait attribute. Expects a class traits name as parameter and the widget instance as value.

For example:

>>> from spectacoular import RectGrid
>>> from bokeh.models.widgets import Select
>>>
>>> rg = RectGrid()
>>> sl = Select(value='10.0')
>>> rg.set_widgets(x_max=sl)

The value of the trait attribute changes to the widgets value when it is different.

Parameters:

**kwargs: The name of the class trait attributes. Depends on the class.

Returns:

None.

sample_freq#: Sampling frequency of output signal, as given by source.

num_channels#: Number of channels in output, as given by source.

num_samples#: Number of samples in output, as given by source.

class spectacoular.lprocess.TimeSamplesPlayback(*args, **kwargs)#

Bases: TimeOut, BaseSpectacoular

Naive class implementation to allow audio playback of .h5 file contents.

The class uses the devices available to the sounddevice library for audio playback. Input and output devices can be listed by

>>> import sounddevice
>>> sounddevice.query_devices()

In the future, this class should work in buffer mode and also write the current frame that is played to a class attribute.

digest#: A unique identifier for the generator, based on its properties. (read-only)

channels#: list containing indices of the channels to be played back.

device#: two-element list containing indices of input and output device to be used for audio playback.

trait_widget_mapper: ClassVar[dict[str, type]]#: dictionary containing the mapping between a class trait attribute and a Bokeh widget. Keys: name of the trait attribute. Values: Bokeh widget.

trait_widget_args: ClassVar[dict[str, dict[str, object]]]#: dictionary containing arguments that belongs to a widget that is created from a trait attribute and should be considered when the widget is built. For example: {“traitname”:{‘disabled’:True,’background_color’:’red’,…}}.

play()#: Play normalized audio from the source channels in channels.

stop()#: Stop audio playback of the file content.

result(num)#: Yield the output block-wise.

get_widgets(trait_widget_mapper=None, trait_widget_args=None)#

Create a mapping between several class trait attributes and Bokeh widgets.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes via the bokehview module. For each attribute provided, it builds a corresponding Bokeh widget.

The function handles multiple cases of View construction:

Default View: the function is called as a method by a BaseSpectacoular derived instance without specifying trait_widget_mapper and trait_widget_args explicitly as function arguments. In this case, the default widget mapping, defined in bokehview, will be used:
```
from spectacoular import RectGrid
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(grid.get_widgets().values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))
```
No Predefined View: get_widgets() is called and a HasTraits derived instance is given as the first argument to the function without any further arguments. In this case, a default mapping is created from all editable traits to create the view.

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.layouts import gridplot

grid = RectGrid()

widgets = list(get_widgets(grid).values())
show(gridplot(widgets, ncols=5, sizing_mode='stretch_both'))

Custom View: get_widgets() is called by a BaseSpectacoular derived instance and an explicit mapping is given. In this case, the instance attributes (self.trait_widget_mapper, self.trait_widget_args) are superseded.

from spectacoular import RectGrid
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(grid.get_widgets(
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

The same functionality can also be used with HasTraits-derived classes that are not part of SpectAcoular:

from acoular import RectGrid
from spectacoular import get_widgets
from bokeh.io import show
from bokeh.models.widgets import Slider
from bokeh.layouts import column

grid = RectGrid()

trait_widget_mapper = {'x_min': Slider}
trait_widget_args = {'x_min': {'title': 'X Min', 'start': -1, 'end': 1, 'step':0.1}}

widgets = list(get_widgets(grid,
      trait_widget_mapper=trait_widget_mapper,
      trait_widget_args=trait_widget_args
).values())
show(column(widgets,sizing_mode='stretch_both'))

Parameters:

trait_widget_mapperdict, optional

contains the desired mapping of a variable name (dict key) to a Bokeh widget type (dict value), by default {}

trait_widget_argsdict, optional

contains the desired widget kwargs (dict values) for each variable name (dict key),: by default {}

Returns:

dict: A dictionary containing the variable names as the key and the Bokeh widget instance as value.

set_widgets(**kwargs)#

Set instances of Bokeh widgets to certain trait attributes.

This function is implemented in all SpectAcoular classes and is added to Acoular’s classes in bokehview.py. It allows to reference an existing widget to a certain class trait attribute. Expects a class traits name as parameter and the widget instance as value.

For example:

>>> from spectacoular import RectGrid
>>> from bokeh.models.widgets import Select
>>>
>>> rg = RectGrid()
>>> sl = Select(value='10.0')
>>> rg.set_widgets(x_max=sl)

The value of the trait attribute changes to the widgets value when it is different.

Parameters:

**kwargs: The name of the class trait attributes. Depends on the class.

Returns:

None.

source#: Data source; Generator or derived object.

sample_freq#: Sampling frequency of output signal, as given by source.

num_channels#: Number of channels in output, as given by source.

num_samples#: Number of samples in output, as given by source.

lprocess#

`lprocess`#