braindecode.visualization package

Functions for visualisations, especially of the ConvNets.

Submodules

braindecode.visualization.input_windows module

braindecode.visualization.input_windows.calc_Hout(Hin, kernel, stride, dilation)[source]
braindecode.visualization.input_windows.calc_Hin(Hout, kernel, stride, dilation)[source]
braindecode.visualization.input_windows.calc_receptive_field_size(model, layer_ind, start_receptive_field=array([1., 1.]))[source]

Calculate receptive field size for unit in specific layer of the network Only tested for 2d convolutions/poolings. Dimshuffle operations may lead to a wrong result

Parameters:
  • model (model object) – Network model
  • layer_ind (int) – Index of the layer of interest in model.children()
  • start_receptive_field (int, optional) – How many units are looked at in specified layer (default: [1,1])
Returns:

receptive_field_size – [HxW] in the input layer
Return type:

numpy array
braindecode.visualization.input_windows.get_max_act_index(activations, unique_per_input=True, n_units=None)[source]

Retrieve index of maximum activation in a feature map

Parameters:
  • activations (numpy array) – [Nx1xHxW] can only take 1 filter
  • unique_per_input (bool, optional) – Specifies if only 1 index (maximum) for each input is returned (default: True)
  • n_units (int, optional) – How many indeces are returned in total. If None all (default: None)
Returns:

  • units (numpy array) – [Nx4] with the columns Input_i,`Filter(0)`,`H_i`,`W_i` indeces of the units
  • units_activation (numpy array) – Activation of the units
braindecode.visualization.input_windows.calc_receptive_field_for_units_2d(units, receptive_field_size)[source]
braindecode.visualization.input_windows.get_input_windows_from_units_2d(inputs, units, receptive_field_size)[source]

Cut input windows in receptive field of specified units from inputs

Parameters:
  • inputs (numpy array) – [NxCxHxW] Inputs x Channels x Time x W
  • units (numpy array) – [Mx4] unit indeces specifying Input and time indeces. Second dimension consists of Input x Filter(1) x H x W indeces. Can only handle 1 filter.
  • receptive_field_size (int) – Size of receptive field of units on input
Returns:

windows – Cut input windows
Return type:

numpy array
braindecode.visualization.input_windows.most_activating_input_windows(inputs, activations, receptive_field_size, top_percentage=0.05)[source]

Get the input windows that evoked highest activation in a feature map

Parameters:
  • inputs (numpy array) – [NxCxTx1] Inputs used for the calculation of activations
  • activations (numpy array) – [NxFxHx1] Activations
  • receptive_field_size (numpy array) – [Wx1] Receptive field of a unit of the layer on the input
  • top_percentage (float, optional) – How many of the most activating input windows should be returned (default: top 5%)
Returns:

input_windows – [FxUxCxWx1] Returns U (resulting from top_percentage) input windows for each filter
Return type:

numpy array
braindecode.visualization.input_windows.activation_reverse_correlation(inputs, activations, receptive_field_size)[source]

Get reverse correlations for filters

Parameters:
  • inputs (numpy array) – [NxCxTx1] Inputs used for the calculation of activations
  • activations (numpy array) – [NxFxHx1] Activations
  • receptive_field_size (numpy array) – [Wx1] Receptive field of a unit of the layer on the input
Returns:

reverse_corr – [FxCxWx1] Reverse correlations over all input windows for each filter
Return type:

numpy array

braindecode.visualization.perturbation module

braindecode.visualization.perturbation.phase_perturbation(amps, phases, rng=None)[source]

Takes amps and phases of BxCxF with B input, C channels, F frequencies Shifts spectral phases randomly U(-pi,pi) for input and frequencies, but same for all channels

Parameters:
  • amps (numpy array) – Spectral amplitude (not used)
  • phases (numpy array) – Spectral phases
  • rng (object) – Random Generator
Returns:

  • amps (numpy array) – Input amps (not modified)
  • phases_pert (numpy array) – Shifted phases
  • pert_vals (numpy array) – Absolute phase shifts
braindecode.visualization.perturbation.amp_perturbation_additive(amps, phases, rng=None)[source]

Takes amplitudes and phases of BxCxF with B input, C channels, F frequencies Adds additive noise N(0,0.02) to amplitudes

Parameters:
  • amps (numpy array) – Spectral amplitude
  • phases (numpy array) – Spectral phases (not used)
  • rng (object) – Random Seed
