dispel.signal.core module

Core functionality for signal processing tasks.

dispel.signal.core.amplitude(power_spectrum_)

Compute the amplitude of a signal.

Parameters:

• power_spectrum – An array containing the power spectrum of the signal in question.

• power_spectrum_ (ndarray) –

Returns:

The signal’s amplitude.

Return type:

float

dispel.signal.core.assert_time_series_has_frequency(data)

Check whether a time series contains frequency as index.

Parameters:

data (Series) –

Return type:

None

dispel.signal.core.autocorr(data)

Compute auto-correlation of a signal.

Uses cross-correlation with the same signal as input twice.

Parameters:

data (ndarray[Any, dtype[float64]]) – A signal passed as an iterable of floats.

Returns:

A Tuple containing temporal delays and auto-correlation array.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

dispel.signal.core.autocov(data)

Compute auto-covariance of a signal.

Uses autocovariance from as autocorrelation of demeaned signal.

Parameters:

data (ndarray[Any, dtype[float64]]) – A signal passed as an iterable of floats.

Returns:

A Tuple containing temporal delays and auto-covariance array.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

dispel.signal.core.compute_rotation_matrix_2d(origin, point, angle)

Compute a 2 dimension matrix rotation.

Parameters:

• origin (list) – The origin of the referential.

• point (list) – The point to rotate.

• angle (float) – The angle rotation.

Returns:

The x and y coordinates after rotation.

Return type:

Tuple[float, float]

dispel.signal.core.compute_rotation_matrix_3d(a, b)

Compute a rotation matrix from unit vector a onto unit vector b.

Parameters:

• a (ndarray) – The first unit vector

• b (ndarray) – The second unit vector

Returns:

The rotation matrix from unit vector a onto unit vector b.

Return type:

numpy.ndarray

dispel.signal.core.cross_corr(data_1, data_2)

Compute cross-correlation between two signals.

Uses cross-correlation with the same signal as input twice.

Parameters:

• data_1 (ndarray[Any, dtype[float64]]) – A first signal passed as an iterable of floats.

• data_2 (ndarray[Any, dtype[float64]]) – A second signal passed as an iterable of floats.

Returns:

A Tuple containing temporal delays and auto-correlation array.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

dispel.signal.core.derive_time_data_frame(data)

Derive a data frame based on its time-based index.

This method is preferably used for data frames for which one wants to derive for each column (instead of using data.apply(derive_time_series)).

Parameters:

data (DataFrame) – The pandas data frame for which to derive the values based on time. The data frame must have a time-based index. See index_time_diff().

Returns:

The time derivative of the values of data.

Return type:

pandas.DataFrame

dispel.signal.core.derive_time_series(data)

Derive a series based on its time-based index.

Parameters:

data (Series) – The series for which to derive the values based on time. The series must have a time-based index. See index_time_diff().

Returns:

The time derivative of the values of data.

Return type:

pandas.Series

dispel.signal.core.discretize_sampling_frequency(data, fs_expected, max_frequency_distance=5)

Discretize the sampling frequency from a time series.

First we extract the median sampling frequency of data, then return the closest expected frequency if the estimated sampling frequency is close enough (np.abs(fs_expected, fs_estimate) < 5) to one of the expected sampling frequencies.

Parameters:

• data (Series) – Any pandas series with a time series as index.

• fs_expected (List[int]) – An iterable of expected sampling frequency in Hz.

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

Returns:

Discretized sampling frequency.

Return type:

int

Raises:

ValueError – If estimated sampling frequency is too far (abs distance > max_frequency_distance) from all the expected sampling frequency in fs_expected.

dispel.signal.core.energy(power_spectrum_, lowcut=None, highcut=None)

Compute the energy of a signal.

Parameters:

• power_spectrum – A pandas series containing the power spectrum of the signal in question and the frequencies in index.

• lowcut (float | None) – The lower bound of frequencies to filter.

• highcut (float | None) – The higher bound of frequencies to filter.

• power_spectrum_ (Series) –

Returns:

The signal’s energy.

Return type:

float

dispel.signal.core.entropy(power_spectrum_)

Compute the entropy of a signal.

Parameters:

• power_spectrum – An array containing the power spectrum of the signal in question.

• power_spectrum_ (ndarray) –

Returns:

The signal’s entropy.

Return type:

float

dispel.signal.core.euclidean_distance(point1, point2)

Calculate the euclidean distance between two points.

This particular algorithm is chosen based on question 37794849 on StackOverflow.

Parameters:

• point1 (Iterable[float]) – The coordinates of point1.

• point2 (Iterable[float]) – The coordinates of point2.

Returns:

The euclidean distance between point1 and point2.

Return type:

float

dispel.signal.core.euclidean_norm(data)

Calculate the euclidean norm of a pandas Data Frame.

Parameters:

data (DataFrame) – A pandas data frame for which to compute the euclidean norm

