braindecode 0.1.6.4__tar.gz → 0.1.7__tar.gz

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/Braindecode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: Braindecode
-Version: 0.1.6.4
+Version: 0.1.7
 Summary: A deep learning toolbox to decode raw time-domain EEG.
 Home-page: https://github.com/robintibor/braindecode
 Author: Robin Tibor Schirrmeister
@@ -52,6 +52,28 @@ Description: Note: The old braindecode repository has been moved to
         
         Documentation is online under https://robintibor.github.io/braindecode/
         
+        
+        Citing
+        ======
+        If you use this code in a scientific publication, please cite us as:
+        
+        .. code-block:: bibtex
+        
+          @article {HBM:HBM23730,
+          author = {Schirrmeister, Robin Tibor and Springenberg, Jost Tobias and Fiederer,
+            Lukas Dominique Josef and Glasstetter, Martin and Eggensperger, Katharina and Tangermann, Michael and
+            Hutter, Frank and Burgard, Wolfram and Ball, Tonio},
+          title = {Deep learning with convolutional neural networks for EEG decoding and visualization},
+          journal = {Human Brain Mapping},
+          issn = {1097-0193},
+          url = {http://dx.doi.org/10.1002/hbm.23730},
+          doi = {10.1002/hbm.23730},
+          month = {aug},
+          year = {2017},
+          keywords = {electroencephalography, EEG analysis, machine learning, end-to-end learning, brain–machine interface, 
+            brain–computer interface, model interpretability, brain mapping},
+          }
+        
 Keywords: eeg deep-learning brain-state-decoding
 Platform: UNKNOWN
 Classifier: Development Status :: 3 - Alpha

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: Braindecode
-Version: 0.1.6.4
+Version: 0.1.7
 Summary: A deep learning toolbox to decode raw time-domain EEG.
 Home-page: https://github.com/robintibor/braindecode
 Author: Robin Tibor Schirrmeister
@@ -52,6 +52,28 @@ Description: Note: The old braindecode repository has been moved to
         
         Documentation is online under https://robintibor.github.io/braindecode/
         
+        
+        Citing
+        ======
+        If you use this code in a scientific publication, please cite us as:
+        
+        .. code-block:: bibtex
+        
+          @article {HBM:HBM23730,
+          author = {Schirrmeister, Robin Tibor and Springenberg, Jost Tobias and Fiederer,
+            Lukas Dominique Josef and Glasstetter, Martin and Eggensperger, Katharina and Tangermann, Michael and
+            Hutter, Frank and Burgard, Wolfram and Ball, Tonio},
+          title = {Deep learning with convolutional neural networks for EEG decoding and visualization},
+          journal = {Human Brain Mapping},
+          issn = {1097-0193},
+          url = {http://dx.doi.org/10.1002/hbm.23730},
+          doi = {10.1002/hbm.23730},
+          month = {aug},
+          year = {2017},
+          keywords = {electroencephalography, EEG analysis, machine learning, end-to-end learning, brain–machine interface, 
+            brain–computer interface, model interpretability, brain mapping},
+          }
+        
 Keywords: eeg deep-learning brain-state-decoding
 Platform: UNKNOWN
 Classifier: Development Status :: 3 - Alpha

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/README.rst

@@ -43,3 +43,25 @@ Documentation
 =============
 
 Documentation is online under https://robintibor.github.io/braindecode/
+
+
+Citing
+======
+If you use this code in a scientific publication, please cite us as:
+
+.. code-block:: bibtex
+
+  @article {HBM:HBM23730,
+  author = {Schirrmeister, Robin Tibor and Springenberg, Jost Tobias and Fiederer,
+    Lukas Dominique Josef and Glasstetter, Martin and Eggensperger, Katharina and Tangermann, Michael and
+    Hutter, Frank and Burgard, Wolfram and Ball, Tonio},
+  title = {Deep learning with convolutional neural networks for EEG decoding and visualization},
+  journal = {Human Brain Mapping},
+  issn = {1097-0193},
+  url = {http://dx.doi.org/10.1002/hbm.23730},
+  doi = {10.1002/hbm.23730},
+  month = {aug},
+  year = {2017},
+  keywords = {electroencephalography, EEG analysis, machine learning, end-to-end learning, brain–machine interface, 
+    brain–computer interface, model interpretability, brain mapping},
+  }

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/datautil/signalproc.py

@@ -3,6 +3,7 @@ import logging
 import pandas as pd
 import numpy as np
 import scipy
+import scipy.signal
 
 log = logging.getLogger(__name__)
 

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/experiments/experiment.py

@@ -1,6 +1,7 @@
 import logging
 from collections import OrderedDict
 from copy import deepcopy
+import time
 
 import pandas as pd
 import torch as th
@@ -131,6 +132,8 @@ class Experiment(object):
         augmentation
     cuda: bool, optional
         Whether to use cuda.
+    pin_memory: bool, optional
+        Whether to pin memory of inputs and targets of batch.
         
     Attributes
     ----------
@@ -142,7 +145,7 @@ class Experiment(object):
                  monitors, stop_criterion, remember_best_column,
                  run_after_early_stop,
                  model_loss_function=None,
-                 batch_modifier=None, cuda=True):
+                 batch_modifier=None, cuda=True, pin_memory=False):
         self.model = model
         self.datasets = OrderedDict(
             (('train', train_set), ('valid', valid_set), ('test', test_set)))
@@ -160,6 +163,7 @@ class Experiment(object):
         self.epochs_df = pd.DataFrame()
         self.before_stop_df = None
         self.rememberer = None
+        self.pin_memory = pin_memory
 
     def run(self):
         """
@@ -250,7 +254,7 @@ class Experiment(object):
         """
         batch_generator = self.iterator.get_batches(datasets['train'],
                                                     shuffle=True)
-        # TODO, add timing again?
+        start_train_epoch_time = time.time()
         for inputs, targets in batch_generator:
             if self.batch_modifier is not None:
                 inputs, targets = self.batch_modifier.process(inputs,
@@ -258,6 +262,9 @@ class Experiment(object):
             # could happen that batch modifier has removed all inputs...
             if len(inputs) > 0:
                 self.train_batch(inputs, targets)
+        end_train_epoch_time = time.time()
+        log.info("Time only for training updates: {:.2f}s".format(
+            end_train_epoch_time - start_train_epoch_time))
 
         self.monitor_epoch(datasets)
         self.print_epoch()
@@ -275,8 +282,8 @@ class Experiment(object):
         targets: `torch.autograd.Variable`
         """
         self.model.train()
-        input_vars = np_to_var(inputs)
-        target_vars = np_to_var(targets)
+        input_vars = np_to_var(inputs, pin_memory=self.pin_memory)
+        target_vars = np_to_var(targets, pin_memory=self.pin_memory)
         if self.cuda:
             input_vars = input_vars.cuda()
             target_vars = target_vars.cuda()
@@ -306,8 +313,8 @@ class Experiment(object):
 
         """
         self.model.eval()
-        input_vars = np_to_var(inputs)
-        target_vars = np_to_var(targets)
+        input_vars = np_to_var(inputs, pin_memory=self.pin_memory)
+        target_vars = np_to_var(targets, pin_memory=self.pin_memory)
         if self.cuda:
             input_vars = input_vars.cuda()
             target_vars = target_vars.cuda()

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/models/deep4.py

@@ -29,11 +29,11 @@ class Deep4Net(object):
                  filter_time_length=10,
                  pool_time_length=3,
                  pool_time_stride=3,
-                 num_filters_2=50,
+                 n_filters_2=50,
                  filter_length_2=10,
-                 num_filters_3=100,
+                 n_filters_3=100,
                  filter_length_3=10,
-                 num_filters_4=200,
+                 n_filters_4=200,
                  filter_length_4=10,
                  first_nonlin=elu,
                  first_pool_mode='max',
@@ -89,18 +89,18 @@ class Deep4Net(object):
                              stride=(self.pool_time_stride, 1)))
         model.add_module('pool_nonlin', Expression(self.first_pool_nonlin))
 
