TEAP documentation

General documentation

A simple documentation generated by Doxygen is available HERE. In case of a more extensive understanding, you can still read below.

Abstract

TEAP (www.teap.science), the Toolbox for Emotion Analysis using Physiological signals, is a Matlab (fully Octave compliant) toolbox that aims to reduce code dispersing and duplication across your research projects.

TEAP supports various signals (ECG, BVP, GSR , EEG, etc.) and its aim is to allow the user to quickly use it in order to compute signal features without any boilerplate code. TEAP is also programmed in an Object-Oriented Programming sort of way: while it doesn't use Matlab classes (in order to keep being compatible with octave), it uses encapsulating functions thus making it really easy to program signal feature code or to add another signal structure to the toolbox.

Goal of the toolbox

There are actually some toolboxes that allow signal processing (like EEGLAB, or BioSig), but these where too complex or too specialized. TEAP solves that by offering a somewhat high-level interface (see the examples below): with some lines of code it is possible to do some powerful things.


Table of Contents



Introduction TEAP utilisation Description of TEAP's functions Signals actually supported by TEAP TEAP code examples

Technical Information Conclusion

Introduction

TEAP (www.teap.science) is a toolbox. You can also view-it as a library. That is, you can easily add a specific signal into you workspace and extract it's features using TEAP.


Getting TEAP

The best way to get TEAP is via git: the URL is:

git://git.vi-di.fr/TEAP.git

so you just have to type:

git clone git://git.vi-di.fr/TEAP.git

License

TEAP is licensed under the GPLv4 Licence. For the exact license, please take a look at the LICENSE file located at the root of the TEAP folder.


Thanks to

Many thank to Mohammad Soleymani, Guillaume Chanel, and Prof. Thierry Pun from the University of Geneva/CVML, TEAP couldn't have been developed without their help !


Contributing to TEAP

If you want to contribute to TEAP, you are encouraged to send git patches (see here for more info) to TEAP@vi-di.fr ; they'll be applied upstream

You can also read the HACKING and the CONTRIB file for more info.


TEAP utilisation

In the following chapter we'll see how you can simply and efficiently use TEAP.

Loading TEAP

In order to load TEAP, you have two possibilities, but they all use the same principle:

TEAP for multiple small projects

If you want to use TEAP for multiple small projects, the best way is to extract TEAP somewhere in your directory and add-it to your matlab's (or octave's) classpath. This way, TEAP's functions will always be accessible.

TEAP for a stand-alone project

If you want to build a project that uses TEAP and that should work everywhere, the best way is to copy TEAP in your project's folder. Then, you'll simply have to call the init.m scrip to load TEAP.

In general though, a simple call to the init.m script will enable it and you will be able to start working with it.


Description of TEAP's functions

Two main categories

As you'll see, TEAP is divided into 2 main components: Signals and Bulk signals.

A Signal (signal folder) may be viewed as a channel from the acquisition card (except for things like EEG and ECG (which uses 2 differential signals), but these specific cases are embedded in within the signal).

A Bulk Signal (bulksig) can be viewed as the acquisition card: a Bulk Signal consists of multiple signals.