Returns:

The euclidean norm of data

Return type:

pandas.Series

dispel.signal.core.extract_sampling_frequency(data)

Extract the median sampling frequency in Hz of a time series.

Parameters:

data (Series) – Any pandas series with a time series as index.

Returns:

The sampling frequency

Return type:

float

Raises:

ValueError – if any difference in consecutive timestamps is null.

dispel.signal.core.get_cartesian(lat, lon)

Transform latitude longitude to cartesian coordinates in meters.

Parameters:

• lat (Sequence[float]) –

• lon (Sequence[float]) –

Return type:

Tuple[ndarray, ndarray, ndarray]

dispel.signal.core.get_sampling_rate_idx(data)

Get sampling rate from time series index.

Parameters:

data (Series) – A pandas series containing the signal data for which sampling frequency is to be extracted.

Returns:

The sampling frequency.

Return type:

float

Raises:

ValueError – Raises a value error if data has not been resampled to a constant sampling rate.

dispel.signal.core.index_time_diff(data)

Get the time difference from the index in seconds.

Parameters:

data (Series | DataFrame) – The series or data frame with a time-based index

Returns:

A series containing the time difference in seconds between each row based on the index.

Return type:

pandas.Series

dispel.signal.core.integrate_time_series(data)

Compute the integral of a time series.

Parameters:

data (Series) – Input series to integrate. Must have a DatetimeIndex.

Returns:

Definite integral as approximated by trapezoidal rule.

Return type:

numpy.ndarray

Raises:

TypeError – Raises a type error if the index of the series to integrate is not a DateTimeIndex.

dispel.signal.core.non_uniform_power_spectrum(data)

Compute the power spectrum for non uniformly sampled data.

The algorithm for default frequencies and converting them to angular frequencies is taken from https://jakevdp.github.io/blog/2015/06/13/lomb-scargle-in-python/. Notably, we have decided to use gatspy rather than scipy.

Parameters:

data (Series) – An pandas series containing the signal data for which the power spectrum is to be computed, indexed by time

Returns:

One Dataframe containing the signal’s periodogram indexed by frequencies.

Return type:

pandas.Series

dispel.signal.core.peak(power_spectrum_)

Compute the peak frequency of a signal.

Parameters:

• power_spectrum – An array containing the power spectrum of the signal in question.

• power_spectrum_ (Series) –

Returns:

The signal’s peak frequency.

Return type:

float

dispel.signal.core.scale_corr(corr, n_samples, phase_shift, method)

Scale auto-correlation.

Parameters:

• corr (ndarray) – An iterable of floats containing the correlations for each delay.

• n_samples (int) – The number of samples of the input signal (denoted N in equation).

• phase_shift (ndarray) – The phase shift in number of samples (denoted m in equation).

• method (Literal['biased', 'unbiased']) – the method to be used (biased or unbiased)

Returns:

An array containing the scaled auto-correlation values.

Return type:

numpy.ndarray

dispel.signal.core.scaled_autocorr(data, method='unbiased', do_autocov=True)

Compute scaled auto-correlation function of a signal.

Parameters:

• data (ndarray[Any, dtype[float64]]) – An iterable signal of floats.

• method (Literal['unbiased']) – A string defining the scaling method to be used.

• do_autocov (bool) – A boolean denoting whether autocovariance should be used for calculation of the autocorrelation function.

Returns:

A Tuple containing lags and auto-correlation output..

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

dispel.signal.core.signal_duration(data)

Get signal duration from time-based indices.

Parameters:

data (Series | DataFrame) – The signal of which we want to compute the duration based on its index. The index has to be either a TimedeltaIndex or DatetimeIndex.

Returns:

The duration of the signal (in seconds) from the index.

Return type:

float

dispel.signal.core.sparc(movement, sample_freq=60.0, pad_level=4, cut_off_freq=10.0, amp_th=0.05)

Compute the spectral arc length of a signal.

Parameters:

• movement (ndarray) – The given 1 dimensional signal (x, y or z axis).

• sample_freq (float) – The sampling rate.

• pad_level (int) – The padding level.

• cut_off_freq (float) – The frequency cut off.

• amp_th (float) – The amplitude threshold.

Returns:

• new_sal (float) – The spectral arc length value.

• (freq, mag_spec) (tuple) – A tuple containing both frequencies and the normalized magnitude spectrum of the movement.

• (freq_sel, mag_spec_sel) (tuple) – A tuple containing both frequencies (after applying a cutoff) and the normalized magnitude spectrum (after applying a cutoff) of the movement.

Return type:

Tuple[float, tuple, tuple]

dispel.signal.core.uniform_power_spectrum(data)

Compute the power spectrum of a signal.

Parameters:

data (Series) – An pandas series containing the signal data for which the power spectrum is to be computed.

Returns:

Two arrays, one containing the signal’s frequency and the other the power spectrum.

Return type:

pandas.Series