base

Module: missions.nodes.visualization.base

Base class for visualization nodes

Classes

VisualizationBase:  

This node can be used as a base to visualize instances of the data as time series. To use the functionality of this node in a child node you just have to create one function, which is _plotValues:

Parameters of `_plotValues`

values:

dict TimeSeries values, e.g.:

{'Standard': TimeSeries(...),'Target'  : TimeSeries(...)}

plot_label:

str Plot-Label

fig_num:

int Figure-number for ?

store_dir:

str Directory to store the plots

counter:

int Plot counter for all trials

Inside this function you can perform any plot you want.

Inheritance diagram for pySPACE.missions.nodes.visualization.base:

VisualizationBase

class pySPACE.missions.nodes.visualization.base.VisualizationBase(request_training=True, request_test=True, separate_training_and_test=False, averaging=True, accum_avg=False, single_trial=False, time_stamps=[-1], store=False, store_data=False, create_movie=False, timeshift=0, online=False, user_dir='./', limit2class=None, physiological_arrangement=True, history_index=None, use_FN=True, use_SF=True, SF_channels=None, use_transformation=False, rand_initial_fig=True, covariancing=False, **kwargs)

Bases: pySPACE.missions.nodes.base_node.BaseNode

Base node for visualization

If you want to use the functionality you can inherit from it, like, e.g., ElectrodeCoordinationPlotNode does. See the module documentation for details.

This base class provides the following functionality:

• you can insert this node at any place in your node chain
• you can optionally plot single trials and/or averages (the latter also accumulating over time)
• you can either plot in online or in offline mode (see below)
• data is sorted according to labels
• optionally training and test data are distinguished
• feature vectors are automatically transferred to time series
• prediction vectors are evaluated according to the transformation they were generated from
• optionally you can add backward computing of previous transformations (e.g. spatial filters) to get better visualizations
• electrodes come with defined positions
• history values can be taken into account for plot

The node has a number of parameters to define what should be plotted, e.g. whether to plot single trials, accumulated average and/or average, or to plot training vs test data, or to constrain to a certain label.

Basically, there are two modes of plotting and storing the data: the offline mode (default) and the online mode. In the offline mode, the plotting is performed at the end and the plots are saved into the result_dir, specified for the store method in pySPACE. In the online mode, the plotting is performed as soon as the information is available and the user can specify the directory to store the data with the parameter user_dir.

Note

• Currently the data labels which are also given in the figure’s title are based on the tag from the data.
• If you use a splitter node previous to this node, the information of the different splits is also handled separately.
• This node is not changing the data as such!

Note

Be careful when configuring matplotlib! Interactive matplotlib-backends are not compatible between offline and online, when using live environment. Without the live environment, successful matplotlib backends used on a Mac were Agg (not interactive) and MacOSX. When using the live package, a working interactive matplotlib backend should be GTKAgg. You can change the matplotlib backend by modifying the matplotlibrc file in .matplotlib in your home directory, e.g. backend : GTKAgg.

Parameters

General parameters:  

rand_initial_fig:  

This option is useful when using the visualisation node multiple times within a node chain and getting the plots directly printed on-screen. The initial figure number is randomized between 1 and 10000, so each visualisation node most likely plots into different figure windows.

(optional, default: True)

online:

The computation is performed in “online” mode, i.e. the plots are generated in the execution period of the node. If you additionally store the data, the user_dir is used (see below). On the other hand, if the “offline” mode is used the plots are generated after all computations have been performed and the default way of saving the data is used.

(optional, default: False)

Limit the amount of data:  

limit2class:

List of strings. Only the data belonging to class labels in the list are plotted.

Note

If there is no match, no plot will be generated!

(optional, default: None)

request_training:  

Has to be True if you want to plot data belonging to the training set. If you are only interested in test data, you can set this parameter to False.

(optional, default: True)

request_test:

Has to be True if you want to plot data belonging to the test set.

(optional, default: True)

time_stamps:

Specify which points in time should be included in visualization. With the default option, all available time stamps are displayed. The time_stamps are computed with respect to the timeshift option (see below), i.e. in a data window of 600 ms length, with timeshift = -200 and time_stamps = [200], the data at 400 ms in the original window is displayed.

(optional, default: [-1])

Influence the way how the data is plotted:  

averaging:

If this is true, all samples are averaged and the plot is created using this average. The average is performed with respect to the class labels.

(optional, default: True)

accum_avg:

If this is true, you will see the average accumulating with trials in a separate window. Again, this average is computed for each class separately.

(optional, default: False)

single_trial:

If this is true, single trials are plotted.

(optional, default: False)

separate_training_and_test:  

When this option is True, training and test data are separately treated as if they belong to different classes. Therefore, if you have two original classes and set this option to True, your plot will consist of four subplots.

Note

Setting this option to True will force request_training and request_test to True.

(optional, default: False)

timeshift:

This parameter shifts the labels of the time axis. If, e.g., timeshift = -1000, the axis would show [-1000, 1000] instead of [0, 2000]. Adjust this according to how the windowing was performed - usually one would want to have the marker at time 0.

(optional, default: 0)

physiological_arrangement:  

This parameter controls whether the plots are arranged according to physiological positions. Otherwise this parameter has no effect.

(optional, default: True)

history_index:

