dispel.providers.generic.sensor module#

Generic functionality for signal processing steps.

class dispel.providers.generic.sensor.AddGravityAndScale[source]#

Bases: TransformStep

Add gravity to userAcceleration and scale to m/s^2.

The step expects a unique data set id for data_set_ids pointing to a data frame containing both acceleration and gravity with a pandas.DatetimeIndex index.

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: acceleration_x (acceleration_x)>, <RawDataValueDefinition: acceleration_y (acceleration_y)>, <RawDataValueDefinition: acceleration_z (acceleration_z)>]#
get_new_data_set_id()[source]#

Overwrite new_data_set_id.

class dispel.providers.generic.sensor.ComputeGravityRotationMatrices[source]#

Bases: TransformStep

Compute a series of rotation matrices to align sensors to gravity.

This transformation step creates a series of rotation matrices based on the gravity information contained in the accelerometer sensor. This allows to rotate other sensors on a desired orientation related to gravity. This is in particular of interest if we want to measure physical interactions with devices around the plane perpendicular to gravity.

Parameters:

  • target_gravity – The target gravity vector, e.g. (-1, 0, 0) to create rotation matrices that rotate the x-axis of a device onto gravity.

  • level_filter – An optional LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

__init__(data_set_id, target_gravity, **kwargs)[source]#
Parameters:
class dispel.providers.generic.sensor.EuclideanNorm[source]#

Bases: TransformStep

Compute euclidean norm of the specified columns of a raw data set.

Parameters:

  • data_set_id – The data set id of the data set on which the method is to be applied

  • columns – The columns to be considered during the method application.

  • drop_nan – `True if NaN values are to be dropped after transformation.

  • level_filter – An optional dispel.processing.level.LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a dispel.processing.level.LevelIdFilter for convenience.

__init__(data_set_id, columns=None, drop_nan=False, level_filter=None)[source]#
Parameters:
class dispel.providers.generic.sensor.ExtractAverageSignalEnergy[source]#

Bases: NotEmptyDataSetAssertionMixin, ExtractStep

An average signal energy extraction step.

Parameters:

  • sensor – The type of sensor on which the extraction is to be performed.

  • data_set_id – The data set id on which the extraction is to be performed.

  • columns – The columns onto which the signal energy is to be computed.

  • level_filter – An optional LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

__init__(sensor, data_set_id, columns, level_filter=None)[source]#
Parameters:
class dispel.providers.generic.sensor.ExtractPowerSpectrumMeasures[source]#

Bases: NotEmptyDataSetAssertionMixin, ExtractMultipleStep

A measure extraction processing step for power spectrum measures.

Parameters:

  • sensor – The type of sensor on which the extraction is to be performed.

  • data_set_id – The data set id on which the extraction is to be performed.

  • columns – The columns onto which the power spectrum measures are to be extracted.

  • lower_bound – The lower bound of frequencies below which the signal is filtered.

  • upper_bound – The higher bound of frequencies above which the signal is filtered.

  • level_filter – An optional LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

__init__(sensor, data_set_id, columns, lower_bound=None, upper_bound=None, level_filter=None)[source]#
Parameters:
class dispel.providers.generic.sensor.RenameColumns[source]#

Bases: TransformStep

Rename and select columns of a raw data set.

Parameters:

  • data_set_id – The data set id of the time series to be renamed.

  • level_filter – An optional LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

  • kwargs – All arguments passed into this class will serve as a renaming mapping for the raw data set.

__init__(data_set_id, level_filter=None, **kwargs)[source]#
Parameters:
class dispel.providers.generic.sensor.Resample[source]#

Bases: NotEmptyDataSetAssertionMixin, TransformStep

Resample a time-based raw data set to a specific sampling frequency.

The resampling creates a new raw data set which is accessible via the data set comprised of the original one concatenated with _resampled.

Parameters:

  • data_set_id – The data set to be resampled. This has to be a data set that uses a time-based index. You might first have to apply the SetTimestampIndex processing step before you can apply this step.

  • aggregations –

    A list of resampling methods to be applied in order. Each can be any

    method that is also accepted by pandas.DataFrame.agg().

  • columns – The columns to be considered during the resampling.

  • freq – The frequency to resample to. See also pandas.DataFrame.resample() for details. If freq is not provided the frequency is estimated automatically taking the median frequency.

  • max_frequency_distance – An optional integer specifying the maximum accepted distance between the expected frequency and the estimated frequency above which we raise an error.

  • level_filter – An optional dispel.processing.level.LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

__init__(data_set_id, aggregations, columns, freq=None, max_frequency_distance=None, level_filter=None)[source]#
Parameters:
class dispel.providers.generic.sensor.RotateSensorWithGravityRotationMatrices[source]#

Bases: TransformStep

Apply a series of rotation matrices to a sensor.

This is a complementary step to ComputeGravityRotationMatrices and applies the rotation matrices to the specified sensor.

Parameters:

  • data_set_id – The id of the sensor data set to be rotated.

  • columns – The columns of the sensor data set to be considered in the rotation.

  • level_filter – An optional LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

Examples

Assuming you want to rotate the gyroscope vector onto gravity you can achieve this by chaining the following steps:

processing

>>> from dispel.data.raw import DEFAULT_COLUMNS
>>> from dispel.processing import process
>>> from dispel.providers.generic.sensor import (
...     ComputeGravityRotationMatrices,
...     RotateSensorWithGravityRotationMatrices
... )
>>> cols = DEFAULT_COLUMNS
>>> steps = [
...     ComputeGravityRotationMatrices('accelerometer', (-1, 0, 0)),
...     RotateSensorWithGravityRotationMatrices('gyroscope', cols)
... ]
>>> _ = process(reading, steps)  # doctest: +SKIP

The results of the roation are available in the raw data set with the id <data_set_id>_rotated:

processing
:options: +NORMALIZE_WHITESPACE

>>> level = reading.get_level(level_id)  # doctest: +SKIP
>>> level.get_raw_data_set('gyroscope').data.head()  # doctest: +SKIP
          x         y         z                      ts
0  0.035728 -0.021515  0.014879 2020-05-04 17:31:38.574
1 -0.012046  0.005010 -0.009029 2020-05-04 17:31:38.625
2  0.006779  0.000761 -0.003253 2020-05-04 17:31:38.680
3  0.032636 -0.020272 -0.021915 2020-05-04 17:31:38.729
4  0.007495 -0.014061  0.012886 2020-05-04 17:31:38.779
>>> level.get_raw_data_set(
...     'gyroscope_rotated'
... ).data.head()  # doctest: +SKIP
          x         y         z
0 -0.002309 -0.042509 -0.012182
1 -0.003754  0.014983  0.003624
2 -0.002237 -0.002116 -0.006901
3 -0.030461 -0.021654 -0.023656
4  0.001203 -0.019580  0.005924
__init__(data_set_id, columns, level_filter=None)[source]#
Parameters:
class dispel.providers.generic.sensor.SetTimestampIndex[source]#

Bases: TransformStep

Create a new time series based on a date time or time delta column.

Parameters:

  • data_set_id – The data set id of the time series to be transformed.

  • columns – The columns to consider in the new raw data set.

  • time_stamp_column – The time series column name to use as index.

  • level_filter – An optional dispel.processing.level.LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

  • duplicates – The strategy used to handle duplicates. Has to be one of ignore, raise, first, last.

__init__(data_set_id, columns, time_stamp_column='ts', level_filter=None, duplicates=None)[source]#
Parameters:
class dispel.providers.generic.sensor.TransformFindZeroCrossings[source]#

Bases: TransformStep

Find zero crossings in the signal.

To find the zeros, the function identifies the sign change in the signal by differentiating data > 0.

column#

The column to be used to find the zero crossings in the data set

Type:

str

Parameters:

column (str) – See :data:FindZeroCrossings.column`.

