Py_get_data.md

+[[_TOC_]]
+
+# Introduction
+Getting data from anywave is getting channels.
+The function will return a list of Channel objects.   
+
+## Channel object
+````python
+import anywave
+chan = anywave.Channel()
+
+chan.name # name (electrode label or electrode label and reference label)
+chan.type   # type of channel as a string.
+chan.ref    # reference channel label, can be empty.
+chan.sr     # Sampling Rate in Hz
+chan.lp     # Low Pass filter value applied to data.
+chan.hp     # High Pass filter value applied to data.
+chan.notch  # notch filter value applied to data.
+chan.data   # data is a numpy array of float32
+
+````
+
+# 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
+````python
+import sys, anywave
+anywave.init(sys.argv)
+
+channels = anywave.get_data()
+
+````
+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:    
+````python
+import sys, anywave
+anywave.init(sys.argv)
+
+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):   
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+cfg = { 'channels_source' : 'raw' }
+channels = anywave.get_data(cfg)
+````
+
+Get selected channels:    
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+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:   
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+# start at position 10s in the file
+ # we want 5 seconds of data
+cfg = { 'start' : 10, 'duration' : 5 } 
+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.   
+````python
+import sys, anywave
+anywave.init(sys.argv)
+
+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* function to have all markers in an array and then iterate over each markers requesting data with the *get_data* function.
+# 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.
+````python
+import sys, anywave
+anywave.init(sys.argv)
+# we suppose artefact and seizure markers exist 
+cfg = { 'skip_markers' : ['artefact', 'seizure']  } 
+
+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
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+cfg = { 'channels_source' : 'montage', 'types' : ['EEG']  } 
+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
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+
+cfg = { 'channels_source' : 'montage', '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 :   
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+cfg = { 'channels_source' : 'montage', 'labels' : ['TP1 - TP2', 'TP2 - TP3'] } 
+# We want bipolar channels TP1-TP2 and 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)
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+cfg = { 'channels_source' : 'montage', 'raw_data' : True } 
+channels = anywave('get_data', cfg);
+````
+## Filter using low pass and high pass
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+cfg = { 'channels_source' : 'montage', '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:   
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+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 keys:      
+*'use_markers'*   
+*'skip_markers'* 
+````python
+import sys, anywave
+
+
+anywave.init(sys.argv)
+cfg = { 'marker_file' : 'd:\data\my_markers.mrk', 'skip_markers' : ['avoid', 'bad data']  } 
+# full path must be set
+ # 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