Tremor Processor¶

class tremor_processor.TremorProcessor(sampling_frequency=100.0, cutoff_frequency=2.0, filter_order=2, window=256, lower_frequency=2.0, upper_frequency=10.0)¶

This is the main Tremor Processor class. Once the data is loaded it will be accessible at data_frame (pandas.DataFrame), where it looks like: data_frame.x, data_frame.y, data_frame.z: x, y, z components of the acceleration data_frame.index is the datetime-like index

These values are recommended by the author of the pilot study [KSR+15]

Parameters:

sampling_frequency (float) – (optional) the sampling frequency in Hz (100.0Hz)
cutoff_frequency (float) – (optional) the cutoff frequency in Hz (2.0Hz)
filter_order (int) – (optional) filter order (2)
window (int) – (optional) window (256)
lower_frequency (float) – (optional) lower frequency in Hz (2.0Hz)
upper_frequency (float) – (optional) upper frequency in Hz (10.0Hz)

Example:

>>> import pdkit
>>> tp = pdkit.TremorProcessor()
>>> ts = pdkit.TremorTimeSeries().load(path_to_data)
>>> amplitude, frequency = tp.amplitude(ts)

abs_energy(x)¶

As in tsfresh abs_energy Returns the absolute energy of the time series which is the sum over the squared values

\[E=\sum_{i=1,\ldots, n}x_i^2\]

Parameters:: x (pandas.Series) – the time series to calculate the feature of
Returns:: the value of this feature
Return type:: float

agg_linear_trend(x, param=None)¶

As in tsfresh agg_inear_trend

Calculates a linear least-squares regression for values of the time series that were aggregated over chunks versus the sequence from 0 up to the number of chunks minus one.

This feature assumes the signal to be uniformly sampled. It will not use the time stamps to fit the model.

The parameters attr controls which of the characteristics are returned. Possible extracted attributes are “pvalue”, “rvalue”, “intercept”, “slope”, “stderr”, see the documentation of linregress for more information.

The chunksize is regulated by “chunk_len”. It specifies how many time series values are in each chunk.

Further, the aggregation function is controlled by “f_agg”, which can use “max”, “min” or , “mean”, “median”

Parameters:

x (pandas.Series) – the time series to calculate the feature of
param (list) – contains dictionaries {“attr”: x, “chunk_len”: l, “f_agg”: f} with x, f a str and l an int

Returns:

the different feature values

Return type:

pandas.Series

amplitude(data_frame, method='fft')¶

This method calculates the tremor amplitude of the data frame. It accepts two different methods, ‘fft’ and ‘welch’. First the signal gets re-sampled and then high pass filtered.

Parameters:

data_frame (pandas.DataFrame) – the data frame
method (str) – fft or welch

Return ampl:

the amplitude of the Tremor

Rtype ampl:

float

Return freq:

the frequency of the Tremor

Rtype freq:

float

amplitude_by_fft(data_frame)¶

This methods extract the fft components and sum the ones from lower to upper freq as per [KSR+15]

Parameters:: data_frame (pandas.DataFrame) – the data frame
Return ampl:: the ampl
Rtype ampl:: float
Return freq:: the freq
Rtype freq:: float

amplitude_by_welch(data_frame)¶

This methods uses the Welch method [Welch67] to obtain the power spectral density, this is a robust alternative to using fft_signal & amplitude

Parameters:: data_frame (pandas.DataFrame) – the data frame
Returns:: the ampl
Rtype ampl:: float
Returns:: the freq
Rtype freq:: float

approximate_entropy(x, m=None, r=None)¶

As in tsfresh approximate_entropy

Implements a vectorized approximate entropy algorithm For short time-series this method is highly dependent on the parameters, but should be stable for N > 2000, see [YHS+13]. Other shortcomings and alternatives discussed in [RM00]

Parameters:

x (pandas.Series) – the time series to calculate the feature of
m (int) – Length of compared run of data
r (float) – Filtering level, must be positive

Returns:

Approximate entropy

Return type:

float

autocorrelation(x, lag)¶

As in tsfresh autocorrelation

Calculates the autocorrelation of the specified lag, according to the formula:

