Difference between revisions of "AnyWave:WriteMatlabScripted"

From WikiMEG
Jump to: navigation, search
(→‎AnyWave-MATLAB functions)
(→‎main.m)
 
(39 intermediate revisions by one user not shown)
Line 3: Line 3:
 
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.<br/>
 
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.<br/>
 
We will also explain how to create a text file to describe our plug-in to AnyWave<br/>
 
We will also explain how to create a text file to describe our plug-in to AnyWave<br/>
 +
The AnyWave-MATLAB API consists in a set of MATLAB functions. They will be described in details in a dedicated section.<br/>
  
−
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.
+
=Setup the plugin folder=
−
 
+
−
=Requirements=
+
−
MATLAB software must be installed on the computer.
+
−
AnyWave should be able to detect the installation by itself.
+
−
However, in some special cases, MATLAB could be installed on a custom path AnyWave may not check.
+
−
In that case, the user must specify the path to MATLAB in AnyWave by changing options in the Preferences settings.
+
−
 
+
−
NB: on Linux, csh must be installed at /bin/csh, or the MATLAB Engine API used by AnyWave will not function, and AnyWave will report "Failed to connect to MATLAB!" in the corresponding Process log.
+
−
 
+
−
=Where to start?=
+
 
The first thing to do is to create the basic structure for a plug-in.<br/>
 
The first thing to do is to create the basic structure for a plug-in.<br/>
−
A MATLAB Scripted plug-in is very simple: it is a folder containing at least two files.
+
A MATLAB Scripted plug-in is very simple: it is a folder containing at least two files.<br/>
  
 
Let's begin by creating a folder (called MyPlugin) somewhere on the computer.<br/>
 
Let's begin by creating a folder (called MyPlugin) somewhere on the computer.<br/>
Line 39: Line 30:
 
category = Process:MATLAB:My MATLAB Plugin
 
category = Process:MATLAB:My MATLAB Plugin
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
The syntax is to set keywords and values.<br /><br />
  
−
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.
+
Here we have three keywords (name, description, category).<br />
−
 
+
Two keywords are mandatory : name and description. Other keywords are optional.<br />
−
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.
+
==desc.txt keywords==
−
It could also be useful to classify signal processing algorithms.
+
Some keywords may have several values. Separate the values by the colon character ''':''' <br/>
−
 
+
The table below shows all the keywords handled by AnyWave and their functions.<br/>
−
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:
+
−
[[File:Matlab3.png|center]]
+
−
 
+
−
As you can see MyPlugin is 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.
+
−
[[File:Matlab4.png|center]]
+
−
 
+
−
=AnyWave-MATLAB functions=
+
−
The table below shows a summary of all MATLAB functions available when writing a MATLAB Scripted plug-in:<br/>
+
−
 
+
−
'''Note:''' All AnyWave MATLAB functions start with 'aw_' to avoid confusions with other MATLAB functions.
+
−
 
+
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Function !! Short description
+
! keyword !! description !! type
 
|-
 
|-
−
| '''[[#aw_getplugininfo()|aw_getplugininfo]]''' || Returns useful information about the plugin.
+
| name || the name of your plugin. Must be unique.|| MANDATORY
 
|-
 
|-
−
| '''[[#aw_getdata()|aw_getdata]]''' || Returns data from AnyWave.
+
| description || short description || MANDATORY
 
|-
 
|-
−
| '''[[#aw_getmarkers()|aw_getmarkers]]''' || Returns markers from AnyWave.
+
| category || Where to link the plugin in AnyWave menus || OPTIONAL
 
|-
 
|-
−
| '''[[#aw_addmarkers()|aw_addmarkers]]''' || Sends markers to AnyWave.
+
| input_flags || what is required for input || OPTIONAL
 +
|-
 +
| flags || The plugin special flags || OPTIONAL
 
|}
 
|}
  
−
==aw_getplugininfo==
+
===category===
−
<syntaxhighlight lang="matlab">
+
'''category:''' It tells AnyWave where the plug-in will appear in the menus. Here, we decided to make it appear under the Python sub-menu in the Processes main menu.<br />
−
function [ infos ] = aw_getplugininfo()
+
The category feature is usefull to separate plug-ins by theme.<br/>
−
%aw_getplugininfo returns information about the input set for the plugin.
+
Three category keywords are recognized:<br/>
−
%  infos = aw_getplugininfo();
+
* 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 file.'
−
%  returns a structure with the following fields:
+
* View: The plug-in will be set in the View Menu. Example : 'View:Launch 3D viewer'
−
%  .labels
+
If no category is specified, AnyWave will set the plug-in in the Processes menu using the name defined in the file.<br/>
−
%      labels of channels set as input for the plugin.
+
<br/>
−
%  .refs
+
−
%      references of channels: Empty strings for monopolar channels.
+
−
%  .max_sr
+
−
%      maximum sampling rate in Hz.
+
−
%  .total_duration
+
−
%      the total duration in seconds of the data.
+
−
%  .temp_dir
+
−
%      the path to a temporary directory created by AnyWave for the
+
−
%      plugin.
+
−
%
+
−
end
+
−
</syntaxhighlight>
+
−
 
