Difference between revisions of "AnyWave:MATLAB API"

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.
%   .rejected_ics 
%      labels of rejected independent components (ICA). Empty if no ICA computation is involved.
%
end

io = aw_getpluginio();
% the function returns a structure containing: 
% .file - Full path to the the data file open in AnyWave.
% .data_dir - The directory where the data file is.
% .labels - Cell array containing the labels of all channels set as input for the plugin.
% .refs - Cell array containing the reference labels of all channels (can be empty if monopolar montage).
% .types - Cell array containing the types of the corresponding labels (strings).
% .max_sr - Maximum sampling rate of the data in Hz.
% .total_duration - Total duration in seconds of the data file.
% .temp_dir - Path to the temporary directory created by AnyWave.
% .plugin_dir - Path to the current plugin.
% .ica_file -  Path to the current loaded ICA file (empty if no ica file loaded).
% .rejected_ics - Labels of all ICA channels rejected by the user. (empty is no ICA channels is loaded or set as rejected.)
% .markers - Array of structs containing the markers set as input for the plugin.
%   Each marker is a struct containing:
%   .label - The label of the marker.
%   .position - The position in seconds of the marker.
%   .duration - The marker duration (0 if single marker).
%   .value - The value associated to the marker (-1 if no value).
%   .chunk - Vector containing the position and duration of the marker (position and duration vectorized).
%
% Example: get all the chunks into one vector.
% chunks = [ io.markers(:).chunk];
%
% Get the chunks into a vector for markers labels 'Event1':
% chunks = [ io.markers(find(cellfun(@(x)isequal(x, 'Event1'), {markers.label} ))).chunk];
%
% NOTE: chunks will be usefull when used with the new aw_getdataex function. See below.

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.
%   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

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

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

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

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

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

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

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