Detailed Description

PRELIMINARY Feature Extraction for EdgeAI

WARNING These set of functions are PRELIMINARY, and subject to change in the next few months.

To use the Feature Extraction library, include this header file in the application as follows:

#include <ti/ai/edge_ai/fe/feature_extract.h>

Overview

This library will serve as a pre-processing stage where raw signal inputs will be fed to the feature extraction library and the resulting output will be fed into the pre-compiled NN model. The function that have been implemented so far are the following:

FE_applyWindow(): extracts windows of data based on a window size, stride size and an input stream.
FE_fftPool(): calculates the Real FFT magnitude for each window and average pool the resulting bins. The window undergoes a symmetrical modification first, doubling its size.
FE_kurtosis(): calculates the fisher or excess Kurtorsis for each segment of a given window, without bias (look for exact equation in the previous graph). Kurtosis describes the "peakedness" of a probability distribution.
FE_zeroCrossingRate(): calculates the zero crossing rate for each window. ZCR measures of how often a signal crosses the zero axis, indicating the frequency or noisiness of a signal.
FE_slopeChanges(): counts the sign changes of signal differences.
FE_topFrequencies(): calculates the top N dominant frequencies of a FFT result per window. The window doubles its size first, padded with zeros to the right.
FE_spectralEntropy(): calculates the Shannon spectral entropy of a FFT result per window. The window doubles its size first, padded with zeros to the right. The Spectral Entropy acts as an indicator of how spread out the power is across different frequencies.
FE_concatenateFeatures(): Concatenate many feature arrays into a big feature vector. The offsets are determined by NUM_FEAT_X and NUM_WINDOWS macros.

Usage

To use the Feature Extraction Library call the previous APIs accordingly.

#include <stddef.h>
#include <stdint.h>

Include dependency graph for feature_extract.h:

Go to the source code of this file.

Macros
#define	ADCSAMPLESIZE 125

#define	SAMPLING_FREQ 25

#define	PADDING_SIZE_LEFT 4

#define	PADDING_SIZE_RIGHT 3

#define	PADDED_INPUT_SIZE (ADCSAMPLESIZE + PADDING_SIZE_LEFT + PADDING_SIZE_RIGHT)

#define	WINDOW_SIZE 32

#define	WINDOW_STRIDE_SIZE 4

#define	NUM_WINDOWS 25

#define	FFT_SIZE 64

#define	NUM_BINS (FFT_SIZE / 2)

#define	POOLED_BINS (NUM_BINS / 2)

#define	TOP_N_FREQ 2

#define	KURTOSIS_CHUNK_SIZE 8

#define	KURTOSIS_STRIDE_SIZE 8

#define	NUM_FEAT_FFT 16

#define	NUM_FEAT_TOPFREQ TOP_N_FREQ

#define	NUM_FEAT_KURTOSIS 4

#define	NUM_FEAT_ZCR 1

#define	NUM_FEAT_SLOPE 1

#define	NUM_FEAT_PW_SPEC 1

#define	NUM_TOTAL_FEATURES 25

Enumerations
enum	fe_status_t { FE_OK = 0x00, FE_ERR_NULLPTR = 0x01, FE_ERR_BAD_PARAM = 0x02, FE_ERR_DSP = 0x03 }
	Specifies the FE status codes. More...

Functions
fe_status_t	FE_applyWindow (const uint8_t *data_stream, uint8_t output_windows[25][32])
	Builds padded/sliding windows from an input stream considering a stride size. More...

fe_status_t	FE_zeroCrossingRate (const uint8_t input_window, float zcr_out)
	Measures of how often a signal crosses the zero axis, indicating the frequency or noisiness of a signal. More...

fe_status_t	FE_slopeChanges (const uint8_t input_window, float slope_changes)
	Counts the sign changes of signal differences. More...

fe_status_t	FE_fftPool (const uint8_t input_window, float fft_output_pool_mag)
	calculate FFT magnitudes and pooling (averaging) to produce NUM_FEAT_FFT features. More...

fe_status_t	FE_topFrequencies (const uint8_t input_window, float top_freqs)
	Extract the index of the dominant frequencies (Hz) per window. More...

