A simple documentation generated by Doxygen is available HERE. In case of a more extensive understanding, you can still read below.
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.
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.
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.
The best way to get TEAP is via git: the URL is:
so you just have to type:
git clone git://git.vi-di.fr/TEAP.git
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.
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 !
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
file for more info.
In the following chapter we'll see how you can simply and efficiently use TEAP.
In order to load TEAP, you have two possibilities, but they all use the same principle:
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.
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
In general though, a simple call to the
will enable it and you will be able to start working with it.
As you'll see, TEAP is divided into 2 main components:
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).
Bulk Signal (
bulksig) can be viewed as
the acquisition card: a
Bulk Signal consists of multiple
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.
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).
As we saw, User functions are the ones that you be useful to you. Here are the different possible user functions:
SSS_feat_FFF: calculates the feature FFF for a signal of type SSS. Ex:
BVP_feat_BPM(BVPSig). Please note that there also are some general functions, ex:
Signal_feat_enr(), that can be applied to all signals.
SSS_aqn_TTT: creates a TEAP SSS signal from a specific source. TTT can be
file. In this case, it creates a signal SSS from a variable. Ex:
Signal_plot: plots a signal, automatically setting x and y axis to their correct values (unit for the y axis and time for the x's)
Signal_plot_pts: plots points onto the graph. Automatically divides by the sampling rate, so you read seconds on the graph.
As you may see, there are fewer
bulk 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:
Bulk_load_PPP: loads a bulk signal from a source. Ex:
Bulk_load_eeglab()to load a bulk signal from an ecglab variable.
Bulk_plot: plots all the bulk signals (calls
Signal_ploton each of it's embeded signals).
Here's a short example (more examples below) of how to use TEAP:
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.
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.
If you want to display the given signal, you only have to type:
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, …).
To calculate a feature, you simply have to type the signals function,
_feat_ and then its feature. For example, if
you want to calculate the beats per minute of a BVP signal,
if you don't know which features are supported by a signal, simply
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
These functions start with
Signal_feat_. These include
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);
To display the bulk signal:
This will display a figure per epoch for each embedded signal. If you only want to display the first epoch only, do:
Bulk signals contain
signals. If you want
to calculate the BPM from a BVP signal, you can do-it in 2
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:
Il will extract the BVP signal itself
Here is the list of signals that are actually supported by TEAP:
You can also read the list at
This is a sample dummy signal, not useful to you, unless you want to contribute to TEAP a bit ;)
For some examples, you can go to
(SSS is the name of the signal). For example, there is an
Here is some technical information, for you geeks or hackers:
Signals are organised in a OOP sort of way: each signal (ex. Galvanic
Skin Response) has their own folder (in our case:
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
folder (for ex:
Signals of the TEAP toolbox are in fact structures. The signal has the following attributes embedded:
TEAP: the signal type. Will always be S for a signal.
samprate: the sampling rate of the signal.
raw: the raw data of the signal. It's a 1D horizontal vector.
unit: the unit of the signal (ex: Ohm).
name: the signal's name (ex: GSR)
isAbsolute: indicates if the signal was baselined/relatived.
preprocessing: a vector of pre-processing features (see below).
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
Sig1 is of type ECG.
This structure indicates the possible pre-processing features that
the signal has. Actually, only
lowpass = 1 is sometimes
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
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').
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.
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);
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:
SSS__new_empty.m: the signal's unit
SSS__get_signame.m: the signal's name. Replace-it by SSS
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 ;).