AnyWave:WriteMatlabScripted

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.

Function	Short description
AwGetInputChannels()	Get current input channels set by AnyWave for the plug-in.
AwGetData(start, duration, <filtering>, <filteringOptions>)	Get the data of the current input channels.
AwGetWorkingDir()	Get the full path to a temporary directory created by AnyWave for the plug-in.
AwGetFilePath()	Get the full path of the current open data file in AnyWave.
AwAddMarker(value, position, duration, <targeted channels>)	Add a marker in AnyWave.
AwSendMessage(message)	Send a message to AnyWave. The message will be added to the plug-in's log.

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 match 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

There are two mandatory parameters, the data position in file and the duration. Both parameters must be expressed in seconds.
Here is an example:

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.