fe_status_t	FE_spectralEntropy (const uint8_t input_window, float entropy_out)
	Calculates the Shannon spectral entropy. The Spectral Entropy acts as an indicator of how spread out the power is. More...

fe_status_t	FE_kurtosis (const uint8_t input_window, float kurtosis_output)
	Calculates the fisher or excess kurtosis without bias for each segment of a given series. Kurtosis describes the "peakedness" of a probability distribution. More...

fe_status_t	FE_concatenateFeatures (const float fft_output_pool_mag, uint32_t window_index, const float kurtosis_output, const float zcr, const float slope_changes, const float top_dominant_freq, const float power_spectrum, float *concatenated_features)
	Concatenate many feature arrays into a big feature vector. The offsets are determined by NUM_FEAT_X and NUM_WINDOWS macros. More...

Variables
uint32_t	samplingfreq

Macro Definition Documentation

§ ADCSAMPLESIZE

#define ADCSAMPLESIZE 125

§ SAMPLING_FREQ

#define SAMPLING_FREQ 25

§ PADDING_SIZE_LEFT

#define PADDING_SIZE_LEFT 4

§ PADDING_SIZE_RIGHT

#define PADDING_SIZE_RIGHT 3

§ PADDED_INPUT_SIZE

#define PADDED_INPUT_SIZE (ADCSAMPLESIZE + PADDING_SIZE_LEFT + PADDING_SIZE_RIGHT)

§ WINDOW_SIZE

#define WINDOW_SIZE 32

§ WINDOW_STRIDE_SIZE

#define WINDOW_STRIDE_SIZE 4

§ NUM_WINDOWS

#define NUM_WINDOWS 25

§ FFT_SIZE

#define FFT_SIZE 64

§ NUM_BINS

#define NUM_BINS (FFT_SIZE / 2)

§ POOLED_BINS

#define POOLED_BINS (NUM_BINS / 2)

§ TOP_N_FREQ

#define TOP_N_FREQ 2

§ KURTOSIS_CHUNK_SIZE

#define KURTOSIS_CHUNK_SIZE 8

§ KURTOSIS_STRIDE_SIZE

#define KURTOSIS_STRIDE_SIZE 8

§ NUM_FEAT_FFT

#define NUM_FEAT_FFT 16

§ NUM_FEAT_TOPFREQ

#define NUM_FEAT_TOPFREQ TOP_N_FREQ

§ NUM_FEAT_KURTOSIS

#define NUM_FEAT_KURTOSIS 4

§ NUM_FEAT_ZCR

#define NUM_FEAT_ZCR 1

§ NUM_FEAT_SLOPE

#define NUM_FEAT_SLOPE 1

§ NUM_FEAT_PW_SPEC

#define NUM_FEAT_PW_SPEC 1

§ NUM_TOTAL_FEATURES

#define NUM_TOTAL_FEATURES 25

Enumeration Type Documentation

§ fe_status_t

enum fe_status_t

Specifies the FE status codes.

This enum defines the return states of the FE functions.

Enumerator
FE_OK	Process ended successfully. The pointer to one of the function arguments has a NULL value.
FE_ERR_NULLPTR	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_BAD_PARAM	DSP operation has failed.
FE_ERR_DSP

Function Documentation

§ FE_applyWindow()

fe_status_t FE_applyWindow	(	const uint8_t *	data_stream,
		uint8_t	output_windows[25][32]
	)

Builds padded/sliding windows from an input stream considering a stride size.

Parameters

[in]	data_stream	pointer to input data stream [ADCSAMPLESIZE] for time series.
[out]	output_windows	preallocated 2D-array [NUM_WINDOWS][WINDOW_SIZE].

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_zeroCrossingRate()

fe_status_t FE_zeroCrossingRate	(	const uint8_t *	input_window,
		float *	zcr_out
	)

Measures of how often a signal crosses the zero axis, indicating the frequency or noisiness of a signal.

Parameters

[in]	input_window	input window uint8.
[out]	zcr_out	pointer to result float32.

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_slopeChanges()

fe_status_t FE_slopeChanges	(	const uint8_t *	input_window,
		float *	slope_changes
	)

Counts the sign changes of signal differences.

Parameters

[in]	input_window	input window uint8.
[out]	slope_changes	pointer to result float32.

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_fftPool()