\[\frac{1}{(n-l)\sigma^{2}} \sum_{t=1}^{n-l}(X_{t}-\mu )(X_{t+l}-\mu)\]

where \(n\) is the length of the time series \(X_i\), \(\sigma^2\) its variance and \(\mu\) its mean. l denotes the lag.

Parameters:

x (pandas.Series) – the time series to calculate the feature of
lag (int) – the lag

Returns:

the value of this feature

Return type:

float

bradykinesia(data_frame, method='fft')¶

This method calculates the bradykinesia amplitude of the data frame. It accepts two different methods, ‘fft’ and ‘welch’. First the signal gets re-sampled, dc removed and then high pass filtered.

Parameters:

data_frame (pandas.DataFrame) – the data frame
method (str) – fft or welch.

Return ampl:

the amplitude of the Bradykinesia

Rtype ampl:

float

Return freq:

the frequency of the Bradykinesia

Rtype freq:

float

change_quantiles(x, ql=None, qh=None, isabs=None, f_agg=None)¶

As in tsfresh change_quantiles

First fixes a corridor given by the quantiles ql and qh of the distribution of x. Then calculates the average, absolute value of consecutive changes of the series x inside this corridor. Think about selecting a corridor on the y-Axis and only calculating the mean of the absolute change of the time series inside this corridor.

Parameters:

x (pandas.Series) – the time series to calculate the feature of
ql (float) – the lower quantile of the corridor
qh (float) – the higher quantile of the corridor
isabs (bool) – should the absolute differences be taken?
f_agg (str, name of a numpy function (e.g. mean, var, std, median)) – the aggregator function that is applied to the differences in the bin

Returns:

the value of this feature

Return type:

float

dc_remove_signal(data_frame)¶

Removes the dc component of the signal as per [KSR+15]

Parameters:: data_frame (pandas.DataFrame) – the data frame
Returns:: the data frame with dc remove signal field
Return type:: pandas.DataFrame

extract_features(data_frame, pre='')¶

This method extracts all the features available to the Tremor Processor class.

Parameters:: data_frame (pandas.DataFrame) – the data frame
Returns:: amplitude_by_fft, frequency_by_fft, amplitude_by_welch, frequency_by_fft, bradykinesia_amplitude_by_fft, bradykinesia_frequency_by_fft, bradykinesia_amplitude_by_welch, bradykinesia_frequency_by_welch, magnitude_approximate_entropy, magnitude_autocorrelation_lag_8, magnitude_autocorrelation_lag_9, magnitude_partial_autocorrelation_lag_3, magnitude_partial_autocorrelation_lag_5, magnitude_partial_autocorrelation_lag_6, magnitude_minimum, magnitude_mean, magnitude_ratio_value_number_to_time_series_length, magnitude_change_quantiles, magnitude_number_peaks, magnitude_agg_linear_trend_min_chunk_len_5_attr_intercept, magnitude_agg_linear_trend_var_chunk_len_10_attr_rvalue, magnitude_agg_linear_trend_min_chunk_len_10_attr_intercept, magnitude_spkt_welch_density_coeff_2, magnitude_spkt_welch_density_coeff_5, magnitude_spkt_welch_density_coeff_8, magnitude_percentage_of_reoccurring_datapoints_to_all_datapoints, magnitude_abs_energy, magnitude_fft_aggregated_centroid, magnitude_fft_aggregated_centroid, magnitude_fft_coefficient_abs_coeff_44, magnitude_fft_coefficient_abs_coeff_63, magnitude_fft_coefficient_abs_coeff_0, magnitude_fft_coefficient_real_coeff_0, magnitude_fft_coefficient_real_coeff_23, magnitude_sum_values
Return type:: list

fft_aggregated(x, param=None)¶

As in tsfresh fft_aggregated

Returns the spectral centroid (mean), variance, skew, and kurtosis of the absolute fourier transform spectrum.

Parameters:

x (pandas.Series) – the time series to calculate the feature of
param (list) – contains dictionaries {“aggtype”: s} where s str and in [“centroid”, “variance”, “skew”, “kurtosis”]

Returns:

the different feature values