Returns:

  • amps_pert (numpy array) – Scaled amplitudes
  • phases_pert (numpy array) – Input phases (not modified)
  • pert_vals (numpy array) – Amplitude noise
braindecode.visualization.perturbation.amp_perturbation_multiplicative(amps, phases, rng=None)[source]

Takes amplitude and phases of BxCxF with B input, C channels, F frequencies Adds multiplicative noise N(1,0.02) to amplitudes

Parameters:
  • amps (numpy array) – Spectral amplitude
  • phases (numpy array) – Spectral phases (not used)
  • rng (object) – Random Seed
Returns:

  • amps_pert (numpy array) – Scaled amplitudes
  • phases_pert (numpy array) – Input phases (not modified)
  • pert_vals (numpy array) – Amplitude scaling factor
braindecode.visualization.perturbation.correlate_feature_maps(x, y)[source]

Takes two activation matrices of the form Bx[F]xT where B is batch size, F number of filters (optional) and T time points Returns correlations of the corresponding activations over T

Parameters:
  • x (numpy array) – Activations Bx[F]xT
  • y (numpy array) – Activations Bx[F]xT
  • Returns
  • correlations (numpy array) – Correlations of x and y Bx[F]
braindecode.visualization.perturbation.mean_diff_feature_maps(x, y)[source]

Takes two activation matrices of the form BxFxT where B is batch size, F number of filters and T time points Returns mean difference between feature map activations

Parameters:
  • x (numpy array) – Activations Bx[F]xT
  • y (numpy array) – Activations Bx[F]xT
  • Returns
  • mean_diff (numpy array) – Mean difference between x and y Bx[F]
braindecode.visualization.perturbation.spectral_perturbation_correlation(pert_fn, diff_fn, pred_fn, n_layers, inputs, n_iterations, batch_size=30, seed=(2017, 7, 10))[source]

Calculates perturbation correlations for layers in network by perturbing either amplitudes or phases

Parameters:
  • pert_fn (function) – Function that perturbs spectral phase and amplitudes of inputs
  • diff_fn (function) – Function that calculates difference between original and perturbed activations
  • pred_fn (function) – Function that returns a list of activations. Each entry in the list corresponds to the output of 1 layer in a network
  • n_layers (int) – Number of layers pred_fn returns activations for.
  • inputs (numpy array) – Original inputs that are used for perturbation [B,X,T,1] Phase perturbations are sampled for each input individually, but applied to all X of that input
  • n_iterations (int) – Number of iterations of correlation computation. The higher the better
  • batch_size (int) – Number of inputs that are used for one forward pass. (Concatenated for all inputs)
Returns:

pert_corrs – List of length n_layers containing average perturbation correlations over iterations L x CxFrxFi (Channels,Frequencies,Filters)
Return type:

numpy array
braindecode.visualization.perturbation.compute_amplitude_prediction_correlations(pred_fn, examples, n_iterations, perturb_fn=<function amp_perturbation_additive>, batch_size=30, seed=(2017, 7, 10))[source]

Perturb input amplitudes and compute correlation between amplitude perturbations and prediction changes when pushing perturbed input through the prediction function.

For more details, see [EEGDeepLearning].

Parameters:
  • pred_fn (function) – Function accepting an numpy input and returning prediction.
  • examples (ndarray) – Numpy examples, first axis should be example axis.
  • n_iterations (int) – Number of iterations to compute.
  • perturb_fn (function, optional) – Function accepting amplitude array and random generator and returning perturbation. Default is Gaussian perturbation.
  • batch_size (int, optional) – Batch size for computing predictions.
  • seed (int, optional) – Random generator seed
Returns:

amplitude_pred_corrs – Correlations between amplitude perturbations and prediction changes for all sensors and frequency bins.
Return type:

ndarray

References

[EEGDeepLearning]Schirrmeister, R. T., Springenberg, J. T., Fiederer, L. D. J., Glasstetter, M., Eggensperger, K., Tangermann, M., Hutter, F. & Ball, T. (2017). Deep learning with convolutional neural networks for EEG decoding and visualization. Human Brain Mapping , Aug. 2017. Online: http://dx.doi.org/10.1002/hbm.23730

braindecode.visualization.plot module

