imutools

acc_activityindex

calc_activity_index(accx, accy, accz, signal_length, sampling_rate, metric, input_types=None, threshold=None, baseline_variance=None, triaxial=False)[source]

Calculates the given activity index for the desired input types.

Definitions of the activity indices are: Proportional Integration Method (PIM): Integration of the acceleration signal for a given epoch. Zero Crossing Method (ZCM) : Number of times the acceleration signal crosses a threshold. Time Above Threshold (TAT) : Length of timw that the acceleration signal is above a threshold. Mean Amplitude Deviation (MAD) : Mean absolute deviation of magnitude of acceleration values for a given epoch. Euclidian Norm Minus One (ENMO) : Mean positive deviation of magnitude of acceleration values from 1g. Note that, for the magnitudes lower than 1g,

the deviation is replaced with 0.

High-pass Filtered Euclidian (HFEN) : Mean magnitude of highpass filtered acceleration values. Activity Index (AI) : Sqare root of the mean deviation of the variance of acceleration signals from the systematic noise variance for three axes.

Note that, if the mean deviation is negative, it is replaced with 0.

Reference: Maczák B, Vadai G, Dér A, Szendi I, Gingl Z (2021) Detailed analysis and comparison of different activity metrics. PLOS ONE 16(12): e0261718.

https://doi.org/10.1371/journal.pone.0261718

Parameters:

  • accx (ArrayLike) – Acceleration vector for the x-axis.

  • accy (ArrayLike) – Acceleration vector for the y-axis.

  • accz (ArrayLike) – Acceleration vector for the z-axis.

  • signal_length (float) – Signal length in seconds.

  • sampling_rate (float) – Sampling rate of the acceleration signal(s).

  • input_types (list) –

    Type of dataset. Depends on the preprocessing methods applied on the raw acceleration data.

    UFXYZ : Unfiltered acceleration signals ([accx, accy, accz]). UFM : Magnitude of unfiltered acceleration signals (magnitude([accx, accy, accz])). UFM_modified = Modified magnitude of unfiltered acceleration signals (absolute(UFM - integral(gravity))). UFNM : Normalized magnitude of unfiltered acceleration signals (normalize(magnitude([accx, accy, accz]))). FXYZ : Filtered acceleration signals (filter_signal([accx, accy, accz])). FXYZ_modified = Modified filtered acceleration signals (absolute(FXYZ)). FMpre : Magnitude of filtered acceleration signals (magnitude(filter_signal([accx, accy, accz]))). SpecialXYZ : Filtered acceleration signals (special filter parameters). SpecialM : Magnitude of filtered acceleration signals (special filter parameters). FMpost : Filtered magnitude of acceleration signals (filter_signal(magnitude([accx, accy, accz]))). FMpost_modified = Modified filtered magnitude of acceleration signals (absolute(FMpost)).

  • metric (str) – The activity index to be calculated.

  • threshold (list, optional) – Threshold level in g. This parameter is required for the ‘ZCM’ and ‘TAT’ metrics. Defaults to None.

  • baseline_variance (list, optional) – Baseline variance, corresponding to the variance of acceleration signal at rest (no movement). This parameter is required for the ‘AI’ metric. Defaults to None.

  • triaxial (bool, optional) – Parameter to decide if triaxial metrics should be combined into a single metric or not. Defaults to False.

Raises:

ValueError – If the input type is not one of valid types for the desired metric.

Returns:

A dictionary of calculated metric for the desired input types.

Return type:

dict

generate_dataset(accx, accy, accz, sampling_rate, filtering=False, filtering_order=None, magnitude=False, normalize=False, modify=False, filter_type='bandpass', N=2, f_lower=0.5, f_upper=2)[source]

Generates datasets by applying appropriate preprocessing steps to the raw acceleration signals.

The datasets are:

UFXYZ : Unfiltered acceleration signals ([accx, accy, accz]). UFM : Magnitude of unfiltered acceleration signals (magnitude([accx, accy, accz])). UFM_modified = Modified magnitude of unfiltered acceleration signals (absolute(UFM - integral(gravity))). UFNM : Normalized magnitude of unfiltered acceleration signals (normalize(magnitude([accx, accy, accz]))). FXYZ : Filtered acceleration signals (filter_signal([accx, accy, accz])). FXYZ_modified = Modified filtered acceleration signals (absolute(FXYZ)). FMpre : Magnitude of filtered acceleration signals (magnitude(filter_signal([accx, accy, accz]))). SpecialXYZ : Filtered acceleration signals (special filter parameters). SpecialM : Magnitude of filtered acceleration signals (special filter parameters). FMpost : Filtered magnitude of acceleration signals (filter_signal(magnitude([accx, accy, accz]))). FMpost_modified = Modified filtered magnitude of acceleration signals (absolute(FMpost)).

