Skip to content

GitLab

MATLAB_get_data · Changes

Page history
transferring wiki from anywave to documentation authored by Bruno Colombet's avatar Bruno Colombet
Hide whitespace changes
Inline Side-by-side
Showing with 189 additions and 0 deletions
MATLAB_get_data.md 0 → 100644
View page @ 2d1e05f5
[[_TOC_]]
# Introduction
Getting data from anywave is getting channels.
Channels will be stored in a struct array.
## Channel struct description
````matlab
channel.name; % name (electrode label or electrode lable and reference label)
channel.type; % type of channel as a string.
channel.ref; % reference channel label, can be empty.
channel.sr; % Sampling Rate in Hz
channel.lp; % Low Pass filter value applied to data.
channel.hp; % High Pass filter value applied to data.
channel.notch; % notch filter value applied to data.
channel.data; % data as a vector of Single.
````
The result is a struct array containing the channels informations.
# Input channels policy
When a plugin is launched, depending on the input and modifiers flags defined, the default input channels may vary.
If no flags are specified, the default behavior is to pick the selected channels.
If no channels are selected within the AnyWave views, then the current montage channels are picked.
# Default usage
````matlab
function main(varargin)
anywave('init', varargin);
channels = anywave('get_data');
% Warning, channels may be empty
````
channels is the current list of channels AnyWave has set as input for the plugin. See the Input channels policy section.
# Add an extra parameter to the function
In order to specify constraints or requirements on the data we want to access to, the function allows an extra parameter which must be a struct.
# Change the default behavior when picking channels
Request the current montage channels:
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'montage';
channels = anywave('get_data', cfg);
% Here channels are the ones present in the current montage no matter the user selection.
````
Force to get as recorded channels (no matter the montage, we want channels present in the file):
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'raw';
channels = anywave('get_data', cfg);
````
Get selected channels:
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'selection';
channels = anywave('get_data', cfg);
% channels can be empty meaning there are no selected channels.
````
# Select a time range for data
The example below will get all the data available in the file which could be a lot of data.
To get only a chunk of the data use the following syntax:
````matlab
function main(varargin)
anywave('init', varargin);
cfg = []; % init empty struct
cfg.start = 10; % start at position 10s in the file
cfg.duration = 5; % we want 5 seconds of data
channels = anywave('get_data', cfg);
````
# Get data marked by markers
Instead of specifying a time range, it also possible to get data using time ranges provided by markers.
A marker has a position and may have a duration hence it can be used to get data.
````matlab
function main(varargin)
anywave('init', varargin);
cfg = []; % init empty struct
cfg.use_markers = {'EI'};
channels = anywave('get_data', cfg);
````
This code will get data marked by the EI marker(s).
WARNING: if there are several EI markers on the data file the data chunks of every markers will be concatenated and returned by get_data.
If you need to get EI markers one by one, the solution is to use the 'get_markers' command to have all markers in an array and then iterate over each markers requesting data with the 'get_data' command.
# Avoid data (artefacted)
It is also possible to get data specifying a time range and also make sure that bad data (mostly artefacted chunks) won't overlap the requested data.
````matlab
function main(varargin)
anywave('init', varargin);
cfg = []; % init empty struct
cfg.skip_markers = {'artefact', 'seizure' }; % we suppose artefact and seizure markers exist
channels = anywave('get_data', cfg);
````
This code will get all the data from the default picked channels EXCEPT chunks marked *artefact* and *seizure*.
# Get channels by their types
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'montage';
cfg.types = {'EEG' }; % get only EEG channels from the current montage.
channels = anywave('get_data', cfg);
% Warning channels may be empty if no EEG channels are present in the current montage.
````
# Get channel by their names
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'montage';
cfg.labels = {'TP1', 'TP2' }; % get only TP1 and TP2 channels, we assume they exist in the current montage.
channels = anywave('get_data', cfg);
````
## Specify a reference channel (bipolarity)
If you want a bipolar channels, just can specify the reference when setting the channel label :
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'montage';
% We want bipolar channels TP1-TP2 and TP2-TP3
cfg.labels = {'TP1 - TP2', 'TP2 - TP3' };
% We assume that the channels exist and their bipolar reference is possible.
channels = anywave('get_data', cfg);
````
# Specifying how to filter or not the data
By default, the data came as AnyWave will process them in the GUI.
## Force to get raw data (no filtering)
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'montage';
cfg.raw_data = true;
channels = anywave('get_data', cfg);
````
## Filter using low pass and high pass
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.channels_source = 'montage';
cfg.filters = [1 60 0]; % apply 1-60Hz filter, no notch.
% Note that the third value (notch) is optional.
channels = anywave('get_data', cfg);
````
# Advanced usage
This function also allows to do more complicated things like request to load data from a specified file or skip some chunks of data (artefacted data for example).
## Load data from a specified file
To get data from a file, the full path to the file must be specified as follow:
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.data_path = 'd:\data\file.eeg';
channels = anywave('get_data', cfg);
````
If the file cannot be opened an error will occur. It is a good practice to embed this code in a try catch section.
### Channels picking policy when specifying a data file
If the file specified has an associated .mtg file, AnyWave will load it and apply this montage.
Thus, the channels picked by default will be the montage channels.
You can however change this policy as shown before by adding the field channels_source to the struct.
## Specify a marker file
This feature allows using a custom marker file. The markers contained in that file can then be used with the following options:
*cfg.use_markers*
*cfg.skip_markers*
````matlab
function main(varargin)
anywave('init', varargin);
cfg = [];
cfg.marker_file= 'd:\data\my_markers.mrk'; % full path must be set
cfg.skip_markers = {'avoid', 'bad data'}; % we assume avoir and bad data are markers present in the my_markers.mrk file
channels = anywave('get_data', cfg);
````
\ No newline at end of file