Revision as of 10:50, 19 August 2014

Introduction

This section targets people who have a good knowledge and practice of the MATLAB programming language.
The purpose is to explain how to write a MATLAB function that will be the heart of a plug-in executed in MATLAB by AnyWave.
We will also explain how to create a text file to describe our plug-in to AnyWave

The AnyWave-MATLAB API (Application Programming Interface) which is a set of MATLAB functions, will be described in details, with examples to illustrate their use.

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 (called MyPlugin) somewhere on the computer.
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!!

Refer to the AnyWave-MATLAB functions section to learn how to program a plug-in that will communicate with AnyWave.

Writing the desc.txt file

We have written the MATLAB code and now all we have to do is to create a descriptive text file to inform AnyWave about our plug-in.
Let's dot it in Maltab:

The file must be named desc.txt and may looks like:

name = My Matlab Plugin
description = I am a plug-in written in Matlab
category = Process:MATLAB:My MATLAB Plugin

The category line is optional. It tells AnyWave where the plug-in will appear in the menus. Here we decided to caterogize it as a Process, with a sub category called MATLAB. Finally, the plug-in name will be My MATLAB Plugin.

The category feature is usefull to separate plug-in that won't really do some calculation but convert data to another format or launch external tools. It could also be useful to classify signal processing algorithms.

Three category keywords are recognized:

• Process : The plug-in will be set in the Processes menu with a subcategory and a name, for example 'Process:Correlation:Compute correlation'
• File: The plug-in will be set in the File Menu under the Export sub-menu. Example : 'File:Export to MATLAB'
• View: The plug-in will be set in the View Menu. Example : 'View:Launch 3D viewer'

If no category is specified, AnyWave will set the plug-in in the Processes menu using the name defined in the file.

Copy the plug-in to the right location

We are ready to add the plug-in to AnyWave.

Copy the folder MyPlugin to your user's AnyWave plugins directory. Remember to place it in the Matlab subfolder. For example on Windows:

As you can see MyPlugin in located in the user's AnyWave path for Matlab Scripted plug-ins.

Use the plug-in in AnyWave

Launch AnyWave, the plug-in should be shown as available.

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.
Note: All AnyWave MATLAB functions begin with Aw. That will avoid confusion and clearly indicates the purpose of these functions.

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.

AwGetDataInfo()

% get info about data file
infos = AwGetDataInfo();
 
% current path to data file
fprintf('data path: %s', infos.data_path);
 
% total file duration in seconds
fprintf('data duration : %g', infos.total_duration);

AwGetData(start, duration, <filtering keyword>, <filtering options>)

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

Parameters

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 specify custom filtering options.

Note: 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.

Examples

Requesting data with AnyWave's current 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 context (with a Command Window and a workspace) but is executed and terminated.

Requesting data using filtering options

function main()
   % create the filteriong options struct
   foptions = AwFilteringOptions();
   % set specific filtering options
   % eeg channels only will be filtered.
   foptions.eeg_high = 45;  % High pass filter 45Hz
   foptions.eeg_low = 5;    % Low pass filter 5Hz
   % get data
   channels = AwGetData(0, 20, 'User Filtering Options', foptions);
   % plot only the first channel.
   plot(channels(1).data);
   % Wait for the user to close the figure.
   uiwait();
end

The example above shows how to ask AnyWave to filter data. Note that only the EEG channels will be filtered. That implies that some EEG channels are set as input for the plug-in.

Requesting data with no filtering

function main()
   channels = AwGetData(0, 20, 'No Filtering');
   % plot only the first channel.
   plot(channels(1).data);
   % Wait for the user to close the figure.
   uiwait();
end

Remember: No Filtering means that AnyWave will send data as they are stored in the file.

AwGetWorkingDir()

The function returns a string which is the full path to a temporary folder created by AnyWave for the plug-in.

This is particularly usefull to store temporary files or settings.

Example:

function main()
   % get input channels
   channels = AwGetInputChannels();
   % save channels to a temporary file
   save(strcat(AwGetWorkingDir(), '/channels'), 'channels');
end

AwAddMarker(label, position, <value>, <duration>, <targeted channels>)

AnyWave is able to receive markers as output parameter of a plug-in. This function will add a marker to the list of output parameters that will be handle by AnyWave when the plug-in has terminated.
A marker must have a name or label and a position in the file.
A marker could also have an integer value, a duration in seconds (a selection of samples) and can target one or several particular channels.

Parameters

Only the first two parameters are mandatory. However, if the marker must target some channels, then you will have to specify parameter 3 and 4 as well.

Let see an example of adding markers:

function main()
   % .. 
   % Add a simple marker:
   AwAddMarker('My Marker', 2.0);   % this will add a marker named My Marker at position 2s in AnyWave.
   % Add a marker with a duration:
   AwAddMarker('My selection', 3.0, -1, 5); % this will add a marker named My selection at position 3s, with a value of -1 and a duration of 5s
   % Add a marker with a value:
   AwAddMarker('My Marker 2', 1, 12); % this will add a marker named My Marker 2, at position 1s with a value of 12
   % Add a marker which targets a particular channel
   AwAddMarker('My Marker 3', 4, -1, 0, {'A12'});
  % add a marker named My Marker 3, at position 4s, with no value (-1), no duration (0) but which targets channel A12
end

Note: Markers can have similar labels and can overlap.

AwGetMarkers(<keyword>, <keyword parameter>)

This function will return Markers currently present in AnyWave. If no parameters are specified, the function returns all the markers handle by AnyWave.

The Markers are returned as an array of structures. Let see the format of a marker structure:

marker.label = 'Marker Label';
marker.start = 0.; % position in seconds from the beginning of the file.
marker.duration = 0.; % duration in seconds. If 0. then the marker is a single marker which marks an event in time.
marker.value = -1; % Associated value. 
% The value is an integer (INT16). -1 indicates that no value is currently associated with the marker.
marker.channels = {'A1', 'A2'}; % a Cell array of strings indicating the channels that are targeted by the marker.
% Can be empty if the marker is global to all channels.

Optional parameters

It is possible to only ask for a subset of the markers currently active in AnyWave. The keyword parameter permits to ask for markers references by their values or by theirs labels.

keyword = 'By Value' This indicates that we want markers which have a specified value. The second parameter must then be the value.
Example:

markers = AwGetMarkers('By Value', 10);
 
% markers will contain structures corresponding to markers with a value 10
% ATTENTION : markers can be an empty array if no markers matches the request.

keyword = 'By Label' This indicates that we want markers which have a specified label. The second parameter must then be the label.
Example:

markers = AwGetMarkers('By Label', 'Stimulus 1');
 
% markers will contain structures corresponding to markers with a label set to Stimulus 1
% ATTENTION : markers can be an empty array if no markers matches the request.

AwSendMessage(message)

This function sends a text message to AnyWave. The message will appear in the Processes console in AnyWave and also in the plugin's log.

Example:

channels = AwGetData(0, -1); % get all data
 
for (i=1:numel(channels)
   AwSendMessage(sprintf('Processing channel %d', i));
   % do something
end

AwIsProcessTerminated

This function will return true or false depending on the action of the user about the currently running plug-in.

This function is usefull when processing heavy and long calculations. If the user want to cancel the current processing, it may be suitable to cancel the current calculation running in MATLAB as well.

Example:

channels = AwGetData(0, -1); % get all data
 
% 
for (i=1:numel(channels)
    if (~AwProcessIsTerminated())
         % do some heavy calculation on a data contained in channel
   end
end