An important thing about TEAP is that it is stateless: that is, each function works on a variable (mainly structures, but you don't have to know that) and returns a variable. No global variables or states are used.

Function hierarchy

We can divide TEAP functions into two parts:

The functions you want to know how to use are the user functions, that is the ones that are useful to you. The toolbox functions (the ones containing 2 trailing underscores) are specific to TEAP, and you shouldn't have to use them (except if you want to add a feature to TEAP).


TEAP user functions

Signals

As we saw, User functions are the ones that you be useful to you. Here are the different possible user functions:

Bulk Signals

As you may see, there are fewer bulk signal functions than signal functions.
This is because bulk signal functions are only used to create the bulk signal.
When you want to calculate things, you do it on signals.

Here are the two main functions:


Using the TEAP functions

Here's a short example (more examples below) of how to use TEAP:

Signals

Creating/acquiring a signal

Let's say that you have a raw signal in a variable. You then want to create a signal in order to be able to extract its features. Here's what you have to do, using a BVP signal for the sake of simplicity:

MyBVPSig = BVP_aqn_variable(BVP_raw_signal, raw_sig_sampfreq);

Please note that in most cases, the acquisition function automatically filters the signal (with a mean, median or filter, depending on the type signal), so you don't have to do-it yourself.

Filtering the signal

Supposing you would want to filter the signal a bit more (but you surely don't want to, but it can happen in some cases if the signal is too noisy), you would have to do (supposing a median filter):

MyBVPSig = Signal__filter1_low_median(MyBVPSig, winSize);

As you can see, you have to get the result into the same variable you provided. In the case that you don't retrieve the result, the signal won't be modified.

Displaying the signal

If you want to display the given signal, you only have to type:

Signal_plot(MyBVPSig);

The function will automatically set the correct y's axis name to the signal's unit (Ohm for a GSR signal, °C for an HST, …).

Calculating a feature

To calculate a feature, you simply have to type the signals function, followed by _feat_ and then its feature. For example, if you want to calculate the beats per minute of a BVP signal, simply type:

BVP_feat_BPM(MyBVPSig)

if you don't know which features are supported by a signal, simply type BVP_feat_<TAB> and Matlab/Octave will show you all the possible results.

Please note that some functions are general and may be applied to all signals.
These functions start with Signal_feat_. These include Signal_feat_energy, Signal_feat_mean, …

Bulk signals

Creating a bulk signal

Let's say that you want to import an eeglab bulk signal:

load myBigMat.mat
Bulk = Bulk_load_ecglab(EEG);

and that's it.

Please note that Bulk is now an array ! If you only want to work with the first epoch, do:

epoch1_bulk_signal = Bulk(1);

Displaying the bulk signal

To display the bulk signal:

Bulk_plot(Bulk);

This will display a figure per epoch for each embedded signal. If you only want to display the first epoch only, do:

Bulk_plot(Bulk(1));

Calculating features

Bulk signals contain signals. If you want to calculate the BPM from a BVP signal, you can do-it in 2 different ways:

BVPSig = Bulk.BVP;
BVP_feat_BPM(BVPSig);

But TEAP is clever. If a bulk signal contains only one signal of the specific type , you can directly type:

BVP_feat_BPM(Bulk);

Il will extract the BVP signal itself


Signals actually supported by TEAP

Here is the list of signals that are actually supported by TEAP:

You can also read the list at src/README.md

BVP (Blood Volume Pressure)

ECG (ElectroCardioGram)

EEG (ElectroEncephaloGram)

GSR (Galvanic Skin Response)

HST (Human Skin Temperature)

RES (RESpiration)

DMY

This is a sample dummy signal, not useful to you, unless you want to contribute to TEAP a bit ;)


TEAP code examples

For some examples, you can go to src/signals/SSS/examples (SSS is the name of the signal). For example, there is an example here:

src/signals/GSR/examples/GSR_feat_peaks_example.m

Technical Information

Here is some technical information, for you geeks or hackers:


Technical Info: Signals

Description

Signals are organised in a OOP sort of way: each signal (ex. Galvanic Skin Response) has their own folder (in our case: GSR). Once in this folder, the functions are ordered by folder (eg: acquisition, examples, features, tests ). For example, if you want to capture a Galvanic Skin Response signal, you would have to call a function in the GSR/acquisition folder (for ex: GSR_aqn_file()).

OOP structure

Signals of the TEAP toolbox are in fact structures. The signal has the following attributes embedded:

You should always access to the signal's attributes via the signal's functions. These functions are fail-safed, and guarantee a semantic coherence across the variables: you can't call GSR_feat_median(Sig1) when Sig1 is of type ECG.

pre-processing structure

This structure indicates the possible pre-processing features that the signal has. Actually, only lowpass = 1 is sometimes used.

Complete example

Here is a little example of a complete signal showing features and pre-processing markers: GSRsig =

  scalar structure containing the fields:

    TEAP = S
    samprate =  512
    raw = SNIP
    unit = Ohm
    name = GSR
    isAbsolute = 0
    preprocessing =

      scalar structure containing the fields:

        lowpass =  1

Technical Info: Bulk Signals

Taking an embedded signal

You could use Bulk.SIG, but it's actually a bad practice. Use instead this simple function:

Signal = Bulk_get_signal(BulkSig, SSS_get_signame())

SSS_get_signame() gives the name of a signal (ex: GSR_get_signame() gives back 'GSR').

Getting the list of the signals of a bulk signal

Well, the function Bulk_get_signals() gives a list of all the signals inside this bulk signal (for you techies, it lists the fields, and takes back the TEAP control field.

Adding a signal to a bulk signal

If you want to add a signal to a bulk signal, you may want to do:

Bulk.SSS = SSSsig;

but that is bad :(. Use:

Bulk = Bulk_add_signal(Bulk, SSS_get_name(), SSSsig);

instead ;)


Creating your own missing signal

If you want to create a missing TEAP signal (eg: EOG), the best way would be to copy some signal's folder (eg: GSR), and start renaming the names.

Don't forget to rename these things:


Conclusion

As you may see, TEAP can be quite simple, yet powerful to use, but there are still some missing features and signals (eg: EOG, EMG). I hope that some persons will contribute to the project, and add some more features to it ;).