Difference between revisions of "AnyWave:MATLAB API"

From WikiMEG
Jump to: navigation, search
(Created page with "I am 32 years old and my name is Madonna Edman. I life in Berlin Wedding (Germany).<br><br>Feel free to visit my web page [http://universalgenerators.wordpress.com/2014/02/18/...")
 
(Created page with "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 av...")
Line 1: Line 1:
−
I am 32 years old and my name is Madonna Edman. I life in Berlin Wedding (Germany).<br><br>Feel free to visit my web page [http://universalgenerators.wordpress.com/2014/02/18/comment-avoir-des-jeux-steam-gratuit/ Jeux Steam Gratuit]
+
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"
 +
|-
 +
! Function !! Short description
 +
|-
 +
| '''[[#aw_getplugininfo()|aw_getplugininfo]]''' || Returns useful information about the plugin.
 +
|-
 +
| '''[[#aw_getdata()|aw_getdata]]''' || Returns data from AnyWave (deprecated, use aw_getdatex).
 +
|-
 +
| '''[[#aw_getdataexs()|aw_getdataexs]]''' || Gets data from AnyWave.
 +
|-
 +
| '''[[#aw_getmarkers()|aw_getmarkers]]''' || Returns markers from AnyWave.
 +
|-
 +
| '''[[#aw_addmarkers()|aw_addmarkers]]''' || Sends markers to AnyWave.
 +
|}
 +
 
 +
==aw_getplugininfo==
 +
<syntaxhighlight lang="matlab">
 +
function [ infos ] = aw_getplugininfo()
 +
%aw_getplugininfo returns information about the input set for the plugin.
 +
%  infos = aw_getplugininfo();
 +
%
 +
%  returns a structure with the following fields:
 +
%  .file
 +
%      Name of the file open in AnyWave.
 +
%  .labels
 +
%      labels of channels set as input for the plugin.
 +
%  .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.file = 'file.eeg';
 +
%      Specify the data file to use. (optional)
 +
%  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.
 +
%  NOTE:
 +
%  start and duration are depecrated. Consider using chunks starting with the september 18 release of AnyWave.
 +
%
 +
%  Starting with september 18 release, you can use chunks vector to get one or several part of the signals at once.
 +
%  cfg.chunks = [10 20]; % at least one chunk
 +
%  a chunk must have at least two values (start and duration).
 +
%  NOTE: if start and duration are used, chunks will be ignored.
 +
%
 +
%  Specifying the electrodes labels:
 +
%  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.
 +
%      Optional field.
 +
%  NOTE: when specifying labels, AnyWave will get the data from those channels without considering the current Montage.
 +
%        If some channels are marked as bad, they won't be returned.
 +
%  cfg.types = {'EEG'};
 +
%      cell array of strings to specify the types of channels we want.
 +
%      Optional field.
 +
%  NOTE: when specifying types, AnyWave will get the data from the corresponding channel in the file without considering the current montage.
 +
%        If some channels are marked as bad, they won't be returned.
 +
%
 +
%  NOTE: if labels and types are used, then the channel selection will be made with respect with these two constraints.
 +
%  For example, if the labels cell array contains the A1 label, and the types cell array contains the EEG type, then
 +
%  AnyWave will return the A1 EEG channel if it exists or nothing. If A1 is MEG or SEEG then nothing will be returned.
 +
%
 +
%  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 filtering options.
 +
%
 +
%  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:
 +
%  .name;
 +
%      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);
 +
 
 +
%  request data for all EEG channels, no filtering specified
 +
cfg = [];
 +
cfg.start = 0;
 +
cfg.duration = 10; % 10 seconds of data
 +
cfg.types = { 'EEG' };
 +
channels = aw_getdata(cfg);
 +
 
 +
end
 +
</syntaxhighlight>
 +
 
 +
==aw_addmarkers==
 +
<syntaxhighlight lang="matlab">
 +
function aw_addmarkers(markers)
 +
%aw_addmarkers add new markers to AnyWave
 +
%  aw_addmarkers(markers)
 +
%
 +