Parameters:

  • accx (ArrayLike) – Acceleration vector for the x-axis.

  • accy (ArrayLike) – Acceleration vector for the y-axis.

  • accz (ArrayLike) – Acceleration vector for the z-axis.

  • sampling_rate (float) – Sampling rate of the acceleration signal(s).

  • filtering (bool, optional) – Parameter to decide if filtering should be applied or not. Defaults to False.

  • filtering_order (str, optional) – The order of filtering, should be ‘pre’, ‘post’ or ‘None’. Defaults to None.

  • magnitude (bool, optional) – Parameter to decide if magnitude of the signals should be calculated or not. Defaults to False.

  • normalize (bool, optional) – Parameter to decide if the signal should be normalized or not. Normalization refers to subtracting the gravity from the signal. Defaults to False.

  • modify (bool, optional) – Parameter to decide if a modification is required or not. For some of the activitiy indices, some extra modifications are required following standard preprocessing steps. These are represented as “_modified”. Defaults to False.

  • filter_type (str, optional) – Type of the filter. Defaults to ‘bandpass’.

  • N (int, optional) – Order of the filter. Defaults to 2.

  • f_lower (float, optional) – Lower cutoff frequency of the filter. Defaults to 0.5.

  • f_upper (float, optional) – Higher cutoff frequency of the filter. Defaults to 2.

Raises:

  • ValueError – If filtering_order is not given when filtering=True.

  • ValueError – If filtering order is invalid.

  • ValueError – If both normalize and filtering are selected as True.

Returns:

The resulting preprocessed signal(s). The dimension can be either 1 or 3 depending on the type of dataset.

Return type:

ArrayLike

acc_correlation

acc_corr_features(signals, signal_names, sampling_rate)[source]
Calculates correlation features for ACC signals.

For example: accx_accy_corr: correlation coefficient for x and y axes accx_accz_corr: correlation coefficient for x and z axes accy_accz_corr: correlation coefficient for y and z axes

Parameters:

  • signals (list) – List of input signals.

  • signal_names (list) – List of signal names. It must have the same order with signal array.

  • sampling_rate (float) – Sampling rate of the ACC signal(s) (Hz).

Returns:

Dictionary of correlation features.

Return type:

dict

acc_features

get_acc_features(signals, signal_names, sampling_rate, feature_types=['Freq', 'Stat', 'Corr'], magnitude=False)[source]

Calculates ACC features.

Parameters:

  • signals (list) – List of ACC signals for different axes.

  • signal_names (list) – List of ACC signal names for different axes. It must have the same order with the signals.

  • sampling_rate (float) – Sampling rate of the ACC signals (Hz).

  • feature_types (list, optional) – Feature types to be calculated. It can be a list of ‘Freq’, ‘Stat’ and ‘Corr’. Defaults to [‘Freq’,’Stat’,’Corr’].

  • magnitude (bool, optional) – If True, features are also calculated for magnitude signal. Defaults to False.

Raises:

  • ValueError – If sampling rate is not greater than zero.

  • ValueError – If feature type is invalid.

Returns:

Dictionary of ACC features.

Return type:

dict

get_domain_function(domain)[source]
Parameters:

domain (str) –

Return type:

Callable

acc_filter

filter_acc(sig, sampling_rate, method='lowpass')[source]

Filters ACC signal using predefined filter parameters.

Parameters:

  • sig (ArrayLike) – ACC signal.

  • sampling_rate (float) – Sampling rate of the ACC signal (Hz).

  • method (str, optional) – Filtering method. Defaults to ‘lowpass’.

Raises:

  • ValueError – If filtering method is not ‘lowpass’.

  • ValueError – If sampling rate is not greater than 0.

Returns:

Filtered ACC signal.

Return type:

ArrayLike

acc_freqdomain

acc_freq_features(signals, signal_names, sampling_rate, magnitude=False)[source]

