BrainBit for developers Subscribe for updates Visit website

Emotions

Algorithm of emotional states

Description

The algorithm processes the data by a sliding window of a given length with a given frequency. If artifacts are detected on one of the bipolar channels, the artifacts on the second bipolar channel are checked, and if there are no artifacts, they are switched to that channel; in case of artifacts on both channels, the spectral values and values of mental levels are filled with previous actual values, while the counter of the number of successive artifact windows increases.

 

Install

Download from [GitHub](https://github.com/BrainbitLLC/EmotionsStateArtifacts-cpp) all folders and add .dll to your project by your preferred way.
            
The Android version is designed for APIs >= 21.

Neurosdk for android is distributed using JitPack as an aar library. Here is an example of adding SDK to an AndroidStudio project using gradle:

Add to `build.gradle` of project:

```
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
```

and to `build.gradle` of app:

```
dependencies {
    implementation 'com.github.BrainbitLLC:Emotional-state-artifacts:version'
}
```

To prevent build errors add to build.gradle this settings:

```groovy
android {
    packagingOptions {
        pickFirst 'lib/x86_64/libc++_shared.so'
        pickFirst 'lib/x86_64/libfilters.so'
        pickFirst 'lib/x86/libc++_shared.so'
        pickFirst 'lib/x86/libfilters.so'
        pickFirst 'lib/arm64-v8a/libc++_shared.so'
        pickFirst 'lib/arm64-v8a/libfilters.so'
        pickFirst 'lib/armeabi-v7a/libfilters.so'
        pickFirst 'lib/armeabi-v7a/libc++_shared.so'
    }
    ...
}
```
            
Install latest version `EmStArtifacts` package from NuGet Gallery in your preferred way.
            
coming soon...
            
> Python package available only for Windows

By pip:

```
pip install pyem-st-artifacts
```

The package has the following structure:
 - em_st_artifacts - the main package with the implementation of methods
 - sample - file `sample.py`, sample of usage library
 - libs - contain dll library files

EmotionalMath - one main module contains all methods of library

```python
from em_st_artifacts.emotional_math import EmotionalMath
```
            
coming soon...
            
> Available for iOS, Android, Windows, MacOS platforms

1. Open Package Manager
2. Click "Add" menu and choose "Add package from GIT url...". A text box and an Add button appear.
3. Enter a https://github.com/BrainbitLLC/unity_em_st_artifacts in the text box and click Add.

If Unity was able to install the package successfully, the package now appears in the package list with the  tag. If Unity was not able to install the package, the Unity Console displays an error message.
            
> Available for iOS, Android and UWP platforms

Install latest version `EmStArtifacts` package from NuGet Gallery in your preferred way to a common project.
            

 

Overview

Artifacts

When the maximum number of consecutive artifact windows is reached, `MathLibIsArtifactedSequence()` returns true, which allows you to give the user information about the need to check the position of the device. If there is no need to give notification of momentary artifacts, you can use this function as the primary for artifact notifications. Otherwise, use `MathLibIsBothSidesArtifacted()` to check for momentary artifacts, returning true for artifacts on both bipolar channels for the current window.

 

Emotional states

The estimate of emotional states (mental levels - relaxation and concentration) is available in two variants:
1. immediate assessment through alpha and beta wave intensity (and theta in the case of independent assessment).
2. relative to the baseline calibration values of alpha and beta wave intensity

In both cases, the current intensity of the waves is defined as the average for the last N windows.

The algorithm starts processing the data after the first N seconds after connecting the device and when the minimum number of points for the spectrum calculation is accumulated.
When reading spectral and mental values an array of appropriate structures (`SpectralDataPercents` and `MindData`) of length is returned, which is determined by the number of new recorded points, signal frequency and analysis frequency.

In this version the filters are built-in and clearly defined:
BandStop_45_55, BandStop_55_65, BandStop_62, HighPass_10, LowPass_30

 

Calibration

According to the results of calibration, the average base value of alpha and beta waves expression is determined in percent, which are further used to calculate the relative mental levels.

 

Library mode

The library can operate in two modes - bipolar and multichannel. In bipolar mode only two channels are processed - left and right bipolar. In multichannel mode you can process for any number of channels using the same algorithms.

 

Parameters

Main parameters description

Structure `MathLibSettings` with fields:
1. sampling_rate - raw signal sampling frequency, Hz, integer value
2. process_win_freq - frequency of spectrum analysis and emotional levels, Hz, integer value
3. fft_window - spectrum calculation window length, integer value
4. n_first_sec_skipped - skipping the first seconds after connecting to the device, integer value
5. bipolar_mode - enabled bipolar mode, boolean value
6. channels_number - count channels for multy-channel library mode, integer value
7. channel_for_analysis - in case of multichannel mode: channel by default for computing spectral values and emotional levels, integer value

`channels_number` and `channel_for_analysis` are not used explicitly for bipolar mode, you can leave the default ones.

Separate parameters:
1. MentalEstimationMode - type of evaluation of instant mental levels - disabled by default, boolean value
2. SpectNormalizationByBandsWidth - spectrum normalization by bandwidth - disabled by default, boolean value

 

Artifact detection parameters description

Structure `ArtifactDetectSetting` with fields:
1. art_bord - threshold for the long amplitude artifact, mcV, integer value
2. allowed_percent_artpoints - percent of allowed artifact points in the window, integer value
3. raw_betap_limit - boundary for spectral artifact (beta power), detection of artifacts on the spectrum occurs by checking the excess of the absolute value of the raw beta wave power, integer value
4. total_pow_border - boundary for spectral artifact (in case of assessment by total power) and for channels signal quality estimation, integer value
5. global_artwin_sec - number of seconds for an artifact sequence, the maximum number of consecutive artifact windows (on both channels) before issuing a prolonged artifact notification / device position check, integer value
6. spect_art_by_totalp - assessment of spectral artifacts by total power, boolean value
7. hanning_win_spectrum - setting the smoothing of the spectrum calculation by Hamming, boolean value
8. hamming_win_spectrum - setting the smoothing of the spectrum calculation by Henning, boolean value
9. num_wins_for_quality_avg - number of windows for estimation of signals quality, by default = 100, which, for example, with process_win_freq=25Hz, will be equal to 4 seconds, integer value

Structure `ShortArtifactDetectSetting` with fields:
1. ampl_art_detect_win_size - the length of the sliding window segments for the detection of short-term amplitude artifacts, ms, integer value
2. ampl_art_zerod_area - signal replacement area of the previous non-artefact to the left and right of the extremum point, ms, integer value
3. ampl_art_extremum_border - boundary for the extremum considered to be artifactual, mcV, integer value

Structure `MentalAndSpectralSetting` with fields:
1. n_sec_for_instant_estimation - the number of seconds to calculate the values of mental levels, integer value
2. n_sec_for_averaging - spectrum averaging, integer value

Separate setting is the number of windows after the artifact with the previous actual value - to smooth the switching process after artifacts (`SkipWinsAfterArtifact`).

 

Initialization

Main parameters

MathLibSetting mathLibSetting;
mathLibSetting.sampling_rate = 250;
mathLibSetting.process_win_freq = 25;
mathLibSetting.n_first_sec_skipped = 4;
mathLibSetting.fft_window = 1000;
mathLibSetting.bipolar_mode = true;
mathLibSetting.channels_number = 4;
mathLibSetting.channel_for_analysis = 3;

ArtifactDetectSetting artifactDetectSetting;
artifactDetectSetting.art_bord = 70;
artifactDetectSetting.allowed_percent_artpoints = 50;
artifactDetectSetting.total_pow_border = 3 * 1e7;
artifactDetectSetting.raw_betap_limit = 800000;
artifactDetectSetting.spect_art_by_totalp = false;
artifactDetectSetting.global_artwin_sec = 4;
artifactDetectSetting.num_wins_for_quality_avg = 125;
artifactDetectSetting.hanning_win_spectrum = true;
artifactDetectSetting.hamming_win_spectrum = false;

ShortArtifactDetectSetting shortArtifactDetectSetting;
shortArtifactDetectSetting.ampl_art_detect_win_size = 200;
shortArtifactDetectSetting.ampl_art_zerod_area = 200;
shortArtifactDetectSetting.ampl_art_extremum_border = 25;

MentalAndSpectralSetting mentalAndSpectralSetting;
mentalAndSpectralSetting.n_sec_for_averaging = 2;
mentalAndSpectralSetting.n_sec_for_instant_estimation = 2;

OpStatus opSt;
MathLib* tMathPtr = createMathLib(mathLibSetting, artifactDetectSetting, shortArtifactDetectSetting, mentalAndSpectralSetting, &opSt);
            
int samplingFrequency = 250;
var mls = new MathLibSetting
{
sampling_rate = samplingFrequency,
process_win_freq = 25,
n_first_sec_skipped = 6,
fft_window = samplingFrequency * 2,
bipolar_mode = true,
channels_number = 4,
channel_for_analysis = 0
};

var ads = new ArtifactDetectSetting
{
art_bord = 110,
allowed_percent_artpoints = 70,
raw_betap_limit = 800_000,
total_pow_border = 3 * 1e7;
global_artwin_sec = 4,
spect_art_by_totalp = false,
num_wins_for_quality_avg = 100,
hanning_win_spectrum = false,
hamming_win_spectrum = true
};

var sads = new ShortArtifactDetectSetting
{
ampl_art_detect_win_size = 200,
ampl_art_zerod_area = 200,
ampl_art_extremum_border = 25
};

var mss = new MentalAndSpectralSetting
{
n_sec_for_averaging = 2,
n_sec_for_instant_estimation = 2
};

var math = new EegEmotionalMath(mls, ads, sads, mss);
            
int samplingFrequency = 250;
MathLibSetting mls = new MathLibSetting(samplingFrequency, 25, samplingFrequency * 2, 4, true, 4, 3);

ArtifactDetectSetting ads = new ArtifactDetectSetting(70, 50, 800000,(int) (3*1e7), 4, false, true,false,125);

ShortArtifactDetectSetting sads = new ShortArtifactDetectSetting(200,200,25);

MentalAndSpectralSetting mss = new MentalAndSpectralSetting(2,2);

EmotionalMath tMathPtr = new EmotionalMath(mls, ads, sads, mss);
            
mls = MathLibSetting(sampling_rate=250,
process_win_freq=25,
fft_window=1000,
n_first_sec_skipped=4,
bipolar_mode=False,
channels_number=4,
channel_for_analysis=3)

ads = ArtifactDetectSetting(hanning_win_spectrum=True, num_wins_for_quality_avg=125)

sads = ShortArtifactDetectSetting(ampl_art_extremum_border=25)

mss = MentalAndSpectralSetting()

emotions = EmotionalMath(mls, ads, sads, mss)
            

            

            

            

            

 

Optional parameters 

OpStatus opSt;

// setting calibration length
int calibration_length = 8;
MathLibSetCallibrationLength(tMathPtr, calibration_length, &opSt);

// type of evaluation of instant mental levels
bool independent_mental_levels = false;
MathLibSetMentalEstimationMode(tMathPtr, independent_mental_levels, &opSt);

// number of windows after the artifact with the previous actual value
int nwins_skip_after_artifact = 10;
MathLibSetSkipWinsAfterArtifact(tMathPtr, nwins_skip_after_artifact, &opSt);

// calculation of mental levels relative to calibration values
MathLibSetZeroSpectWaves(tMathPtr, true, 0, 1, 1, 1, 0, &opSt);

// spectrum normalization by bandwidth
MathLibSetSpectNormalizationByBandsWidth(tMathPtr, true);
            
// setting calibration length
int calibrationLength = 8;
math.SetCallibrationLength(calibrationLength);

// type of evaluation of instant mental levels
bool independentMentalLevels = false;
math.SetMentalEstimationMode(independentMentalLevels);

// number of windows after the artifact with the previous actual value
int nwinsSkipAfterArtifact = 10;
math.SetSkipWinsAfterArtifact(nwinsSkipAfterArtifact);

// calculation of mental levels relative to calibration values
math.SetZeroSpectWaves(true, 0, 1, 1, 1, 0);

// spectrum normalization by bandwidth
math.SetSpectNormalizationByBandsWidth(true);
            
// setting calibration length
int calibrationLength = 8;
math.setCallibrationLength(calibrationLength);

// type of evaluation of instant mental levels
boolean independentMentalLevels = false;
math.setMentalEstimationMode(independentMentalLevels);

// number of windows after the artifact with the previous actual value
int nwinsSkipAfterArtifact = 10;
math.setSkipWinsAfterArtifact(nwinsSkipAfterArtifact);

// calculation of mental levels relative to calibration values
math.setZeroSpectWaves(true, 0, 1, 1, 1, 0);

// spectrum normalization by bandwidth
math.setSpectNormalizationByBandsWidth(true);
            
# setting calibration length
calibration_length = 8
math.set_calibration_length(calibration_length)

# type of evaluation of instant mental levels
independent_mental_levels = False
math.set_mental_estimation_mode(independent_mental_levels)

# number of windows after the artifact with the previous actual value
nwins_skip_after_artifact = 10
math.set_skip_wins_after_artifact(nwins_skip_after_artifact)

# calculation of mental levels relative to calibration values
math.set_zero_spect_waves(True, 0, 1, 1, 1, 0)

# spectrum normalization by bandwidth
math.set_spect_normalization_by_bands_width(True)
            

            

            

            

            

  

Types

RawChannels

Structure contains left and right bipolar values to bipolar library mode with fields:
1. LeftBipolar - left bipolar value, double value
2. RightBipolar - right bipolar value, double value

 

RawChannelsArray

Structure contains array of values of channels with field:
1. channels - double array

 

MindData

Mental levels. Struct with fields:
1. Rel_Attention - relative attention value
2. Rel_Relaxation - relative relaxation value
3. Inst_Attention - instantiate attention value
4. Inst_Relaxation - instantiate relaxation value

 

SpectralDataPercents

Relative spectral values. Struct with double fields:
1. Delta
2. Theta
3. Alpha
4. Beta
5. Gamma

 

SideType

Side of current artufact. Enum with values:
1. LEFT
2. RIGHT
3. NONE

 

Usage

1. If you need calibration start calibration right after library init: 

OpStatus opSt;
MathLibStartCalibration(tMathPtr, &opSt);
            
math.StartCalibration();
            
math.startCalibration();
            
math.start_calibration()
            

            

            

            

            

 

2. Adding and process data

   In bipolar mode:

RawChannels* samples = new RawChannels[SAMPLES_COUNT];
...
MathLibPushData(tMathPtr, samples, SAMPLES_COUNT);
MathLibProcessDataArr(tMathPtr);
            
var samples = new RawChannels[SAMPLES_COUNT];
math.PushData(samples);
            
RawChannels[] samples = new RawChannels[SAMPLES_COUNT];
math.pushData(samples);
math.processDataArr();
            
samples = []
math.push_data(samples)
math.process_data_arr()
            

            

            

            

            

 

   In multi-channel mode: 

RawChannelsArray* samples = new RawChannelsArray[SAMPLES_COUNT];
...
MathLibPushDataArr(tMathPtr, samples, SAMPLES_COUNT);
MathLibProcessDataArr(tMathPtr);
            
var samples = new RawChannelsArray[SAMPLES_COUNT];
math.PushDataArr(samples);
            
var samples = new RawChannelsArray[SAMPLES_COUNT];
math.pushDataArr(samples);
math.processDataArr();
            
samples = []
math.push_data_arr(samples)
math.process_data_arr()
            

            

            

            

            


3. Then check calibration status if you need to calibrate values: 

OpStatus os;
bool calibrationFinished = false;
MathLibCalibrationFinished(tMathPtr, &calibrationFinished, &os);
// and calibration progress
int calibrationProgress = 0;
MathLibGetCallibrationPercents(tMathPtr, &calibrationProgress, &os);
            
bool calibrationFinished = math.CalibrationFinished();
// and calibration progress
int calibrationProgress = math.GetCallibrationPercents();
            
boolean calibrationFinished = math.calibrationFinished();
// and calibration progress
int calibrationProgress = math.getCallibrationPercents();
            
calibration_finished = math.emotions.calibration_finished()
# and calibration progress
calibration_progress = math.get_callibration_percents()
            

            

            

            

            


4. If calibration finished (or you don't need to calibrate) read output values: 

OpStatus opSt;

int size = 0;

// Reading mental levels in percent
MathLibReadMentalDataArrSize(tMathPtr, &size, &opSt);
MindData* mental_data = new MindData[size];
MathLibReadMentalDataArr(tMathPtr, mental_data, &size, &opSt);

// Reading relative spectral values in percent:
MathLibReadSpectralDataPercentsArrSize(tMathPtr, &size, &opSt);
SpectralDataPercents* sp_data = new SpectralDataPercents[size];
MathLibReadSpectralDataPercentsArr(tMathPtr, sp_data, &size, &opSt);
            
// Reading mental levels in percent
MindData[] mentalData = math.ReadMentalDataArr();

// Reading relative spectral values in percent
SpectralDataPercents[] spData = math.ReadSpectralDataPercentsArr();
            
// Reading mental levels in percent
MindData[] mentalData = math.readMentalDataArr();

// Reading relative spectral values in percent
SpectralDataPercents[] spData = math.readSpectralDataPercentsArr();
            
# Reading mental levels in percent
mental_data = math.read_mental_data_arr()
# Reading relative spectral values in percent
sp_data = math.read_spectral_data_percents_arr()
            

            

            

            

            

 

5. Check artifacts

   5.1. During calibration

if(MathLibIsBothSidesArtifacted(tMathPtr)){
// signal corruption
}
            
if(math.IsBothSidesArtifacted()){
// signal corruption
}
            
if(math.isBothSidesArtifacted()){
// signal corruption
}
            
if math.is_both_sides_artifacted():
# signal corruption
            

            

            

            

            

 

   5.2. After (without) calibration

if(MathLibIsArtifactedSequence(tMathPtr)){
// signal corruption
}
            
if(math.IsArtifactedSequence()){
// signal corruption
}
            
if(math.isArtifactedSequence()){
// signal corruption
}
            
if math.is_artifacted_sequence():
# signal corruption
            

            

            

            

            


Finishing work with the library

freeMathLib(tMathPtr);
            
math.Dispose();
            
math = null;
// native finalizer is run
            
del math