-        def add_conv_pool_block(model, num_filters_before,
-                                num_filters, filter_length, block_nr):
+        def add_conv_pool_block(model, n_filters_before,
+                                n_filters, filter_length, block_nr):
             suffix = '_{:d}'.format(block_nr)
             model.add_module('drop' + suffix,
                              nn.Dropout(p=self.drop_prob))
             model.add_module('conv' + suffix.format(block_nr),
-                             nn.Conv2d(num_filters_before, num_filters,
+                             nn.Conv2d(n_filters_before, n_filters,
                                        (filter_length, 1),
                                        stride=1, bias=not self.batch_norm))
             if self.batch_norm:
                 model.add_module('bnorm' + suffix,
-                             nn.BatchNorm2d(num_filters,
+                             nn.BatchNorm2d(n_filters,
                                             momentum=self.batch_norm_alpha,
                                             affine=True,
                                             eps=1e-5))
@@ -114,11 +114,11 @@ class Deep4Net(object):
             model.add_module('pool_nonlin' + suffix,
                              Expression(self.later_pool_nonlin))
 
-        add_conv_pool_block(model, n_filters_conv, self.num_filters_2,
+        add_conv_pool_block(model, n_filters_conv, self.n_filters_2,
                             self.filter_length_2, 2)
-        add_conv_pool_block(model, self.num_filters_2, self.num_filters_3,
+        add_conv_pool_block(model, self.n_filters_2, self.n_filters_3,
                             self.filter_length_3, 3)
-        add_conv_pool_block(model, self.num_filters_3, self.num_filters_4,
+        add_conv_pool_block(model, self.n_filters_3, self.n_filters_4,
                             self.filter_length_4, 4)
 
 
@@ -129,7 +129,7 @@ class Deep4Net(object):
             n_out_time = out.cpu().data.numpy().shape[2]
             self.final_conv_length = n_out_time
         model.add_module('conv_classifier',
-                             nn.Conv2d(self.num_filters_4, self.n_classes,
+                             nn.Conv2d(self.n_filters_4, self.n_classes,
                                        (self.final_conv_length, 1), bias=True))
         model.add_module('softmax', nn.LogSoftmax())
         # remove empty dim at end and potentially remove empty time dim

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/models/eegnet.py

@@ -56,13 +56,14 @@ class EEGNet(object):
         model.add_module('drop_1', nn.Dropout(p=self.drop_prob))
 
         n_filters_2 = 4
-        # not clear to me how they did the padding
-        # keras padds unequal padding more in front:
+        # keras padds unequal padding more in front, so padding
+        # too large should be ok.
+        # Not padding in time so that croped training makes sense
         # https://stackoverflow.com/questions/43994604/padding-with-even-kernel-size-in-a-convolutional-layer-in-keras-theano
 
         model.add_module('conv_2', nn.Conv2d(
             1, n_filters_2, self.second_kernel_size, stride=1,
-            padding=(self.second_kernel_size[0] // 2, self.second_kernel_size[1] // 2),
+            padding=(self.second_kernel_size[0] // 2, 0),
             bias=True))
         model.add_module('bnorm_2',nn.BatchNorm2d(
             n_filters_2, momentum=0.01, affine=True, eps=1e-3),)
@@ -74,7 +75,7 @@ class EEGNet(object):
         n_filters_3 = 4
         model.add_module('conv_3', nn.Conv2d(
             n_filters_2, n_filters_3, self.third_kernel_size, stride=1,
-            padding=(self.third_kernel_size[0] // 2, self.third_kernel_size[1] // 2),
+            padding=(self.third_kernel_size[0] // 2, 0),
             bias=True))
         model.add_module('bnorm_3',nn.BatchNorm2d(
             n_filters_3, momentum=0.01, affine=True, eps=1e-3),)

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/models/util.py

@@ -13,6 +13,12 @@ def to_dense_prediction_model(model, axis=(2, 3)):
     axis: int or (int,int)
         Axis to transform (in terms of intermediate output axes)
         can either be 2, 3, or (2,3).
+    
+    Notes
+    -----
+    Does not yet work correctly for average pooling.
+    Prior to version 0.1.7, there had been a bug that could move strides
+    backwards one layer.
 
     """
     if not hasattr(axis, '__len__'):
@@ -21,14 +27,6 @@ def to_dense_prediction_model(model, axis=(2, 3)):
     axis = np.array(axis) - 2
     stride_so_far = np.array([1, 1])
     for module in model.modules():
-        if hasattr(module, 'stride'):
-            if not hasattr(module.stride, '__len__'):
-                module.stride = (module.stride, module.stride)
-            stride_so_far *= np.array(module.stride)
-            new_stride = list(module.stride)
-            for ax in axis:
-                new_stride[ax] = 1
-            module.stride = tuple(new_stride)
         if hasattr(module, 'dilation'):
             assert module.dilation == 1 or (module.dilation == (1, 1)), (
                 "Dilation should equal 1 before conversion, maybe the model is "
@@ -37,3 +35,11 @@ def to_dense_prediction_model(model, axis=(2, 3)):
             for ax in axis:
                 new_dilation[ax] = int(stride_so_far[ax])
             module.dilation = tuple(new_dilation)
+        if hasattr(module, 'stride'):
+            if not hasattr(module.stride, '__len__'):
+                module.stride = (module.stride, module.stride)
+            stride_so_far *= np.array(module.stride)
+            new_stride = list(module.stride)
+            for ax in axis:
+                new_stride[ax] = 1
+            module.stride = tuple(new_stride)

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/torch_ext/util.py

@@ -4,18 +4,33 @@ import numpy as np
 import random
 
 
-def np_to_var(X, requires_grad=False, **var_kwargs):
+def np_to_var(X, requires_grad=False, dtype=None, pin_memory=False, **var_kwargs):
     """
     Convenience function to transform numpy array to `torch.autograd.Variable`.
         
     Converts `X` to ndarray using asarray if necessary.
     
+    Parameters
+    ----------
+    X: ndarray or list
+        Input arrays
+    requires_grad: bool
+        passed on to Variable constructor
+    dtype: numpy dtype, optional
+    var_kwargs:
+        passed on to Variable constructor
+    
     Returns
     -------
     var: `torch.autograd.Variable`
     """
     X = np.asarray(X)
-    return Variable(th.from_numpy(X), requires_grad=requires_grad, **var_kwargs)
+    if dtype is not None:
+        X = X.astype(dtype)
+    X_tensor = th.from_numpy(X)
+    if pin_memory:
+        X_tensor = X_tensor.pin_memory()
+    return Variable(X_tensor, requires_grad=requires_grad, **var_kwargs)
 
 
 def var_to_np(var):

Braindecode-0.1.7/braindecode/visualization/__init__.py

@@ -0,0 +1,3 @@
+"""
+Functions for visualisations, especially of the ConvNets.
+"""

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/visualization/perturbation.py

@@ -10,7 +10,22 @@ log = logging.getLogger(__name__)
 
 
 def gaussian_perturbation(amps, rng):
-    perturbation = rng.randn(*amps.shape)
+    """
+    Create gaussian noise tensor with same shape as amplitudes.
+
+    Parameters
+    ----------
+    amps: ndarray
+        Amplitudes.
+    rng: RandomState
+        Random generator.
+
+    Returns
+    -------
+    perturbation: ndarray
+        Perturbations to add to the amplitudes.
+    """
+    perturbation = rng.randn(*amps.shape).astype(np.float32)
     return perturbation
 
 
@@ -46,6 +61,15 @@ def compute_amplitude_prediction_correlations(pred_fn, examples, n_iterations,
     amplitude_pred_corrs: ndarray
         Correlations between amplitude perturbations and prediction changes
         for all sensors and frequency bins.
+
+    References
+    ----------
+
+    .. [EEGDeepLearning] Schirrmeister, R. T., Springenberg, J. T., Fiederer, L. D. J.,
+       Glasstetter, M., Eggensperger, K., Tangermann, M., ... & Ball, T. (2017).
+       Deep learning with convolutional neural networks for EEG decoding and
+       visualization.
+       arXiv preprint arXiv:1703.05051.
     """
     inds_per_batch = get_balanced_batches(
         n_trials=len(examples), rng=None, shuffle=False, batch_size=batch_size)
@@ -68,8 +92,8 @@ def compute_amplitude_prediction_correlations(pred_fn, examples, n_iterations,
         # zero
         perturbation = np.maximum(-amps, perturbation)
         new_amps = amps + perturbation
-        log.info("Compute new  complex inputs...")
-        new_complex = amplitude_phase_to_complex(new_amps, phases)
+        log.info("Compute new complex inputs...")
+        new_complex = _amplitude_phase_to_complex(new_amps, phases)
         log.info("Compute new real inputs...")
         new_in = np.fft.irfft(new_complex, axis=2).astype(np.float32)
         log.info("Compute new predictions...")
@@ -88,5 +112,5 @@ def compute_amplitude_prediction_correlations(pred_fn, examples, n_iterations,
     return amp_pred_corrs
 
 
-def amplitude_phase_to_complex(amplitude, phase):
+def _amplitude_phase_to_complex(amplitude, phase):
     return amplitude * np.cos(phase) + amplitude * np.sin(phase) * 1j

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/braindecode/visualization/plot.py

@@ -18,7 +18,8 @@ def ax_scalp(v, channels,
              scalp_line_width=1,
              scalp_line_style='solid',
              chan_pos_list=CHANNEL_10_20_APPROX,
-             interpolation='bilinear'):
+             interpolation='bilinear',
+             fontsize=8):
     """Draw a scalp plot.
 
     Draws a scalp plot on an existing axes. The method takes an array of
@@ -138,7 +139,7 @@ def ax_scalp(v, channels,
     if annotate:
         for i in zip(channels, list(zip(x, y))):
             ax.annotate(" " + i[0], i[1], horizontalalignment="center",
-                        verticalalignment='center')
+                        verticalalignment='center', fontsize=fontsize)
     ax.set_aspect(1)
     return image
 

{Braindecode-0.1.6.4 → Braindecode-0.1.7}/docs/index.rst

@@ -63,6 +63,30 @@ API
    braindecode.mne_ext
    braindecode.models
    braindecode.torch_ext
+   braindecode.visualization
+
+
+Citing
+======
+If you use this code in a scientific publication, please cite us as:
+
+.. code-block:: bibtex
+
+  @article {HBM:HBM23730,
+  author = {Schirrmeister, Robin Tibor and Springenberg, Jost Tobias and Fiederer,
+    Lukas Dominique Josef and Glasstetter, Martin and Eggensperger, Katharina and Tangermann, Michael and
+    Hutter, Frank and Burgard, Wolfram and Ball, Tonio},
+  title = {Deep learning with convolutional neural networks for EEG decoding and visualization},
+  journal = {Human Brain Mapping},
+  issn = {1097-0193},
+  url = {http://dx.doi.org/10.1002/hbm.23730},
+  doi = {10.1002/hbm.23730},
+  month = {aug},
+  year = {2017},
+  keywords = {electroencephalography, EEG analysis, machine learning, end-to-end learning, brain–machine interface,
+    brain–computer interface, model interpretability, brain mapping},
+  }
+
 
 Indices and tables
 ==================