braindecode.visualization.plot.ax_scalp(v, channels, ax=None, annotate=False, vmin=None, vmax=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, scalp_line_width=1, scalp_line_style='solid', chan_pos_list=('angle', ('Fpz', (0.0, 4.0)), ('Fp1', (-3.5, 3.5)), ('Fp2', (3.5, 3.5)), ('AFp3h', (-1.0, 3.5)), ('AFp4h', (1.0, 3.5)), ('AF7', (-4.0, 3.0)), ('AF3', (-2.0, 3.0)), ('AFz', (0.0, 3.0)), ('AF4', (2.0, 3.0)), ('AF8', (4.0, 3.0)), ('AFF5h', (-2.5, 2.5)), ('AFF1', (-0.5, 2.5)), ('AFF2', (0.5, 2.5)), ('AFF6h', (2.5, 2.5)), ('F7', (-4.0, 2.0)), ('F5', (-3.0, 2.0)), ('F3', (-2.0, 2.0)), ('F1', (-1.0, 2.0)), ('Fz', (0.0, 2.0)), ('F2', (1.0, 2.0)), ('F4', (2.0, 2.0)), ('F6', (3.0, 2.0)), ('F8', (4.0, 2.0)), ('FFT7h', (-3.5, 1.5)), ('FFC5h', (-2.5, 1.5)), ('FFC3h', (-1.5, 1.5)), ('FFC1h', (-0.5, 1.5)), ('FFC2h', (0.5, 1.5)), ('FFC4h', (1.5, 1.5)), ('FFC6h', (2.5, 1.5)), ('FFT8h', (3.5, 1.5)), ('FT9', (-5.0, 1.0)), ('FT7', (-4.0, 1.0)), ('FC5', (-3.0, 1.0)), ('FC3', (-2.0, 1.0)), ('FC1', (-1.0, 1.0)), ('FCz', (0.0, 1.0)), ('FC2', (1.0, 1.0)), ('FC4', (2.0, 1.0)), ('FC6', (3.0, 1.0)), ('FT8', (4.0, 1.0)), ('FT10', (5.0, 1.0)), ('FTT9h', (-4.5, 0.5)), ('FTT7h', (-3.5, 0.5)), ('FCC5h', (-2.5, 0.5)), ('FCC3h', (-1.5, 0.5)), ('FCC1h', (-0.5, 0.5)), ('FCC2h', (0.5, 0.5)), ('FCC4h', (1.5, 0.5)), ('FCC6h', (2.5, 0.5)), ('FTT8h', (3.5, 0.5)), ('FTT10h', (4.5, 0.5)), ('M1', (-5.0, 0.0)), ('T9', (-4.5, 0.0)), ('T7', (-4.0, 0.0)), ('C5', (-3.0, 0.0)), ('C3', (-2.0, 0.0)), ('C1', (-1.0, 0.0)), ('Cz', (0.0, 0.0)), ('C2', (1.0, 0.0)), ('C4', (2.0, 0.0)), ('C6', (3.0, 0.0)), ('T8', (4.0, 0.0)), ('T10', (4.5, 0.0)), ('M2', (5.0, 0.0)), ('TTP7h', (-3.5, -0.5)), ('CCP5h', (-2.5, -0.5)), ('CCP3h', (-1.5, -0.5)), ('CCP1h', (-0.5, -0.5)), ('CCP2h', (0.5, -0.5)), ('CCP4h', (1.5, -0.5)), ('CCP6h', (2.5, -0.5)), ('TTP8h', (3.5, -0.5)), ('TP7', (-4.0, -1.0)), ('CP5', (-3.0, -1.0)), ('CP3', (-2.0, -1.0)), ('CP1', (-1.0, -1.0)), ('CPz', (0.0, -1.0)), ('CP2', (1.0, -1.0)), ('CP4', (2.0, -1.0)), ('CP6', (3.0, -1.0)), ('TP8', (4.0, -1.0)), ('TPP9h', (-4.5, -1.5)), ('TPP7h', (-3.5, -1.5)), ('CPP5h', (-2.5, -1.5)), ('CPP3h', (-1.5, -1.5)), ('CPP1h', (-0.5, -1.5)), ('CPP2h', (0.5, -1.5)), ('CPP4h', (1.5, -1.5)), ('CPP6h', (2.5, -1.5)), ('TPP8h', (3.5, -1.5)), ('TPP10h', (4.5, -1.5)), ('P9', (-5.0, -2.0)), ('P7', (-4.0, -2.0)), ('P5', (-3.0, -2.0)), ('P3', (-2.0, -2.0)), ('P1', (-1.0, -2.0)), ('Pz', (0.0, -2.0)), ('P2', (1.0, -2.0)), ('P4', (2.0, -2.0)), ('P6', (3.0, -2.0)), ('P8', (4.0, -2.0)), ('P10', (5.0, -2.0)), ('PPO9h', (-4.5, -2.5)), ('PPO5h', (-3.0, -2.5)), ('PPO1', (-0.65, -2.5)), ('PPO2', (0.65, -2.5)), ('PPO6h', (3.0, -2.5)), ('PPO10h', (4.5, -2.5)), ('PO9', (-5.0, -3.0)), ('PO7', (-4.0, -3.0)), ('PO5', (-3.0, -3.0)), ('PO3', (-2.0, -3.0)), ('PO1', (-1.0, -3.0)), ('POz', (0.0, -3.0)), ('PO2', (1.0, -3.0)), ('PO4', (2.0, -3.0)), ('PO6', (3.0, -3.0)), ('PO8', (4.0, -3.0)), ('PO10', (5.0, -3.0)), ('POO9h', (-4.5, -3.25)), ('POO3h', (-2.0, -3.25)), ('POO4h', (2.0, -3.25)), ('POO10h', (4.5, -3.25)), ('O1', (-2.5, -3.75)), ('Oz', (0.0, -3.75)), ('O2', (2.5, -3.75)), ('OI1h', (1.5, -4.25)), ('OI2h', (-1.5, -4.25)), ('I1', (1.0, -4.5)), ('Iz', (0.0, -4.5)), ('I2', (-1.0, -4.5))), interpolation='bilinear', fontsize=8)[source]

