Difference between revisions of "AnyWave:WritePythonScripted"
(→getData(start, duration, , )) |
(→get_markers) |
||
(71 intermediate revisions by one user not shown) | |||
Line 1: | Line 1: | ||
− | = | + | =Requirements= |
− | + | '''Python 2.7 64bit must be installed on your computer. The numpy package is also required.'''<br /> | |
− | The | + | We suggest to install the Anaconda Package for your system which is available [[https://www.continuum.io/downloads here]]<br /> |
− | We | + | |
− | + | =Configuring AnyWave to use Pyhton= | |
− | + | It's very simple, just open the Preferences UI:<br /> | |
− | + | [[File:PythonPrefs.png|center]]<br /> | |
− | + | This is a Windows version of AnyWave on which we are using the Anaconda Python package. The path is the location of the Python interpreter.<br /> | |
− | + | This is quite similar on Mac or Linux, just point to the python interpreter you want to use to run your plug-ins.<br /> | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | The | + | |
− | + | ||
− | + | ||
− | + | ||
+ | =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= | =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:<br /> | |
<syntaxhighlight lang="text"> | <syntaxhighlight lang="text"> | ||
− | name = | + | name = PyExample Plugin |
− | description = I | + | description = I'm a Python plugin |
− | category = Process:Python: | + | category = Process:Python:PyExample |
</syntaxhighlight> | </syntaxhighlight> | ||
+ | The syntax is to set keywords and values.<br /><br /> | ||
− | + | Here we have three keywords (name, description, category).<br /> | |
+ | Two keywords are mandatory : name and description. Other keywords are optional.<br /> | ||
+ | ==keywords== | ||
+ | '''name:''' The plugin name used by Anywave (here PyExample Plugin).<br /> | ||
+ | '''description:''' a brief description of what the plugin does.<br /> | ||
+ | '''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.<br /> | ||
− | The category feature is usefull to separate plug- | + | 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: | 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' | * 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: 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' | * 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. | 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:<br /> | ||
+ | [[File:PyLocation.png|center]] | ||
+ | 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 | + | =The AnyWave module= |
− | + | The python support in AnyWave consists in a Python module called anywave which is automatically imported when launching the Python interpreter.<br /> | |
+ | So it is not necessary to import it again when programming a Python plugin.<br /> | ||
+ | ==A short example== | ||
+ | Let's see a very simple plugin example: (don't forget to place it in a __main__.py file)<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # get informations about the current data associated with our plugin by AnyWave: | ||
+ | infos = anywave.get_plugininfo(); | ||
+ | print infos; | ||
+ | </syntaxhighlight> | ||
+ | As you can see it's very short and simple. The get_plugininfo method is documented in the Python objects section.<br /> | ||
+ | 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.<br /> | ||
+ | That means you can get markers from AnyWave in your plugin, or create your own marker in Python and send them to AnyWave.<br /> | ||
+ | The same possibility is available for channels.<br /> | ||
+ | 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=== | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # create a channel object | ||
+ | channel = anywave.channel(label="Cz", type="EEG"); | ||
+ | </syntaxhighlight> | ||
+ | This example shows how to create a channel object in Python.<br /> | ||
+ | The channel object has the following methods and attributes:<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | 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) | ||
+ | </syntaxhighlight> | ||
− | + | ===Markers=== | |
+ | <syntaxhighlight lang="python"> | ||
+ | # create a marker object | ||
+ | marker = anywave.marker(label="artefact", value=10, position=5.0, duration = 2.5, color="yellow"); | ||
+ | </syntaxhighlight> | ||
+ | This example shows how to create a marker object in Python.<br/> | ||
+ | The marker object has the following methods and attributes:<br/> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | 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. | ||
+ | </syntaxhighlight> | ||
+ | ==Methods== | ||
+ | ===get_plugininfo=== | ||
+ | This method returns a dictionary in which you could find the following:<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | .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. List of strings. | ||
+ | .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. | ||
+ | </syntaxhighlight> | ||
+ | Example:<br/> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # 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"] | ||
+ | </syntaxhighlight> | ||
− | = | + | ===get_markers=== |
− | + | This method will return a list of marker objects.<br/> | |
+ | Input arguments is a dict in which you can set the following parameters:<br/> | ||
+ | 'file' : 'path to marker file' (optional: specify a marker file from which get the markers.)<br/> | ||
+ | 'extracttriggers' : 'yes' (optional: ask AnyWave to parse trigger channels of the data to get markers from there.)<br/> | ||
+ | 'values' : tuple of float values (optional: specify the values requested for the markers).<br/> | ||
+ | 'labels' : tuple of strings (optional : specify the labels of the markers.)<br/> | ||
+ | 'channels' : tuple of strings (optional: specify the targeted channels of the marekrs.<br/> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # 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' | ||
+ | </syntaxhighlight> | ||
+ | You can also specify options to filter the markers you want:<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # 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. | ||
+ | </syntaxhighlight> | ||
− | = | + | <syntaxhighlight lang="python"> |
− | + | # Get markers with specified values | |
+ | markers = anywave.get_markers({'values' : [2, 8]}) | ||
+ | # We should get all markers with value 2 or 8. | ||
+ | </syntaxhighlight> | ||
− | + | <syntaxhighlight lang="python"> | |
− | + | # Get markers which are targeting channels | |
− | + | markers = anywave.get_markers({'channels' : ['A1', 'A2']}) | |
+ | # We should get all the markers targeting A1 or A2 channels. | ||
+ | </syntaxhighlight> | ||
− | + | ===add_markers=== | |
− | + | This method sends markers to AnyWave.<br /> | |
− | + | Example: | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | == | + | |
− | This method | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
− | # | + | # 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]) | ||
+ | </syntaxhighlight> | ||
+ | ===get_data=== | ||
+ | This method will request data and returns a list of channels.<br /> | ||
+ | Example:<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # 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 |
− | anywave. | + | </syntaxhighlight> |
+ | There are several other parameters:<br /> | ||
+ | '''Request using electrode labels'''<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # Get the data from specified channels (A1 and A2) | ||
+ | channels = anywave.get_data({'start' : 0., 'duration' : 5., 'labels' : ['A1', 'A2']}) | ||
+ | </syntaxhighlight> | ||
+ | <br /> | ||
+ | '''Request with filtering options:'''<br /> | ||
+ | ''Note that if no filtering option is specified, the data will be filtered as they are in AnyWave (using user options set in AnyWave).''<br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # Get the data WITHOUT any filtering (raw data) | ||
+ | channels = anywave.get_data({'start' : 0., 'duration' : 5., 'filtering' : 'no'}) | ||
+ | </syntaxhighlight> | ||
+ | <br /> | ||
+ | <syntaxhighlight lang="python"> | ||
+ | # 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 | ||
</syntaxhighlight> | </syntaxhighlight> | ||
+ | ====complete list of parameters==== | ||
+ | '''start''' : starting position in seconds. (float)<br /> | ||
+ | '''duration''': length of data in seconds. (float)<br /> | ||
+ | '''file''': path to a file (string). This option will tell AnyWave to open the specified file and get the data from it. <br /> | ||
+ | '''montage''': path to a montage file (usually used with file ) (string)<br /> | ||
+ | '''filtering''': 'yes' or 'no'. If 'yes', force the filtering options for the data. if 'no' force AnyWave to get the raw data.<br /> | ||
+ | '''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.<br /> | ||
+ | '''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.<br /> | ||
+ | '''decimate''': integer factor of decimation. This will decimate the data with the specified factor. An anti aliasing filter is applied before decimation.<br /> |
Latest revision as of 10:31, 13 December 2018
Contents
Requirements
Python 2.7 64bit must be installed on your computer. The numpy package is also required.
We suggest to install the Anaconda Package for your system which is available [here]
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 the Anaconda Python package. The path is the location of the Python interpreter.
This is quite similar on Mac or Linux, just point to the python interpreter you want to use to run your plug-ins.
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
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. List of strings. .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.
Example:
# 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"]
get_markers
This method will return a list of marker objects.
Input arguments is a dict in which you can set the following parameters:
'file' : 'path to marker file' (optional: specify a marker file from which get the markers.)
'extracttriggers' : 'yes' (optional: ask AnyWave to parse trigger channels of the data to get markers from there.)
'values' : tuple of float values (optional: specify the values requested for the markers).
'labels' : tuple of strings (optional : specify the labels of the markers.)
'channels' : tuple of strings (optional: specify the targeted channels of the marekrs.
# 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.