+
−
==aw_getdata==
+
−
<syntaxhighlight lang="matlab">
+
−
function [ channels ] = aw_getdata(cfg )
+
−
%aw_getdata request data from AnyWave
+
−
%  channels = aw_getdata(cfg)
+
−
%  returns channels' data according to the settings defined in cfg structure.
+
−
%
+
−
%  cfg may contain the following fields:  
+
−
% 
+
−
%  cfg.start = 10.;
+
−
%      starting position in seconds of requested data.
+
−
%      if this field is not specified, AnyWave will return data starting
+
−
%      at position 0s.
+
−
%  cfg.duration = 20.;
+
−
%      duration of requested data in seconds.
+
−
%      if this field is not specified, AnyWave will return ALL the
+
−
%      available data.
+
−
%  cfg.labels = {'A1', 'A2'};
+
−
%      cell array of strings to identify the required channel labels.
+
−
%      if no labels are specified, AnyWave will return the current selected
+
−
%      channels set as input for the plugin.
+
−
%
+
−
%  cfg.filtering = 'no';
+
−
%      specifies that we don't want AnyWave to filter the data.
+
−
%  cfg.filtering = 'yes';
+
−
%      specifies that we want data to be filtered.
+
−
%  Note:
+
−
%      if the filtering field is not specified, the data will be filtered by
+
−
%      AnyWave using the current user defined settings.
+
−
%
+
−
%  cfg.eeg_lp = 10.;  requires filtering = 'yes'.
+
−
%      specifies that we want EEG data with low pass filter of 10Hz.
+
−
%  cfg.eeg_hp = 1.;  requires filtering = 'yes'.
+
−
%      specifies that we want EEG data with high pass filter of 1Hz.
+
−
%  cfg.meg_lp = 10.;  requires filtering = 'yes'.
+
−
%      specifies that we want MEG data with low pass filter of 10Hz.
+
−
%  cfg.meg_hp = 1.;  requires filtering = 'yes'.
+
−
%      specifies that we want MEG data with high pass filter of 1Hz.
+
−
%
+
−
%  cfg.decimate = 8;
+
−
%      specifies that we only take 1 sample of data every 8 samples.
+
−
%
+
−
%Output:
+
−
%  channels is an array of strucrures with the following fields:
+
−
%  .label;
+
−
%      a string representing the channel's label.
+
−
%  .ref;
+
−
%      a string representing the reference channel. Can be empty.
+
−
%  .data;
+
−
%      a data vector containing the samples.
+
−
%  .sr;
+
−
%      the sampling rate of data.
+
−
%  .hpf; 
+
−
%      the High Pass filter set.
+
−
%  .lpf;
+
−
%      the Low Pass filter set.
+
−
end
+
−
</syntaxhighlight>
+
−
 
+
−
'''Example:'''<br />
+
−
<syntaxhighlight lang="matlab">
+
−
function main
+
−
 
+
−
% request 10 seconds of data starting at 2.5s
+
−
cfg = [];
+
−
cfg.start = 2.5;
+
−
cfg.duration = 10;
+
−
channels = aw_getdata(cfg);
+
−
 
+
−
% request raw data (with no filtering)
+
−
cfg = [];
+
−
cfg.start = 2.5;
+
−
cfg.duration = 10;
+
−
cfg.filtering = 'no';
+
−
channels = aw_getdata(cfg);
+
−
 
+
−
% request data with low pass filter of 25Hz on EEG channels
+
−
cfg = [];
+
−
cfg.start = 2.5;
+
−
cfg.duration = 10;
+
−
cfg.filtering = 'yes';
+
−
cfg.eeg_lp = 25;
+
−
channels = aw_getdata(cfg);
+
−
 
+
−
end
+
−
</syntaxhighlight>
+
−
 
+
  
−
==AwAddMarker(label, position, <value>, <duration>, <targeted channels>)==
+
===input_flags===
−
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.<br/>
+
'''input_flags:''' a list a ":" separated strings that set the input flags for the plugin.<br/>
−
A marker must have a name or label and a position in the file.<br/>
+
−
A marker could also have an integer value, a duration in seconds (a selection of samples) and can target one or several particular channels.<br/>
+
  
−
===Parameters===
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Parameter!! Description
+
! input_flag !! description
 
|-
 
