Revision as of 16:26, 12 June 2017

Introduction

Here we assume that you have Python 2.7 installed on your system with at least the numpy package.

Configuring AnyWave to use Pyhton

It's very simple, just open the Preferences UI:

This is a Windows version of AnyWave on which we are using Anaconda Python package. The path is the location of the Python interpreter.
That's it, your are ready to use Python plugins.

What is a Python plugin?

It's a folder containing at least two files:

• __main__.py Python code file.
• desc.txt Text file giving information about the plugin.

Writing the desc.txt file

We will write a Python example plugin which will be named PyExample, so the desc.txt file should look like:

name = PyExample Plugin
description = I'm a Python plugin
category = Process:Python:PyExample

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.

keywords

name: The plugin name used by Anywave (here PyExample Plugin).
description: a brief description of what the plugin does.
category (optional): 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 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 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.

Copying the plugin to the correct location

To make AnyWave find our plugin we must copy it to a specific location:

This is the default Documents folder on Windows in which AnyWave created its own folders.

The Python subfolder is where AnyWave will look for Python plugins.

The AnyWave module

The python support in AnyWave consists in a Python module called anywave which is automatically imported when launching the Python interpreter.
So it is not necessary to import it again when programming a Python plugin.

A short example

Let's see a very simple plugin example: (don't forget to place it in a __main__.py file)

# get informations about the current data associated with our plugin by AnyWave:
infos = anywave.get_plugininfo(); 
print infos;

As you can see it's very short and simple. The get_plugininfo method is documented in the Python objects section.
Basically, it returns the labels of the electrodes, their references, the maximum sampling rate of data, etc.

Python Objects

There are two objects of AnyWave currently available within the Python interpreter: markers and channels.
That means you can get markers from AnyWave in your plugin, or create your own marker in Python and send them to AnyWave.
The same possibility is available for channels.
Markers and Channels are the two main objects to handle data in AnyWave:

• The signals you see in AnyWave are channels.
• The time selections, or events are markers.

Channels

# create a channel object
channel = anywave.channel(label="Cz", type="EEG");

This example shows how to create a channel object in Python.
The channel object has the following methods and attributes:

channel.label = "A1";  # the label of the electrode (MANDATORY)
channel.ref = "A2";    # the electrode used as reference (a bipolar channel). If no ref is set, then the channel is considered monopolar.
channel.type = "EEG";  # Type of channel. Could be (EEG, SEEG, MEG, Trigger, Other, ICA, Source, ECG, EMG). If no type is set, the channel is set to EEG.
channel.lpf = 40;      # Sets a low pass filter for the channel (40Hz). (optional)
channel.hpf = 1;       # Sets a high pass filter for the channel (1Hz). (optional)
channel.notch = 50;    # Sets a notch filter for 50Hz. (optional)
channel.data = numpy.zeros(1000); # Sets a vector of 1000 samples as the data for the channels.
channel.sr = 1000;     # Sets the sampling rate of data at 1000Hz. (MANDATORY)

Markers

# create a marker object
marker = anywave.marker(label="artefact", value=10, position=5.0, duration = 2.5, color="yellow");

This example shows how to create a marker object in Python.
The marker object has the following methods and attributes:

marker.label = "artefact";  # the label of the marker
marker.position = 5.0;      # the markers starts at 5.0s after the beginning of the file
marker.duration = 2.5;      # the markers has a duration of 2.5s which means this is a time selection marker.
# if duration is not set, the marker is considered as Single and marks an instant.
marker.value = 10;          # adds a numerical value to the marker (optional)
marker.color = "yellow";    # defines the color AnyWave will use to render the marker. (optional)
marker.channels = ["A1", "A2"]; # the marker will target two channels (A1 and A2).
# this is optional. If a marker does not target channels, it is considered as a global marker.

Methods

get_plugininfo

# Get information about the data loaded in AnyWave
infos = anywave.get_plugininfo();
# print the labels of channels set as input for the current plugin:
print infos.labels;

This method returns a dictionary in which you could find the following:

.file # the path to the current data file open in AnyWave
.ica_file # the path to the currently ICA file loaded. This item is only added to the dict. if the user has loaded an ICA HDF5 file in AnyWave.
.labels # the labels of the channels set as input for the plugin. 
.refs   # the references of the electrodes (could be a list of empty strings if channels are monopolars).
.max_sr # the maximum sampling rate in Hz.
.total_dur # the total duration in seconds of the data.
.temp_dir # the path to the temp dir AnyWave has created for our plugin.
.plugin_dir # the path to our plugin.

get_markers

# Get all the markers from anywave
markers = anywave.get_markers();
# print the labels of all markers
for m in markers:
   print m.label; 
   print '\n';

You can also specify options to filter the markers you want:

# Get markers with specified labels, here get only Annotation markers
markers = anywave.get_markers({'labels' : ['Annotation']})
# Note that if no Annotation markers exist, the method will return an empty list of objects.

# Get markers with specified values
markers = anywave.get_markers({'values' : [2, 8]})
# We should get all markers with value 2 or 8.

# Get markers which are targeting channels
markers = anywave.get_markers({'channels' : ['A1', 'A2']})
# We should get all the markers targeting A1 or A2 channels.

add_markers

This method sends markers to AnyWave.
Example:

# Create two markers and send them to AnyWave
m1 = anywave.marker(label="marker1", position = 10.0)
m2 = anywave.marker(label="marker2", position = 15.0)
anywave.add_markers([m1, m2])

get_data

This method will request data and returns a list of channels.
Example:

# A plugin always have channels as input. Those channels can have been selected by the user for example.
# Here we just request for 5s of data starting at the beginning of the file.
channels = anywave.get_data({('start' : 0., 'duration' : 5.})
# Get the data of the first channel
data = channels[0]['data']
# data is a numpy array vector of float32

There are several other parameters:
Request using electrode labels

# Get the data from specified channels (A1 and A2)
channels = anywave.get_data({'start' : 0., 'duration' : 5., 'labels' : ['A1', 'A2']})

Request with filtering options:
Note that if no filtering option is specified, the data will be filtered as they are in AnyWave (using user options set in AnyWave).

# Get the data WITHOUT any filtering (raw data)
channels = anywave.get_data({'start' : 0., 'duration' : 5., 'filtering' : 'no'})

# Get the data with a 40Hz low pass on EEG (we suppose channels are EEG)
channels = anywave.get_data({'start'  : 0., 'duration' : 5., 'filtering' : 'yes', 'eeg_lp' : 40. })
# filter options are:
# eeg_lp, eeg_hp, meg_lp, meg_hp
# Note that eeg filters are also used for seeg channels. 
# So, if you want to filter seeg data, use eeg_lp or eeg_hp parameters

complete list of parameters

start : starting position in seconds. (float)
duration: length of data in seconds. (float)
file: path to a file (string). This option will tell AnyWave to open the specified file and get the data from it.
montage: path to a montage file (usually used with file ) (string)
filtering: 'yes' or 'no'. If 'yes', force the filtering options for the data. if 'no' force AnyWave to get the raw data.
labels: list of channel labels to get data from. May result in empty output if the labels do not match any channels in the current data file.
types: list of channel types to get (strings). For example: ['SEEG', 'EEG'] will force to get the data from ALL the seeg and eeg channels in the data file.
decimate: integer factor of decimation. This will decimate the data with the specified factor. An anti aliasing filter is applied before decimation.