%  markers is an array of structs. Each element is a marker to be added.
 +
%
 +
% See also AwMarker
 +
% 
 +
%
 +
end
 +
 
 +
function [ marker ] = AwMarker( label, position, duration, value, targets)
 +
% defines the structure for a marker
 +
%
 +
%  marker.label
 +
%      the label for the marker.
 +
%  marker.position
 +
%      the position in seconds from the beginning of data.
 +
%  marker.duration
 +
%      the duration in seconds. Can be 0 if the marker is just a position
 +
%      in time.
 +
%  marker.value
 +
%      the value associated to the marker. -1 indicates that no value is
 +
%      set.
 +
%  marker.targets
 +
%      a cell array containing the targeted channels. Empty if the marker
 +
%      is global.
 +
marker.label = label;               
 +
marker.position = position;
 +
marker.duration = duration;         
 +
marker.value = value;
 +
marker.targets = targets;           
 +
 
 +
end
 +
</syntaxhighlight>
 +
 
 +
'''Example:'''<br />
 +
<syntaxhighlight lang="matlab">
 +
function main
 +
%
 +
% add one marker labeled spike at position 3s.
 +
%
 +
marker.label = 'spike';
 +
marker.position = 3;
 +
 
 +
 
 +
% send the marker to AnyWave
 +
aw_addmarkers(marker);
 +
 
 +
% add two markers with value and targeted channels
 +
markers(1).label = 'spike';
 +
markers(1).position = 3;
 +
markers(1).value = 2;
 +
markers(1).targets = {'A2'};  % this marker is targeting the channel named A2
 +
 
 +
markers(2).label = 'selection';
 +
markers(2).position = 15;
 +
markers(2).duration = 1.5; % this marker is a selection of 1.5s starting at position 15s.
 +
% no targets are specified, the marker is GLOBAL
 +
 
 +
% send the markers to AnyWave
 +
aw_addmarkers(markers);
 +
 
 +
end
 +
</syntaxhighlight>
 +
 
 +
==aw_getmarkers==
 +
<syntaxhighlight lang="matlab">
 +
function [ markers ] = aw_getmarkers( cfg )
 +
%aw_getmarkers retrieves markers from AnyWave
 +
%  markers = aw_getmarkers(cfg)
 +
%  markers = aw_getmarkers()
 +
%  returns markers which match the settings defined in cfg structure or
 +
%  all available markers if no cfg structure is passed as paramater.
 +
%
 +
%  cfg may contain the following fields:
 +
% 
 +
%  cfg.values = [1 10 12];
 +
%      get markers depending on their value. Several values can be
 +
%      specified.
 +
%  cfg.labels = {'Spike1', 'Spike2'};
 +
%      get markers depending on their labels.
 +
%  cfg.channels = {'A1', 'A2'};
 +
%      get markers which target specific channels.
 +
%
 +
% Note: if a marker matches several conditions (values, labels or channels) only one
 +
% instance of the marker is returned.
 +
%
 +
%Output:
 +
%  markers is an array of strucrures with the following fields:
 +
%  .label
 +
%      a string representing the marker's label.
 +
%  .position
 +
%      the position in seconds from beginning of data.
 +
%  .duration
 +
%      duration in seconds. Can be zero if the marker is just a time position.
 +
%  .value
 +
%      a numerical value associated with the marker. -1 indicates that no value is set.
 +
%  .channels 
 +
%      a cell array of channel labels. Can be empty if the marker is
 +
%      global to all channels.
 +
%
 +
end
 +
</syntaxhighlight>
 +
 
 +
'''Example:'''<br />
 +
<syntaxhighlight lang="matlab">
 +
function main()
 +
% get all the markers currently available in AnyWave
 +
markers = aw_getmarkers();
 +
 
 +
% get markers labeled spike
 +
cfg=[];
 +
cfg.labels = {'spike'};
 +
 
 +
spikes = aw_getmarkers(cfg);
 +
 
 +
% get markers with specified values
 +
cfg=[];
 +
cfg.values = [2 3 4];
 +
 
 +