|-
−
| 1. label || A string to set the marker's label.
+
| GetAllMarkers || AnyWave will copy all the markers and set them as input for the plugin. This will impact aw_getmarkers() function.
 
|-
 
|-
−
| 2. position || Real scalar value to set the psition in seconds of the marker in the file.
+
| GetDurationMarkers || AnyWave will copy markers with a duration and set them as input. This will impact aw_getmarkers() function
 
|-
 
|-
−
| 3. value : optional  || Integer value (INT16 if possible) associated to the marker.  
+
| ProcessIgnoresChannelSelection || The plugin will be run without using the selected channels as input by default.
 
|-
 
|-
−
| 4. duration : optional || Real scalar value to set the duration of the marker. Could be zero.
+
| ProcessRequiresChannelSelection || The plugin will only run if the user has selected channels.
 
|-
 
|-
−
| 5. target channels : optional || A cell array of strings. This parameter is optional.
+
| GetAsRecordedChannels || AnyWave will copy all the as recorded channels found in the current file as input for the plugin. This will impact aw_getdata() function.
 +
|-
 +
| GetCurrentMontage || AnyWave will copy the current montaged channels and set them as input for the plugin. This will impact aw_getdata() function.
 
|}
 
|}
−
 
+
Example of desct.txt with input_flags:<br/>
−
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.
+
<syntaxhighlight lang="text">
−
 
+
name = MyPlugin
−
Let see an example of adding markers:
+
description = do something in MATLAB
−
<syntaxhighlight lang="matlab">
+
category = Process:Test:MyPlugin
−
function main()
+
input_flags = ProcessIgnoresChannelSelection:GetAllMarkers
−
  % ..
+
−
  % 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
+
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
===flags===
 +
flags are used to configure the plugin capabilities.<br/>
 +
{| class="wikitable"
 +
|-
 +
! flag !! description
 +
|-
 +
| NoDataRequired or ProcessDoesntRequireData || indicates the plugin doesn't need a file to be open in AnyWave to run.
 +
|-
 +
| CanRunFromCommandLine || indicates that the plugin can also run in batch mode and using the command line.
 +
|}
  
−
'''Note:''' Markers can have similar labels and can overlap.
+
=main.m=
−
 
+
This is the entry point function called by AnyWave.<br/>
−
==AwGetMarkers(<keyword>, <keyword parameter>)==
+
Depending on the type of plugin you are writing, you may have to setup some variables in this file as an initialisation:<br>
−
This function will return Markers currently present in AnyWave. If no parameters are specified, the function returns all the markers handle by AnyWave.
+
Indeed, you may decide to compile your plugin to distribute it as a standalone software. In this case, use the following code in your main.m:<br/>
−
 
+
−
The Markers are returned as an array of structures. Let see the format of a marker structure:
+
 
<syntaxhighlight lang="matlab">
 
<syntaxhighlight lang="matlab">
−
marker.label = 'Marker Label';
+
function main(varargin)
−
marker.start = 0.; % position in seconds from the beginning of the file.
+
global args;
−
marker.duration = 0.; % duration in seconds. If 0. then the marker is a single marker which marks an event in time.
+
if isdeployed
−
marker.value = -1; % Associated value.
+
% STANDALONE AnyWave Plugin code
−
% The value is an integer (INT16). -1 indicates that no value is currently associated with the marker.
+
  global host;
−
marker.channels = {'A1', 'A2'}; % a Cell array of strings indicating the channels that are targeted by the marker.
+
  global port;
−
% Can be empty if the marker is global to all channels.
+
  global pid;
−
</syntaxhighlight>
+
  
−
===Optional parameters===
+
  if (nargin < 3)
−
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.
+
      error('missing arguments.');
−
 
+
  end
−
 
+
  host = varargin{1};
−
'''keyword''' = 'By Value'<br />
+
  port = str2num(varargin{2});
−
This indicates that we want markers which have a specified value. The second parameter must be the value.<br/>
+
  pid = str2num(varargin{3});
−
Example:
+
  if (nargin > 3)
−
<syntaxhighlight lang="matlab">
+
    args = varargin{4};
−
 
+
  end
−
markers = AwGetMarkers('By Value', 10);
+
 
−
 
+
  assignin('base', 'host',  host);
−
% markers will contain structures corresponding to markers with a value 10
+
  assignin('base', 'port', port);
−
% ATTENTION : markers can be an empty array if no markers matches the request.
+
  assignin('base', 'pid', pid);
−
 
+
  assignin('base', 'args', args);
−
</syntaxhighlight>
+
% end of STANDALONE AnyWave Plugin code
−
 
+
−
'''keyword''' = 'By Label'<br />
+
−
This indicates that we want markers which have a specified label. The second parameter must be the label.<br/>
+
−
Example:
+
−
<syntaxhighlight lang="matlab">
+
−
 