Calculates frequency-domain features for ACC signal(s).

From:

https://towardsdatascience.com/feature-engineering-on-time-series-data-transforming-signal-data-of-a-smartphone-accelerometer-for-72cbe34b8a60

Zangróniz, R., Martínez-Rodrigo, A., Pastor, J.M., López, M.T. and Fernández-Caballero, A., 2017. Electrodermal activity sensor for classification of calm/distress condition. Sensors, 17(10), p.2324.

fft_mean: mean of fft peaks fft_std: standard deviation of fft peaks fft_mad: mean absolute deviation of fft peaks fft_min: minimum value of fft peaks fft_max: maximum value of fft peaks fft_range: difference of maximum and minimum values of fft peaks fft_median: median value of fft peaks fft_medad: median absolute deviation of fft peaks fft_iqr: interquartile range of fft peaks fft_abmean: number of fft peaks above mean fft_npeaks: number of fft peaks fft_skew: skewness of fft peaks fft_kurtosis: kurtosis of fft peaks fft_energy: energy of fft peaks fft_entropy: entropy of fft peaks f1sc: signal power in the range of 0.1 to 0.2 Hz f2sc: signal power in the range of 0.2 to 0.3 Hz f3sc: signal power in the range of 0.3 to 0.4 Hz max_freq: frequency of maximum fft peak

Parameters:

  • signals (list) – List of input signal(s).

  • signal_names (list) – List of signal name(s).

  • sampling_rate (float) – Sampling rate of the ACC signal(s).

  • magnitude (bool, optional) – If True, features are also calculated for magnitude signal. Defaults to False.

Returns:

Dictionary of frequency domain features.

Return type:

dict

acc_plot

plot_acc(signals, peaks=None, sampling_rate=None, timestamps=None, timestamp_resolution=None, method='matplotlib', show_peaks=True, figsize=(18.5, 10.5), width=1050, height=600)[source]

Generates plots for ACC signal(s).

Parameters:

  • signals (dict) – The dictionary of signals to be plotted.

  • peaks (dict, optional) – The dictionary of peaks to be plotted. Defaults to None.

  • sampling_rate (float, optional) – Sampling rate of the signal. Defaults to None.

  • timestamps (ArrayLike, optional) – Timestamp array. Defaults to None.

  • timestamp_resolution (str, optional) – Timestamp resolution. Defaults to None.

  • method (str, optional) – Package to generate plots. Defaults to ‘matplotlib’.

  • show_peaks (bool, optional) – If True, peaks are plotted. Defaults to True.

  • figsize (tuple, optional) – Figure size for matplotlib. Defaults to (18.5, 10.5).

  • width (float, optional) – Figure width for Plotly. Defaults to 1050.

  • height (float, optional) – Figure height for Plotly. Defaults to 600.

Raises:

  • ValueError – If ACC signals for all axes do not have same length.

  • ValueError – If timestamps is not None and timestamp resolution is not provided.

  • ValueError – If timestamps array and ACC signals have different lengths.

  • ValueError – If method is not ‘matplotlib’ or ‘plotly’.

acc_statistical

acc_stat_features(signals, signal_names, sampling_rate, magnitude=False)[source]

Calculates statistical features.

From https://towardsdatascience.com/feature-engineering-on-time-series-data-transforming-signal-data-of-a-smartphone-accelerometer-for-72cbe34b8a60

mean: mean of the signal amplitude std: standard deviation of the signal amplitude mad: mean absolute deviation of the signal amplitude min: minimum value of the signal amplitude max: maximum value of the signal amplitude range: difference of maximum and minimum values of the signal amplitude median: median value of the signal amplitude medad: median absolute deviation of the signal amplitude iqr: interquartile range of the signal amplitude ncount: number of negative values pcount: number of positibe values abmean: number of values above mean npeaks: number of peaks skew: Skewness of the signal kurtosis: Kurtosis of the signal energy: signal energy (the mean of sum of squares of the values in a window) momentum: Signal momentum

Parameters:

  • signals (list) – List of input signal(s).

  • signal_names (list) – List of signal name(s).

  • sampling_rate (float) – Sampling rate of the ACC signal(s) (Hz).

  • magnitude (bool, optional) – If True, features are also calculated for magnitude signal. Defaults to False.

Returns:

Dictionary of statistical features.

Return type:

dict