Revision as of 15:42, 17 April 2014

Introduction

This section targets people who have a good knowledge and practice of Matlab language.
The purpose is to explain how to write a Matlab function that will be available to AnyWave.
The function will be executed by MATLAB after a connection to AnyWave has been established.
We will cover the AnyWave-Matlab API (Application Programming Interface) and develop examples through tutorials.

Where to start?

The first thing to do is to create the basic structure for a plug-in.
A Matlab Scripted plug-in is very simple, it is a folder containing at least two files.

Let's begin by creating a folder somewhere on the computer, called MyPlugin.
This can be done in MATLAB: create a folder and create a new function called main in that folder.
The main function is MANDATORY. It will be the main function AnyWave will call to execute our plugin.

As shown in the image above, a MyPlugin folder has been created and a main function was added.

We are now ready to write our first Matlab plug-in but before doing that we need to cover all the MATLAB functions provided by AnyWave.
Indeed, to get or put data from/to AnyWave, special functions are provided.
We can call that set of functions the AnyWave-MATLAB API.

AnyWave-Matlab functions

The table below shows a summary of all matlab functions available when writing a Matlab Scripted plug-in:
Function parameters placed between <> are optional.

AwGetInputChannels()

AnyWave uses channels to represent signals on screen but also as its internal data set.
When a plug-in is launched by AnyWave, a set of input and/or output parameters is defined accordingly to the specific settings for the plug-in.
The default behavior is to set as input channels the current selected channels in AnyWave. If there is no selection, then AnyWave will set all the channels in the current montage as input channels.

AwGetInputChannels() will request the list of input channels for the plug-in. No parameters are required.
AnyWave will send back a structure array containing Matlab structures which match the structure defined by the AwChannel() function.
AwChannel() is provided by AnyWave to easily create a Matlab structure which will be compatible with AnyWave's channels objects.

This function is usefull if you want to get input the channels' informations without requesting for data.

Let's try it in our main function for our plug-in:

function main()
%MAIN Summary of this function goes here
%   Detailed explanation goes here
 
channels = AwGetInputChannels();
disp('Input channels:');
for i=1:numel(channels)
    fprintf('name: %s', channels(i).name);
    fprintf('ref: %s', channels(i).ref);
    fprintf('sampling rate: %g Hz', channels(i).samplingRate);
end
 
end

As explained above, the channels variable is a Matlab array of structs filled by AnyWave.
The function will then enumerate the contents of the array.
The structure contains 4 fields but only three are usefull in our case:
1. name is a string and contains the name associated with the channel by AnyWave.
Note that if a reference has been set in AnyWave the name will contain the name of the reference channel (for example: A1 - A2 in a bipolar montage).

2. ref is a string and contains the reference channel set for the current channel. The string is empty if no reference is set.

3. samplingRate is a double value containing the data sampling rate in Hertz.

Note that the messages that usually go to the Matlab Command Window, like those coming from disp() or fprintf() will be available in AnyWave.
AnyWave will get the content of all text outputs from the Matlab script and put it in the process's log.

AwGetData()

As explained in AwGetInputChannels(), AnyWave will set some channels as input for the plug-in. AwGetData() will request data for these channels.

Parameters:
1. starting position (in seconds).
2. duration (in seconds) or -1 to get ALL the data in the file. (Could be memory consuming).
3. filtering keyword : optional.
No Filtering => request data with no filering: AnyWave will send data as they are in the file.
User Filtering Options => request specific filtering options for data. A fourth parameter will describe it.
4. filtering options : optional if no filtering keyword is set or if the fileting keyword is 'No Filtering'.
filtering options must be a structure that matches the one generated by the AwFilteringOptions() Matlab function:

function [ foptions ] = AwFilteringOptions()
foptions.meg_high = 0.;
foptions.meg_low = 0.;
foptions.eeg_high = 0.;
foptions.eeg_low = 0.;
foptions.emg_high = 0.;
foptions.emg_low = 0.;
end

As you can see above, the AwFilteringOptions function will create a structure with all fields set to zero, which means no filtering on data of all types of channels.
The structure can then be modified to specified custom filtering options.

Note: Only the first two parameters are mandatory. If no filtering options are specified using the filtering keyword parameter, then the data coming from AnyWave will be filtered as it is defined in AnyWave.
In other words, if you have set filtering options in AnyWave, that filtering options will be applied when requesting for data in the Matlab plug-in.

Here is an example where we will only request 20s of data without specifying any filtering options:

function main()
%MAIN Summary of this function goes here
%   Detailed explanation goes here
 
% ask for data, at position 0 and for a duration of 20 seconds.
channels = AwGetData(0, 20);
% plot only the first channel.
plot(channels(1).data);
% Wait for the user to close the figure.
uiwait();
 
end

Like in the AwGetInputChannels() example above, channels will be an array of structures containing informations about input channels.
The difference here is that the data are provided by AnyWave. The data vector for a channel is available in the field named data.

In the script above we will get 20 seconds of data from the begining of file, using the current filtering options of AnyWave.

We then plot the data contained in the first channel and wait for the user to close the figure.

Note: uiwait() is mandatory here if you want to see something on the screen when the plug-in will be executed by AnyWave.
This is due to the fact that the Matlab code will not run in the normal Matlab context, with a Command Window and a workspace.