+
−
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.
+
−
 
+
−
</syntaxhighlight>
+
−
 
+
−
==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:
+
−
<syntaxhighlight lang="matlab">
+
−
 
+
−
channels = AwGetData(0, -1); % get all data
+
−
 
+
−
for (i=1:numel(channels)
+
−
  AwSendMessage(sprintf('Processing channel %d', i));
+
−
  % do something
+
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==AwIsProcessTerminated==
+
=Copy the plug-in to the right location=
−
This function will return true or false depending on the action of the user about the currently running plug-in.
+
We are ready to add the plug-in to AnyWave.
  
−
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.
+
Copy the folder MyPlugin to your user's AnyWave plugins directory. Remember to place it in the Matlab subfolder.
 +
For example on Windows:
 +
[[File:Matlab3.png|center]]
  
−
Example:
+
As you can see MyPlugin is located in the user's AnyWave path for Matlab Scripted plug-ins.
−
<syntaxhighlight lang="matlab">
+
  
−
channels = AwGetData(0, -1); % get all data
+
=Use the plug-in in AnyWave=
−
 
+
Launch AnyWave: the plug-in should be shown as available.
−
%
+
[[File:Matlab4.png|center]]
−
for (i=1:numel(channels)
+
−
    if (~AwProcessIsTerminated())
+
−
        % do some heavy calculation on a data contained in channel
+
−
  end
+
−
end
+
−
 
+
−
</syntaxhighlight>
+

Latest revision as of 14:17, 30 March 2020

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 consists in a set of MATLAB functions. They will be described in details in a dedicated section.

Setup the plugin folder

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.

Matlab1.png

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:

Matlab2.png

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 syntax is to set keywords and values.

Here we have three keywords (name, description, category).
Two keywords are mandatory : name and description. Other keywords are optional.

desc.txt keywords

Some keywords may have several values. Separate the values by the colon character :
The table below shows all the keywords handled by AnyWave and their functions.

keyword description type
name the name of your plugin. Must be unique. MANDATORY
description short description MANDATORY
category Where to link the plugin in AnyWave menus OPTIONAL
input_flags what is required for input OPTIONAL
flags The plugin special flags OPTIONAL

category

category: It tells AnyWave where the plug-in will appear in the menus. Here, we decided to make it appear under the Python sub-menu in the Processes main menu.
The category feature is usefull to separate plug-ins by theme.
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 file.'
  • 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.

input_flags

input_flags: a list a ":" separated strings that set the input flags for the plugin.

input_flag description
GetAllMarkers AnyWave will copy all the markers and set them as input for the plugin. This will impact aw_getmarkers() function.
GetDurationMarkers AnyWave will copy markers with a duration and set them as input. This will impact aw_getmarkers() function
ProcessIgnoresChannelSelection The plugin will be run without using the selected channels as input by default.
ProcessRequiresChannelSelection The plugin will only run if the user has selected channels.
GetAsRecordedChannels AnyWave will copy all the as recorded channels found in the current file as input for the plugin. This will impact aw_getdata() function.
GetCurrentMontage AnyWave will copy the current montaged channels and set them as input for the plugin. This will impact aw_getdata() function.

Example of desct.txt with input_flags:

name = MyPlugin
description = do something in MATLAB
category = Process:Test:MyPlugin
input_flags = ProcessIgnoresChannelSelection:GetAllMarkers

flags

flags are used to configure the plugin capabilities.

flag description
NoDataRequired or ProcessDoesntRequireData indicates the plugin doesn't need a file to be open in AnyWave to run.
CanRunFromCommandLine indicates that the plugin can also run in batch mode and using the command line.

main.m

This is the entry point function called by AnyWave.
Depending on the type of plugin you are writing, you may have to setup some variables in this file as an initialisation:
Indeed, you may decide to compile your plugin to distribute it as a standalone software. In this case, use the following code in your main.m:

function main(varargin)
global args;
if isdeployed
% STANDALONE AnyWave Plugin code
   global host;
   global port;
   global pid;
 
   if (nargin < 3)
       error('missing arguments.');
  end
  host = varargin{1};
  port = str2num(varargin{2});
  pid = str2num(varargin{3});
  if (nargin > 3)
    args = varargin{4};
  end
 
  assignin('base', 'host',  host);
  assignin('base', 'port', port);
  assignin('base', 'pid', pid);
  assignin('base', 'args', args);
% end of STANDALONE AnyWave Plugin code
end

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:

Matlab3.png

As you can see MyPlugin is 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.

Matlab4.png
Retrieved from "https://meg.univ-amu.fr/index.php?title=AnyWave:WriteMatlabScripted&oldid=25863"