__init__(*args, column=None, **kwargs)[source]#
Parameters:

column (str | None) –

column: str#
definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: zero_crossings (Zero-crossings of the signal.)>]#
class dispel.providers.generic.sensor.TransformGyroscope[source]#

Bases: TransformStep

Format gyroscope data to ADS format if not already the case.

On ADS format, the gyroscope is synchronized with the accelerometer. Here we make sure gyroscope is synchronized with the acc data set.

Parameters:

level_filter – An optional dispel.processing.level.LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

data_set_ids: str | Iterable[str] = ['acc', 'gyroscope']#

An iterable of data sets to be being processed

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: x (Rotation speed along the x axis.)>, <RawDataValueDefinition: y (Rotation speed along the y axis.)>, <RawDataValueDefinition: z (Rotation speed along the z axis.)>, <RawDataValueDefinition: ts (time index)>]#
new_data_set_id: str = 'gyroscope'#
class dispel.providers.generic.sensor.TransformUserAcceleration[source]#

Bases: TransformStep

Format accelerometer data to ADS format if not already the case.

Prior to formatting, linear acceleration and gravity are decoupled from acceleration.

Parameters:

level_filter – An optional dispel.processing.level.LevelFilter to determine the levels to be transformed. If no filter is provided, all levels will be transformed. The level_filter also accepts str, LevelIds and lists of either and passes them to a LevelFilter for convenience.

static add_gravity(accelerometer, level, gravity=None)[source]#

Format gravity data to ADS format.

Parameters:
Return type:

DataFrame

data_set_ids: str | Iterable[str] = 'accelerometer'#

An iterable of data sets to be being processed

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: userAccelerationX (Linear Acceleration along the X axis.)>, <RawDataValueDefinition: userAccelerationY (Linear Acceleration along the Y axis.)>, <RawDataValueDefinition: userAccelerationZ (Linear Acceleration along the Z axis.)>, <RawDataValueDefinition: gravityX (gravity component along the X axis.)>, <RawDataValueDefinition: gravityY (gravity component along the Y axis.)>, <RawDataValueDefinition: gravityZ (gravity component along the Z axis.)>, <RawDataValueDefinition: ts (time index)>]#
new_data_set_id: str = 'acc'#
class dispel.providers.generic.sensor.Trim[source]#

Bases: TransformStep

Trim a sensor signal at the beginning and/or end.

Parameters:

  • trim_left – The amount of data to trim from the left side of the sensor readings.

  • trim_right – The amount of data to trim from the right side of the sensor readings.

  • ts_column (str | None) – The column id to be used in the provided raw data set through data_set_ids. If no column is provided, the data set is expected to have a time-based index that is used to trim the data set.

__init__(*args, **kwargs)[source]#
trim_left = Timedelta('0 days 00:00:00')#
trim_right = Timedelta('0 days 00:00:00')#
ts_column: str | None = None#
class dispel.providers.generic.sensor.Upsample[source]#

Bases: Apply

Upsample a time-based raw data set to a specific sampling frequency.

The upsampling creates a new raw data set which is an upsampled version of the original data set identified by data_set_id. The upsampled data set is accessible via the new_data_set_id which is a concatenation of the original data_set_id and a suffix _upsampled.

Parameters:
__init__(interpolation_method, freq, **kwargs)[source]#
Parameters:

  • interpolation_method (str) –

  • freq (float | str) –

get_new_data_set_id()[source]#

Overwrite new_data_set_id.

Return type:

str