Return type:

pandas.Series

fft_coefficient(x, param=None)¶

As in tsfresh fft_coefficient Calculates the fourier coefficients of the one-dimensional discrete Fourier Transform for real input by fast fourier transformation algorithm

\[A_k = \sum_{m=0}^{n-1} a_m \exp \left \{ -2 \pi i \frac{m k}{n} \right \}, \qquad k = 0, \ldots , n-1.\]

The resulting coefficients will be complex, this feature calculator can return the real part (attr==”real”), the imaginary part (attr==”imag), the absolute value (attr=””abs) and the angle in degrees (attr==”angle).

Parameters:

x (pandas.Series) – the time series to calculate the feature of
param (list) – contains dictionaries {“coeff”: x, “attr”: s} with x int and x >= 0, s str and in [“real”, “imag” , “abs”, “angle”]

Returns:

the different feature values

Return type:

pandas.Series

fft_signal(data_frame)¶

This method perform Fast Fourier Transform on the data frame using a hanning window

Parameters:: data_frame (pandas.DataFrame) – the data frame
Returns:: data frame with a ‘filtered_signal’, ‘transformed_signal’ and ‘dt’ columns
Return type:: pandas.DataFrame

filter_signal(data_frame, ts='mag_sum_acc')¶

This method filters a data frame signal as suggested in [KSR+15]. First step is to high pass filter the data frame using a Butterworth digital and analog filter. Then this method filters the data frame along one-dimension using a digital filter.

Parameters:

data_frame (pandas.DataFrame) – the input data frame
ts (str) – time series name of data frame to filter

Return data_frame:

adds a column named ‘filtered_signal’ to the data frame

Rtype data_frame:

pandas.DataFrame

mean(x)¶

Returns the mean of x

Parameters:: x (pandas.Series) – the time series to calculate the feature of
Returns:: the value of this feature
Return type:: float

minimum(x)¶

Calculates the lowest value of the time series x.

Parameters:: x (pandas.Series) – the time series to calculate the feature of
Returns:: the value of this feature
Return type:: float

number_peaks(x, n=None)¶

As in tsfresh number_peaks

Calculates the number of peaks of at least support n in the time series x. A peak of support n is defined as a subsequence of x where a value occurs, which is bigger than its n neighbours to the left and to the right.

Hence in the sequence

>>> x = [3, 0, 0, 4, 0, 0, 13]

4 is a peak of support 1 and 2 because in the subsequences

>>> [0, 4, 0]
>>> [0, 0, 4, 0, 0]

4 is still the highest value. Here, 4 is not a peak of support 3 because 13 is the 3th neighbour to the right of 4 and its bigger than 4.

Parameters:

x (pandas.Series) – the time series to calculate the feature of
n (int) – the support of the peak

Returns:

the value of this feature

Return type:

float

partial_autocorrelation(x, param=None)¶

As in tsfresh partial_autocorrelation

Calculates the value of the partial autocorrelation function at the given lag. The lag k partial autocorrelation of a time series \(\lbrace x_t, t = 1 \ldots T \rbrace\) equals the partial correlation of \(x_t\) and \(x_{t-k}\), adjusted for the intermediate variables \(\lbrace x_{t-1}, \ldots, x_{t-k+1} \rbrace\) ([Wil15]). Following this notes, it can be defined as

\[\alpha_k = \frac{ Cov(x_t, x_{t-k} | x_{t-1}, \ldots, x_{t-k+1})} {\sqrt{ Var(x_t | x_{t-1}, \ldots, x_{t-k+1}) Var(x_{t-k} | x_{t-1}, \ldots, x_{t-k+1} )}}\]

with (a) \(x_t = f(x_{t-1}, \ldots, x_{t-k+1})\) and (b) \(x_{t-k} = f(x_{t-1}, \ldots, x_{t-k+1})\) being AR(k-1) models that can be fitted by OLS. Be aware that in (a), the regression is done on past values to predict \(x_t\) whereas in (b), future values are used to calculate the past value \(x_{t-k}\). It is said in [Wil15] that “for an AR(p), the partial autocorrelations [ \(\alpha_k\) ] will be nonzero for k<=p and zero for k>p.” With this property, it is used to determine the lag of an AR-Process.