This parameter only has effects if the node is used with a prediction vector (i.e. after a classification). Then the predictor property of the prediction vector is always scanned for a FeatureVector for plotting (if it is not found, then the history is scanned for another prediction vector). The parameter history_index now introduces a further switch: When set (between 1 and infinity), it specifies the depth in the history where the history is additionally used for the plot output (i.e. the corresponding node used keep_in_history=True). When the history is not used for something else, this depth is usually 1. The values usually correspond to the original feature values and are of type TimeSeries or FeatureVector. Then, the product of feature value and weight (i.e. the feature vector from the predictor) is computed for each data point. The result is finally plotted as topography.

(optional, default: None)

use_SF:

When the node gets a FeatureVector or PredictionVector this option controls whether the transformation of a preceding spatial filter (SF) is taken into account. If True, all artificial channels of the filter are transformed back to their original electrode counterparts. For full flexibility in what should be plotted, this option can be combined with history_index, use_FN, SF_channels and use_transformation.

(optional, default: True)

use_FN:

documentation in progress

(optional, default: True)

SF_channels:

documentation in progress

(optional, default: All)

use_transformation:  

documentation in progress

(optional, default: False)

Saving Options:

store:

If this is true, the graphics are stored to the persistency directory at the end of the run.

(optional, default: False)

user_dir:

This option is only active, if plotting is in online mode (online=True) and store=True. Then the user can specify where the data should be stored.

(optional, default: ‘./’)

create_movie:

If this is True, a video of the average signals is created. Does require the ffmpeg library. The video is created from plots in the store_dir.

Note

Enforces store=True.

(optional, default: False)

store_data:

With this additional option, you can store the data that has been used for plotting. The folder will be the same where the pictures are in. This option has no effect, if :store: is set to False.

(optional, default: False)

Author:

Sirko Straube (sirko.straube@dfki.de)

Date of Last Revision:  

2013/01/01

Class Components Summary

_create_movie(prefixes, directory)	Creates movies based on the stored plots.
_execute(data)	This function performs a couple of operations: No matter what kind of data is arriving, the data is transformed into TimeSeries (for more information see below).
_inc_train(data[, class_label])
_prepare_FV(data)	Convert FeatureVector into TimeSeries and use it for plotting.
_prepare_prediction(data)	Convert prediction vector to time series object for visualization
_train(data, label)	Every data instance that is passing this function gets a flag.
is_supervised()	Returns whether this node requires supervised training.
is_trainable()	Returns whether this node is trainable.
store_state(result_dir[, index])	Stores the plots to the result_dir and is used for offline plotting and for plotting of average values (online and offline).

__init__(request_training=True, request_test=True, separate_training_and_test=False, averaging=True, accum_avg=False, single_trial=False, time_stamps=[-1], store=False, store_data=False, create_movie=False, timeshift=0, online=False, user_dir='./', limit2class=None, physiological_arrangement=True, history_index=None, use_FN=True, use_SF=True, SF_channels=None, use_transformation=False, rand_initial_fig=True, covariancing=False, **kwargs)

Used to initialize the environment. Called by VisualizationBase child-node.

Parameters: See description above. Returns: Nothing.

is_trainable()

Returns whether this node is trainable. Method of base_node overwritten.

Returns: bool

is_supervised()

Returns whether this node requires supervised training. Method of base_node overwritten.

Returns: bool

_train(data, label)

Every data instance that is passing this function gets a flag.

Returns: nothing.

_execute(data)

This function performs a couple of operations: No matter what kind of data is arriving, the data is transformed into TimeSeries (for more information see below).

The main purpose of this function is to sort the data internally according to the applied and intended label (consisting maximally of “Training” or “Test” plus the actual class label) with respect to what should be plotted (single trial, average or accumulated average). In the end different the list of single_trials (st_list) and/or trials used for averaging (accum_list) are filled with respect to the evaluated label in this function. Accordingly separate counters are increased.

These lists and counters can be easily used by any visualisation child node.

Data instance will be skipped, if o limit2class is set and the the current label of the data is different o we got training-data, but request_training is False o we got test-data, but request_test is False

A list of skipped trials is built.

If it has been set: The flag data.specs[‘Training’]=True is evaluated and deleted afterwards.

Two representations of the data can be computed: o single trial data (=data) o a running average (=accum_avg)

In the online mode, the data is plotted here in the execute function (except average), otherwise in store_state.

Called by base_node.

Note

Currently the label is based on the tag. This should be fixed in the near future!

Returns: unmodified data

store_state(result_dir, index=None)

Stores the plots to the result_dir and is used for offline plotting and for plotting of average values (online and offline). Plots offline-data for every trial which has not been skipped. Optionally creates movies based on the stored images.

Called by base_node.

Returns: Nothing.

_create_movie(prefixes, directory)

Creates movies based on the stored plots.

Creates movies in the directory for the node. Movies will be created for those files with the given prefix. One movie for each prefix. Filename extensions may vary. See “man convert” for further informations.

Returns: Nothing.

_inc_train(data, class_label=None)

_prepare_prediction(data)

Convert prediction vector to time series object for visualization

Using the function get_previous_transformations the node history is searched for the respective transformation parametrizations and then the transformations are combined tog et a complete picture of the data processing chain.

A special case is, when the BacktransformationNode

Parameters

data:This is a Prediction Vector, which might contain data in its history component which is used for multiplication with the transformation or which is used as sample for calculating the derivative of the processing chain for the backtransformation.

_prepare_FV(data)

Convert FeatureVector into TimeSeries and use it for plotting.

Note

This function is not yet working as it should be. Work in progress. Commit due to LRP-Demo (DLR Review)