markers = aw_getmarkers(cfg);
 +
 
 +
% mixing values and labels conditions
 +
cfg=[];
 +
cfg.labels = {'spike', 'selection'};
 +
cfg.values = [2 10];
 +
 
 +
% Note that the returned markers are markers which satisfied one of the conditions (it's a logical OR test).
 +
% That means you can get a marker labeled spike but with a value that is not 2 or 10;
 +
% It's up to you to parse the array of structures afterward.
 +
markers = aw_getmarkers(cfg);
 +
 
 +
% CAUTION
 +
markers can be an empty matrix if no markers are returned by AnyWave
 +
 
 +
end
 +
</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">
 +
 
 +
cfg = [];
 +
cfg.start = 0;
 +
cfg.duration = -1;
 +
channels = aw_getdata(cfg); % get all data
 +
 
 +
for (i=1:numel(channels)
 +
  AwSendMessage(sprintf('Processing channel %d', i));
 +
  % do something
 +
end
 +
</syntaxhighlight>
 +
 
 +
==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:
 +
<syntaxhighlight lang="matlab">
 +
 
 +
cfg = [];
 +
cfg.start = 0;
 +
cfg.duration = -1;
 +
channels = aw_getdata(cfg); % get all data
 +
 
 +
%
 +
for (i=1:numel(channels)
 +
    if (~AwProcessIsTerminated())
 +
        % do some heavy calculation on a data contained in channel
 +
  end
 +
end
 +
 
 +
</syntaxhighlight>

Revision as of 15:15, 4 September 2018

The table below shows a summary of all MATLAB functions available when writing a MATLAB Scripted plug-in:

Note: All AnyWave MATLAB functions start with 'aw_' to avoid confusions with other MATLAB functions.

Function Short description
aw_getplugininfo Returns useful information about the plugin.
aw_getdata Returns data from AnyWave (deprecated, use aw_getdatex).
aw_getdataexs Gets data from AnyWave.
aw_getmarkers Returns markers from AnyWave.
aw_addmarkers Sends markers to AnyWave.

aw_getplugininfo

function [ infos ] = aw_getplugininfo()
%aw_getplugininfo returns information about the input set for the plugin.
%   infos = aw_getplugininfo();
%
%   returns a structure with the following fields:
%   .file
%       Name of the file open in AnyWave.
%   .labels
%       labels of channels set as input for the plugin.
%   .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

aw_getdata

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.file = 'file.eeg';
%       Specify the data file to use. (optional)
%   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.
%   NOTE:
%   start and duration are depecrated. Consider using chunks starting with the september 18 release of AnyWave.
%
%   Starting with september 18 release, you can use chunks vector to get one or several part of the signals at once.
%   cfg.chunks = [10 20]; % at least one chunk 
%   a chunk must have at least two values (start and duration).
%   NOTE: if start and duration are used, chunks will be ignored.
%
%   Specifying the electrodes labels:
%   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.
%       Optional field.
%   NOTE: when specifying labels, AnyWave will get the data from those channels without considering the current Montage.
%         If some channels are marked as bad, they won't be returned.
%   cfg.types = {'EEG'};
%       cell array of strings to specify the types of channels we want.
%       Optional field.
%   NOTE: when specifying types, AnyWave will get the data from the corresponding channel in the file without considering the current montage.
%         If some channels are marked as bad, they won't be returned.
%
%   NOTE: if labels and types are used, then the channel selection will be made with respect with these two constraints.
%   For example, if the labels cell array contains the A1 label, and the types cell array contains the EEG type, then
%   AnyWave will return the A1 EEG channel if it exists or nothing. If A1 is MEG or SEEG then nothing will be returned.
%
%   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 filtering options.
%
%   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:
%   .name; 
%       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

Example:

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);
 
%  request data for all EEG channels, no filtering specified
cfg = [];
cfg.start = 0;
cfg.duration = 10; % 10 seconds of data
cfg.types = { 'EEG' };
channels = aw_getdata(cfg);
 
end

aw_addmarkers

function aw_addmarkers(markers)
%aw_addmarkers add new markers to AnyWave
%   aw_addmarkers(markers) 
%
%   markers is an array of structs. Each element is a marker to be added.
%
% See also AwMarker
%   
%
end
 
function [ marker ] = AwMarker( label, position, duration, value, targets)
% defines the structure for a marker
% 
%   marker.label
%       the label for the marker.
%   marker.position
%       the position in seconds from the beginning of data.
%   marker.duration
%       the duration in seconds. Can be 0 if the marker is just a position
%       in time.
%   marker.value
%       the value associated to the marker. -1 indicates that no value is
%       set.
%   marker.targets
%       a cell array containing the targeted channels. Empty if the marker
%       is global.
marker.label = label;                 
marker.position = position;
marker.duration = duration;           
marker.value = value;
marker.targets = targets;             
 
end

Example:

function main
%
% add one marker labeled spike at position 3s.
%
marker.label = 'spike';
marker.position = 3;
 
 
% send the marker to AnyWave
aw_addmarkers(marker);
 
% add two markers with value and targeted channels
markers(1).label = 'spike';
markers(1).position = 3;
markers(1).value = 2;
markers(1).targets = {'A2'};  % this marker is targeting the channel named A2
 
markers(2).label = 'selection';
markers(2).position = 15;
markers(2).duration = 1.5; % this marker is a selection of 1.5s starting at position 15s.
% no targets are specified, the marker is GLOBAL
 
% send the markers to AnyWave
aw_addmarkers(markers);
 
end

aw_getmarkers

function [ markers ] = aw_getmarkers( cfg )
%aw_getmarkers retrieves markers from AnyWave
%   markers = aw_getmarkers(cfg) 
%   markers = aw_getmarkers()
%   returns markers which match the settings defined in cfg structure or
%   all available markers if no cfg structure is passed as paramater.
%
%   cfg may contain the following fields: 
%   
%   cfg.values = [1 10 12];
%       get markers depending on their value. Several values can be
%       specified.
%   cfg.labels = {'Spike1', 'Spike2'};
%       get markers depending on their labels.
%   cfg.channels = {'A1', 'A2'};
%       get markers which target specific channels.
%
% Note: if a marker matches several conditions (values, labels or channels) only one
% instance of the marker is returned.
%
%Output:
%   markers is an array of strucrures with the following fields:
%   .label 
%       a string representing the marker's label.
%   .position
%       the position in seconds from beginning of data.
%   .duration
%       duration in seconds. Can be zero if the marker is just a time position.
%   .value
%       a numerical value associated with the marker. -1 indicates that no value is set. 
%   .channels  
%       a cell array of channel labels. Can be empty if the marker is
%       global to all channels.
%
end

Example:

function main()
% get all the markers currently available in AnyWave
markers = aw_getmarkers();
 
% get markers labeled spike
cfg=[];
cfg.labels = {'spike'};
 
spikes = aw_getmarkers(cfg);
 
% get markers with specified values
cfg=[];
cfg.values = [2 3 4];
 
markers = aw_getmarkers(cfg);
 
% mixing values and labels conditions
cfg=[];
cfg.labels = {'spike', 'selection'};
cfg.values = [2 10];
 
% Note that the returned markers are markers which satisfied one of the conditions (it's a logical OR test).
% That means you can get a marker labeled spike but with a value that is not 2 or 10;
% It's up to you to parse the array of structures afterward.
markers = aw_getmarkers(cfg);
 
% CAUTION
markers can be an empty matrix if no markers are returned by AnyWave
 
end

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: 

cfg = [];
cfg.start = 0;
cfg.duration = -1;
channels = aw_getdata(cfg); % 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: 

cfg = [];
cfg.start = 0;
cfg.duration = -1;
channels = aw_getdata(cfg); % get all data
 
% 
for (i=1:numel(channels)
    if (~AwProcessIsTerminated())
         % do some heavy calculation on a data contained in channel
   end
end
Retrieved from "https://meg.univ-amu.fr/index.php?title=AnyWave:MATLAB_API&oldid=25427"