Draw a scalp plot.

Draws a scalp plot on an existing axes. The method takes an array of values and an array of the corresponding channel names. It matches the channel names with an channel position list to project them correctly on the scalp.

Parameters:
  • v (1d-array of floats) – The values for the channels
  • channels (1d array of strings) – The corresponding channel names for the values in v
  • ax (Axes, optional) – The axes to draw the scalp plot on. If not provided, the currently activated axes (i.e. gca()) will be taken
  • annotate (Boolean, optional) – Draw the channel names next to the channel markers.
  • vmin, vmax (float, optional) – The display limits for the values in v. If the data in v contains values between -3..3 and vmin and vmax are set to -1 and 1, all values smaller than -1 and bigger than 1 will appear the same as -1 and 1. If not set, the maximum absolute value in v is taken to calculate both values.
  • cmap (matplotlib.colors.colormap, optional) – A colormap to define the color transitions.
  • scalp_line_width (float) – Line width for outline of scalp
  • scalp_line_style (float) – Line style for outline of scalp
  • chan_pos_list (iterable of tuples) – First entry should be ‘angle’ or ‘cartesian’, remaining entries 2-tuples of x and y.
  • interpolation (str)
Returns:

ax – the axes on which the plot was drawn
Return type:

Axes

Notes

Code adapted from Wyrm [1] toolbox https://github.com/bbci/wyrm.

References

[1]Schirrmeister, R. T., Springenberg, J. T., Fiederer, L. D. J., Glasstetter, M., Eggensperger, K., Tangermann, M., Hutter, F. & Ball, T. (2017). Deep learning with convolutional neural networks for EEG decoding and visualization. Human Brain Mapping , Aug. 2017. Online: http://dx.doi.org/10.1002/hbm.23730

braindecode.visualization.sinfit module

braindecode.visualization.sinfit.err_fn_sin(p, x, y)[source]
braindecode.visualization.sinfit.err_fn_lin(p, x, y)[source]
braindecode.visualization.sinfit.fit_fn_lin(x, *kwargs)[source]
braindecode.visualization.sinfit.fit_fn_sin(x, *kwargs)[source]
braindecode.visualization.sinfit.signal_fit(signals, fs)[source]

Fits sinusoid and linear function to signals see sinfit.fit_fn_sin and sinfit.fit_fn_lin

Parameters:
  • signals (numpy array) – [FxCxTx1] Filters x Channels x Time x 1
  • fs (float) – Sampling frequency
Returns:

  • params_sin (numpy array) – [FxCx4] Parameters of sinusoid fit Parameters are: Frequency,Amplitude,Phase,DCOffset
  • params_lin (numpy array) – [FxCx2] Parameters of sinusoid fit Parameters are: Frequency,Amplitude,Phase,DCOffset
  • err_sin (numpy array) – [FxCx1] MSE for sinusoid fit
  • err_lin (numpy array) – [FxCx1] MSE for linear fit