fe_status_t FE_fftPool	(	const uint8_t *	input_window,
		float *	fft_output_pool_mag
	)

calculate FFT magnitudes and pooling (averaging) to produce NUM_FEAT_FFT features.

Parameters

[in]	input_window	input window uint8.
[out]	fft_output_pool_mag	preallocated array of NUM_FEAT_FFT float32.

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_topFrequencies()

fe_status_t FE_topFrequencies	(	const uint8_t *	input_window,
		float *	top_freqs
	)

Extract the index of the dominant frequencies (Hz) per window.

Parameters

[in]	input_window	input window uint8.
[out]	top_freqs	preallocated array of length TOP_N_FREQ.

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_spectralEntropy()

fe_status_t FE_spectralEntropy	(	const uint8_t *	input_window,
		float *	entropy_out
	)

Calculates the Shannon spectral entropy. The Spectral Entropy acts as an indicator of how spread out the power is.

Parameters

[in]	input_window	input window uint8.
[out]	entropy_out	pointer to float32 result.

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_kurtosis()

fe_status_t FE_kurtosis	(	const uint8_t *	input_window,
		float *	kurtosis_output
	)

Calculates the fisher or excess kurtosis without bias for each segment of a given series. Kurtosis describes the "peakedness" of a probability distribution.

Parameters

[in]	input_window	input window uint8.
[out]	kurtosis_output	preallocated array of NUM_FEAT_KURTOSIS float32.

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

§ FE_concatenateFeatures()

fe_status_t FE_concatenateFeatures	(	const float *	fft_output_pool_mag,
		uint32_t	window_index,
		const float *	kurtosis_output,
		const float *	zcr,
		const float *	slope_changes,
		const float *	top_dominant_freq,
		const float *	power_spectrum,
		float *	concatenated_features
	)

Concatenate many feature arrays into a big feature vector. The offsets are determined by NUM_FEAT_X and NUM_WINDOWS macros.

Parameters

[in]	fft_output_pool_mag	pointer to FFT features (NUM_FEAT_FFT)
[in]	window_index	which window this belongs to (0 .. NUM_WINDOWS-1)
[in]	kurtosis_output	pointer to NUM_FEAT_KURTOSIS values
[in]	zcr	pointer to zcr value (scalar)
[in]	slope_changes	pointer to slope_changes value (scalar)
[in]	top_dominant_freq	pointer to TOP_N_FREQ values
[in]	power_spectrum	pointer to spectral entropy (scalar)
[out]	concatenated_features	preallocated feature vector of size NUM_TOTAL_FEATURES * NUM_WINDOWS

Return values

FE_OK	Process ended successfully.
FE_ERR_NULLPTR	The pointer to one of the function arguments has a NULL value.
FE_ERR_BAD_PARAM	One of the Feature Extraction configuration parameters is incorrect or not supported.
FE_ERR_DSP	DSP operation has failed.

Variable Documentation

§ samplingfreq

uint32_t samplingfreq

Detailed Description

Overview

Usage

Macros

Enumerations

Functions

Variables

Macro Definition Documentation

§ ADCSAMPLESIZE

§ SAMPLING_FREQ

§ PADDING_SIZE_LEFT

§ PADDING_SIZE_RIGHT

§ PADDED_INPUT_SIZE

§ WINDOW_SIZE

§ WINDOW_STRIDE_SIZE

§ NUM_WINDOWS

§ FFT_SIZE

§ NUM_BINS

§ POOLED_BINS

§ TOP_N_FREQ

§ KURTOSIS_CHUNK_SIZE

§ KURTOSIS_STRIDE_SIZE

§ NUM_FEAT_FFT

§ NUM_FEAT_TOPFREQ

§ NUM_FEAT_KURTOSIS

§ NUM_FEAT_ZCR

§ NUM_FEAT_SLOPE

§ NUM_FEAT_PW_SPEC

§ NUM_TOTAL_FEATURES

Enumeration Type Documentation

§ fe_status_t

Function Documentation

§ FE_applyWindow()

§ FE_zeroCrossingRate()

§ FE_slopeChanges()

§ FE_fftPool()

§ FE_topFrequencies()

§ FE_spectralEntropy()

§ FE_kurtosis()

§ FE_concatenateFeatures()

Variable Documentation

§ samplingfreq