Parameters:

x (pandas.Series) – the time series to calculate the feature of
param (list) – contains dictionaries {“lag”: val} with int val indicating the lag to be returned

Returns:

the value of this feature

Return type:

float

percentage_of_reoccurring_datapoints_to_all_datapoints(x)¶

As in tsfresh percentage_of_reoccurring_datapoints_to_all_datapoints Returns the percentage of unique values, that are present in the time series more than once. len(different values occurring more than once) / len(different values) This means the percentage is normalized to the number of unique values, in contrast to the percentage_of_reoccurring_values_to_all_values.

Parameters:: x (pandas.Series) – the time series to calculate the feature of
Returns:: the value of this feature
Return type:: float

ratio_value_number_to_time_series_length(x)¶

As in tsfresh ratio_value_number_to_time_series_length

Returns a factor which is 1 if all values in the time series occur only once, and below one if this is not the case. In principle, it just returns: # unique values / # values

Parameters:: x (pandas.Series) – the time series to calculate the feature of
Returns:: the value of this feature
Return type:: float

resample_signal(data_frame)¶

Convenience method for frequency conversion and resampling of data frame. Object must have a DatetimeIndex. After re-sampling, this methods interpolate the time magnitude sum acceleration values and the x,y,z values of the data frame acceleration

Parameters:: data_frame (pandas.DataFrame) – the data frame to resample
Returns:: the resampled data frame
Return type:: pandas.DataFrame

spkt_welch_density(x, param=None)¶

As in tsfresh spkt_welch_density . This feature calculator estimates the cross power spectral density of the time series x at different frequencies. To do so, the time series is first shifted from the time domain to the frequency domain. The feature calculators returns the power spectrum of the different frequencies.

Parameters:

x (pandas.Series) – the time series to calculate the feature of
param (list) – contains dictionaries {“coeff”: x} with x int

Returns:

the different feature values

Return type:

pandas.Series

sum_values(x)¶: Calculates the sum over the time series values :param x: the time series to calculate the feature of :type x: pandas.Series :return: the value of this feature :rtype: bool

Tremor Time Series¶

class tremor_time_series.TremorTimeSeries¶

This is a wrapper class to load the Tremor Time Series data.

load(filename, format_file='cloudupdrs')¶

This is a general load data method where the format of data to load can be passed as a parameter,

Parameters:

filename (str) – The path to load data from
format_file (str) – format of the file. Default is CloudUPDRS. Set to mpower for mpower data.

Return dataframe:

data_frame.x, data_frame.y, data_frame.z: x, y, z components of the acceleration data_frame.index is the datetime-like index

References

[KSR+15] (1,2,3,4)

Panagiotis Kassavetis, Tabish A. Saifee, George Roussos, Loukas Drougkas, Maja Kojovic, John C. Rothwell, Mark J. Edwards, and Kailash P. Bhatia. Developing a tool for remote digital assessment of parkinson's disease. Movement Disorders Clinical Practice, 3(1):59–64, 2015.

[RM00]

Joshua S. Richman and J. Randall Moorman. Physiological time-series analysis using approximate entropy and sample entropy. American Journal of Physiology-Heart and Circulatory Physiology, 278(6):H2039–H2049, 2000.

[Wil15] (1,2)

Granville Tunnicliffe Wilson. Time series analysis: forecasting and control. Journal of Time Series Analysis, 37(5):709–711, 2015.

[YHS+13]

Jennifer M. Yentes, Nathaniel Hunt, Kendra K. Schmid, Jeffrey P. Kaipust, Denise McGrath, and Nicholas Stergiou. The appropriate use of approximate entropy and sample entropy with short data sets. Annals of Biomedical Engineering, 41(2):349–365, 2013.

[Welch67]

P. D. Welch. The use of fast fourier transform for the estimation of power spectra: a method based on time averaging over short, modified periodograms. IEEE Trans. Audio \amp Electroacoust., 15:70–73, 1967.

Tremor Processor¶

Tremor Time Series¶

PDkit

Navigation

Related Topics