braindecode 0.3.2__tar.gz → 0.4.0__tar.gz

{Braindecode-0.3.2 → Braindecode-0.4.0}/Braindecode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: Braindecode
-Version: 0.3.2
+Version: 0.4.0
 Summary: A deep learning toolbox to decode raw time-domain EEG.
 Home-page: https://github.com/robintibor/braindecode
 Author: Robin Tibor Schirrmeister

{Braindecode-0.3.2 → Braindecode-0.4.0}/Braindecode.egg-info/SOURCES.txt

@@ -25,13 +25,16 @@ braindecode/datautil/trial_segment.py
 braindecode/datautil/util.py
 braindecode/experiments/__init__.py
 braindecode/experiments/experiment.py
+braindecode/experiments/loggers.py
 braindecode/experiments/monitors.py
 braindecode/experiments/stopcriteria.py
 braindecode/mne_ext/__init__.py
 braindecode/mne_ext/signalproc.py
 braindecode/models/__init__.py
+braindecode/models/base.py
 braindecode/models/deep4.py
 braindecode/models/eegnet.py
+braindecode/models/hybrid.py
 braindecode/models/shallow_fbcsp.py
 braindecode/models/util.py
 braindecode/torch_ext/__init__.py
@@ -40,6 +43,8 @@ braindecode/torch_ext/functions.py
 braindecode/torch_ext/init.py
 braindecode/torch_ext/losses.py
 braindecode/torch_ext/modules.py
+braindecode/torch_ext/optimizers.py
+braindecode/torch_ext/schedulers.py
 braindecode/torch_ext/util.py
 braindecode/visualization/__init__.py
 braindecode/visualization/input_windows.py
@@ -53,9 +58,12 @@ docs/notebooks/BBCI_Data.ipynb
 docs/notebooks/BBCI_Data_Start_Stop.ipynb
 docs/notebooks/BBCI_Data_Trialwise.ipynb
 docs/notebooks/Cropped_Decoding.ipynb
-docs/notebooks/Experiment_Class.ipynb
-docs/notebooks/TrialWise_Decoding.ipynb
+docs/notebooks/Cropped_Manual_Training_Loop.ipynb
+docs/notebooks/Cropped_Trialwise_Explanation_Figures.ipynb
+docs/notebooks/Trialwise_Decoding.ipynb
+docs/notebooks/Trialwise_Manual_Training_Loop.ipynb
 docs/notebooks/visualization/Perturbation.ipynb
+docs/notebooks/visualization/Perturbation_Old.ipynb
 docs/source/braindecode.datasets.rst
 docs/source/braindecode.datautil.rst
 docs/source/braindecode.experiments.rst

{Braindecode-0.3.2 → Braindecode-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: Braindecode
-Version: 0.3.2
+Version: 0.4.0
 Summary: A deep learning toolbox to decode raw time-domain EEG.
 Home-page: https://github.com/robintibor/braindecode
 Author: Robin Tibor Schirrmeister

{Braindecode-0.3.2 → Braindecode-0.4.0}/braindecode/datautil/iterators.py

@@ -15,7 +15,6 @@ def get_balanced_batches(n_trials, rng, shuffle, n_batches=None,
     n_trials : int
         Size of set.
     rng : RandomState
-
     shuffle : bool
         Whether to shuffle indices before splitting set.
     n_batches : int, optional
@@ -64,10 +63,14 @@ class BalancedBatchSizeIterator(object):
         Resulting batches will not necessarily have the given batch size
         but rather the next largest batch size that allows to split the set into
         balanced batches (maximum size difference 1).
+    seed: int
+        Random seed for initialization of `numpy.RandomState` random generator
+        that shuffles the batches.
     """
-    def __init__(self, batch_size):
+    def __init__(self, batch_size, seed=328774):
         self.batch_size = batch_size
-        self.rng = RandomState(328774)
+        self.seed = seed
+        self.rng = RandomState(self.seed)
 
     def get_batches(self, dataset, shuffle):
         n_trials = dataset.X.shape[0]
@@ -85,7 +88,7 @@ class BalancedBatchSizeIterator(object):
             yield (batch_X, batch_y)
 
     def reset_rng(self):
-        self.rng = RandomState(328774)
+        self.rng = RandomState(self.seed)
 
 
 class ClassBalancedBatchSizeIterator(object):
@@ -100,11 +103,15 @@ class ClassBalancedBatchSizeIterator(object):
         Resulting batches will not necessarily have the given batch size
         but rather the next largest batch size that allows to split the set into
         balanced batches (maximum size difference 1).
+    seed: int
+        Random seed for initialization of `numpy.RandomState` random generator
+        that shuffles the batches.
     """
 
-    def __init__(self, batch_size):
+    def __init__(self, batch_size, seed=328774):
         self.batch_size = batch_size
-        self.rng = RandomState(328774)
+        self.seed = seed
+        self.rng = RandomState(self.seed)
 
     def get_batches(self, dataset, shuffle):
         n_trials = dataset.X.shape[0]
@@ -138,7 +145,7 @@ class ClassBalancedBatchSizeIterator(object):
             yield (batch_X, batch_y)
 
     def reset_rng(self):
-        self.rng = RandomState((4, 7, 2017))
+        self.rng = RandomState(self.seed)
 
 
 class CropsFromTrialsIterator(object):
@@ -149,7 +156,7 @@ class CropsFromTrialsIterator(object):
     Predicting the given input batches can lead to some samples
     being predicted multiple times, if the receptive field size
     (input_time_length - n_preds_per_input + 1) is not a divisor
-    of the trial length.  :func:`compute_preds_per_trial_for_set`
+    of the trial length.  :func:`compute_preds_per_trial_from_crops`
     can help with removing the overlapped predictions again for evaluation.
 
     Parameters
@@ -163,11 +170,12 @@ class CropsFromTrialsIterator(object):
         by making a forward pass with the given input time length, the
         output length in 3rd dimension is n_preds_per_input.
     seed: int
-        Random seed for initialization of `numpy.RandomState`.
+        Random seed for initialization of `numpy.RandomState` random generator
+        that shuffles the batches.
     
     See Also
     --------
-    braindecode.experiments.monitors.compute_preds_per_trial_for_set : Assigns predictions to trials, removes overlaps.
+    braindecode.experiments.monitors.compute_preds_per_trial_from_crops : Assigns predictions to trials, removes overlaps.
     """
     def __init__(self, batch_size, input_time_length, n_preds_per_input,
                  seed=(2017, 6, 28)):

{Braindecode-0.3.2 → Braindecode-0.4.0}/braindecode/experiments/experiment.py

@@ -7,6 +7,7 @@ import pandas as pd
 import torch as th
 
 from braindecode.datautil.splitters import concatenate_sets
+from braindecode.experiments.loggers import Printer
 from braindecode.experiments.stopcriteria import MaxEpochs, ColumnBelow, Or
 from braindecode.torch_ext.util import np_to_var, set_random_seeds
 
@@ -109,7 +110,7 @@ class Experiment(object):
         (predictions: `torch.autograd.Variable`, 
         targets:`torch.autograd.Variable`)
         -> loss: `torch.autograd.Variable`
-    optimizer: torch.optim.Optimizer`
+    optimizer: `torch.optim.Optimizer`
     model_constraint: object
         Object with apply function that takes model and constraints its 
         parameters. `None` for no constraint.
@@ -137,6 +138,16 @@ class Experiment(object):
     do_early_stop: bool
         Whether to do an early stop at all. If true, reset to best model
         even in case experiment does not run after early stop.
+    reset_after_second_run: bool
+        If true, reset to best model when second run did not find a valid loss
+        below or equal to the best train loss of first run.
+    log_0_epoch: bool
+        Whether to compute monitor values and log them before the
+        start of training.
+    loggers: list of :class:`.Logger`
+        How to show computed metrics.
+    seed: int
+        Random seed for python random module numpy.random and torch.
         
     Attributes
     ----------
@@ -149,10 +160,14 @@ class Experiment(object):
                  run_after_early_stop,
                  model_loss_function=None,
                  batch_modifier=None, cuda=True, pin_memory=False,
-                 do_early_stop=True):
-        if run_after_early_stop:
-            assert do_early_stop == True, ("Can only run after early stop if "
-            "doing an early stop")
+                 do_early_stop=True,
+                 reset_after_second_run=False,
+                 log_0_epoch=True,
+                 loggers=('print',),
+                 seed=2382938):
+        if run_after_early_stop or reset_after_second_run:
+            assert do_early_stop == True, ("Can only run after early stop or "
+            "reset after second run if doing an early stop")
         if do_early_stop:
             assert valid_set is not None
             assert remember_best_column is not None
@@ -163,6 +178,9 @@ class Experiment(object):
             self.datasets.pop('valid')
             assert run_after_early_stop == False
             assert do_early_stop == False
+        if test_set is None:
+            self.datasets.pop('test')
+
         self.iterator = iterator
         self.loss_function = loss_function
         self.optimizer = optimizer
@@ -179,7 +197,10 @@ class Experiment(object):
         self.rememberer = None
         self.pin_memory = pin_memory
         self.do_early_stop = do_early_stop
-
+        self.reset_after_second_run = reset_after_second_run
+        self.log_0_epoch = log_0_epoch
+        self.seed = seed
+        self.loggers = loggers
 
     def run(self):
         """
@@ -195,7 +216,17 @@ class Experiment(object):
             self.setup_after_stop_training()
         if self.run_after_early_stop:
             log.info("Run until second stop...")
+            loss_to_reach = float(self.epochs_df['train_loss'].iloc[-1])
             self.run_until_second_stop()
+            if self.reset_after_second_run:
+                # if no valid loss was found below the best train loss on 1st
+                # run, reset model to the epoch with lowest valid_misclass
+                if float(self.epochs_df['valid_loss'].iloc[-1]) > loss_to_reach:
+                    log.info("Resetting to best epoch {:d}".format(
+                        self.rememberer.best_epoch))
+                    self.rememberer.reset_to_best_model(self.epochs_df,
+                                                        self.model,
+                                                        self.optimizer)
 
     def setup_training(self):
         """
@@ -205,8 +236,10 @@ class Experiment(object):
         # reset remember best extension in case you rerun some experiment
         if self.do_early_stop:
             self.rememberer = RememberBest(self.remember_best_column)
+        if self.loggers == ('print',):
+            self.loggers = [Printer()]
         self.epochs_df = pd.DataFrame()
-        set_random_seeds(seed=2382938, cuda=self.cuda)
+        set_random_seeds(seed=self.seed, cuda=self.cuda)
         if self.cuda:
             assert th.cuda.is_available(), "Cuda not available"
             self.model.cuda()
@@ -231,9 +264,7 @@ class Experiment(object):
         datasets['train'] = concatenate_sets([datasets['train'],
                                              datasets['valid']])
 
-        # Todo: actually keep remembering and in case of twice number of epochs
-        # reset to best model again (check if valid loss not below train loss)
-        self.run_until_stop(datasets, remember_best=False)
+        self.run_until_stop(datasets, remember_best=True)
 
     def run_until_stop(self, datasets, remember_best):
         """
@@ -248,11 +279,12 @@ class Experiment(object):
         remember_best: bool
             Whether to remember parameters at best epoch.
         """
-        self.monitor_epoch(datasets)
-        self.print_epoch()
-        if remember_best:
-            self.rememberer.remember_epoch(self.epochs_df, self.model,
-                                           self.optimizer)
+        if self.log_0_epoch:
+            self.monitor_epoch(datasets)
+            self.log_epoch()
+            if remember_best:
+                self.rememberer.remember_epoch(self.epochs_df, self.model,
+                                               self.optimizer)
 
         self.iterator.reset_rng()
         while not self.stop_criterion.should_stop(self.epochs_df):
@@ -285,7 +317,7 @@ class Experiment(object):
             end_train_epoch_time - start_train_epoch_time))
 
         self.monitor_epoch(datasets)
-        self.print_epoch()
+        self.log_epoch()
         if remember_best:
             self.rememberer.remember_epoch(self.epochs_df, self.model,
                                            self.optimizer)
@@ -331,21 +363,20 @@ class Experiment(object):
 
         """
         self.model.eval()
-        input_vars = np_to_var(inputs, pin_memory=self.pin_memory,
-                               volatile=True)
-        target_vars = np_to_var(targets, pin_memory=self.pin_memory,
-                                volatile=True)
-        if self.cuda:
-            input_vars = input_vars.cuda()
-            target_vars = target_vars.cuda()
-        outputs = self.model(input_vars)
-        loss = self.loss_function(outputs, target_vars)
-        if hasattr(outputs, 'cpu'):
-            outputs = outputs.cpu().data.numpy()
-        else:
-            # assume it is iterable
-            outputs = [o.cpu().data.numpy() for o in outputs]
-        loss = loss.cpu().data.numpy()
+        with th.no_grad():
+            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()
+            outputs = self.model(input_vars)
+            loss = self.loss_function(outputs, target_vars)
+            if hasattr(outputs, 'cpu'):
+                outputs = outputs.cpu().data.numpy()
+            else:
+                # assume it is iterable
+                outputs = [o.cpu().data.numpy() for o in outputs]
+            loss = loss.cpu().data.numpy()
         return outputs, loss
 
     def monitor_epoch(self, datasets):
@@ -395,17 +426,12 @@ class Experiment(object):
         assert set(self.epochs_df.columns) == set(row_dict.keys())
         self.epochs_df = self.epochs_df[list(row_dict.keys())]
 
-    def print_epoch(self):
+    def log_epoch(self):
         """
         Print monitoring values for this epoch.
         """
-        # -1 due to doing one monitor at start of training
-        i_epoch = len(self.epochs_df) - 1
-        log.info("Epoch {:d}".format(i_epoch))
-        last_row = self.epochs_df.iloc[-1]
-        for key, val in last_row.iteritems():
-            log.info("{:25s} {:.5f}".format(key, val))
-        log.info("")
+        for logger in self.loggers:
+            logger.log_epoch(self.epochs_df)
 
     def setup_after_stop_training(self):
         """

Braindecode-0.4.0/braindecode/experiments/loggers.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+import logging
+
+log = logging.getLogger(__name__)
+
+
+class Logger(ABC):
+    @abstractmethod
+    def log_epoch(self, epochs_df):
+        raise NotImplementedError("Need to implement the log_epoch function!")
+
+
+class Printer(Logger):
+    """
+    Prints output to the terminal using Python's logging module.
+    """
+    def log_epoch(self, epochs_df):
+        # -1 due to doing one monitor at start of training
+        i_epoch = len(epochs_df) - 1
+        log.info("Epoch {:d}".format(i_epoch))
+        last_row = epochs_df.iloc[-1]
+        for key, val in last_row.iteritems():
+            log.info("{:25s} {:.5f}".format(key, val))
+        log.info("")
+
+
+class TensorboardWriter(Logger):
+
+    """
+    Logs all values for tensorboard visualiuzation using tensorboardX.
+            
+    Parameters
+    ----------
+    log_dir: string
+        Directory path to log the output to
+    """
+    def __init__(self, log_dir):
+        # import inside to prevent dependency of braindecode onto tensorboardX
+        from tensorboardX import SummaryWriter
+        self.writer = SummaryWriter(log_dir)
+
+    def log_epoch(self, epochs_df):
+        # -1 due to doing one monitor at start of training
+        i_epoch = len(epochs_df) - 1
+        last_row = epochs_df.iloc[-1]
+        for key, val in last_row.iteritems():
+            val = last_row[key]
+            self.writer.add_scalar(key, val, i_epoch)

{Braindecode-0.3.2 → Braindecode-0.4.0}/braindecode/experiments/monitors.py

@@ -70,6 +70,34 @@ class MisclassMonitor(object):
         return {column_name: float(misclass)}
 
 
+def compute_pred_labels_from_trial_preds(
+        all_preds, threshold_for_binary_case=None):
+    all_pred_labels = []
+    for i_batch in range(len(all_preds)):
+        preds = all_preds[i_batch]
+        # preds could be examples x classes x time
+        # or just
+        # examples x classes
+        # make sure not to remove first dimension if it only has size one
+        if preds.ndim > 1:
+            only_one_row = preds.shape[0] == 1
+
+            pred_labels = np.argmax(preds, axis=1).squeeze()
+            # add first dimension again if needed
+            if only_one_row:
+                pred_labels = pred_labels[None]
+        else:
+            assert threshold_for_binary_case is not None, (
+                "In case of only one output, please supply the "
+                "threshold_for_binary_case parameter")
+            # binary classification case... assume logits
+            pred_labels = np.int32(preds > threshold_for_binary_case)
+        # now examples x time or examples
+        all_pred_labels.extend(pred_labels)
+    all_pred_labels = np.array(all_pred_labels)
+    return all_pred_labels
+
+
 class AveragePerClassMisclassMonitor(object):
     """
     Compute average of misclasses per class,
@@ -148,6 +176,7 @@ class LossMonitor(object):
         return {column_name: mean_loss}
 
 
+
 class CroppedTrialMisclassMonitor(object):
     """
     Compute trialwise misclasses from predictions for crops.
@@ -169,9 +198,10 @@ class CroppedTrialMisclassMonitor(object):
         assert self.input_time_length is not None, "Need to know input time length..."
         # First case that each trial only has a single label
         if not hasattr(dataset.y[0], '__len__'):
-            all_pred_labels = self._compute_pred_labels(dataset, all_preds)
-            all_trial_labels = dataset.y
+            all_pred_labels = compute_trial_labels_from_crop_preds(
+                all_preds, self.input_time_length, dataset.X)
             assert all_pred_labels.shape == dataset.y.shape
+            all_trial_labels = dataset.y
         else:
             all_trial_labels, all_pred_labels = (
                 self._compute_trial_pred_labels_from_cnt_y(dataset, all_preds))
@@ -181,8 +211,8 @@ class CroppedTrialMisclassMonitor(object):
         return {column_name: float(misclass)}
 
     def _compute_pred_labels(self, dataset, all_preds, ):
-        preds_per_trial = compute_preds_per_trial_for_set(
-            all_preds, self.input_time_length, dataset)
+        preds_per_trial = compute_preds_per_trial_from_crops(
+            all_preds, self.input_time_length, dataset.X)
         all_pred_labels = [np.argmax(np.mean(p, axis=1))
                            for p in preds_per_trial]
         all_pred_labels = np.array(all_pred_labels)
@@ -194,8 +224,8 @@ class CroppedTrialMisclassMonitor(object):
         # we only want the preds that are for the same labels as the last label in y
         # (there might be parts of other class-data at start, for trialwise misclass we assume
         # they are contained in other trials at the end...)
-        preds_per_trial = compute_preds_per_trial_for_set(
-            all_preds, self.input_time_length, dataset)
+        preds_per_trial = compute_preds_per_trial_from_crops(
+            all_preds, self.input_time_length, dataset.X)
         trial_labels = []
         trial_pred_labels = []
         for trial_pred, trial_y in zip(preds_per_trial, dataset.y):
@@ -217,8 +247,36 @@ class CroppedTrialMisclassMonitor(object):
         return trial_labels, trial_pred_labels
 
 
-def compute_preds_per_trial_for_set(all_preds, input_time_length,
-                                        dataset, ):
+def compute_trial_labels_from_crop_preds(all_preds, input_time_length, X):
+    """
+    Compute predicted trial labels from arrays of crop predictions
+
+    Parameters
+    ----------
+    all_preds: list of 2darrays (classes x time)
+        All predictions for the crops.
+    input_time_length: int
+        Temporal length of one input to the model.
+    X: ndarray
+        Input tensor the crops were taken from.
+
+    Returns
+    -------
+    pred_labels_per_trial: 1darray
+        Predicted label for each trial.
+
+    """
+
+    preds_per_trial = compute_preds_per_trial_from_crops(
+        all_preds, input_time_length, X)
+    pred_labels_per_trial = [np.argmax(np.mean(p, axis=1))
+                       for p in preds_per_trial]
+    pred_labels_per_trial = np.array(pred_labels_per_trial)
+    return pred_labels_per_trial
+
+
+def compute_preds_per_trial_from_crops(all_preds, input_time_length,
+                                        X, ):
     """
     Compute predictions per trial from predictions for crops.
     
@@ -228,8 +286,8 @@ def compute_preds_per_trial_for_set(all_preds, input_time_length,
         All predictions for the crops. 
     input_time_length: int
         Temporal length of one input to the model.
-    dataset: :class:`.SignalAndTarget`
-        Dataset the crops were taken from.
+    X: ndarray
+        Input tensor the crops were taken from.
     
     Returns
     -------
@@ -240,7 +298,7 @@ def compute_preds_per_trial_for_set(all_preds, input_time_length,
     n_preds_per_input = all_preds[0].shape[2]
     n_receptive_field = input_time_length - n_preds_per_input + 1
     n_preds_per_trial = [trial.shape[1] - n_receptive_field + 1
-                         for trial in dataset.X]
+                         for trial in X]
     preds_per_trial = compute_preds_per_trial_from_n_preds_per_trial(
         all_preds, n_preds_per_trial)
     return preds_per_trial

{Braindecode-0.3.2 → Braindecode-0.4.0}/braindecode/experiments/stopcriteria.py

@@ -27,10 +27,29 @@ class Or(object):
     """
     def __init__(self, stop_criteria):
         self.stop_criteria = stop_criteria
+        self.triggered = dict([(s, False) for s in stop_criteria])
 
     def should_stop(self, epochs_df):
-        return np.any([s.should_stop(epochs_df)
-                       for s in self.stop_criteria])
+        # Update dictionary of which criterion was triggered ...
+        for s in self.stop_criteria:
+            self.triggered[s] = s.should_stop(epochs_df)
+        # Then check if any of them was triggered.
+        return np.any(list(self.triggered.values()))
+
+    def was_triggered(self, criterion):
+        """
+        Return if given criterion was triggered in the last call to should stop.
+        
+        Parameters
+        ----------
+        criterion: stop criterion
+
+        Returns
+        -------
+        triggered: bool
+
+        """
+        return self.triggered[criterion]
 
 
 class And(object):
@@ -45,8 +64,26 @@ class And(object):
         self.stop_criteria = stop_criteria
 
     def should_stop(self, epochs_df):
-        return np.all([s.should_stop(epochs_df)
-                       for s in self.stop_criteria])
+        # Update dictionary of which criterion was triggered ...
+        for s in self.stop_criteria:
+            self.triggered[s] = s.should_stop(epochs_df)
+        # Then check if all of them were triggered.
+        return np.all(list(self.triggered.values()))
+
+    def was_triggered(self, criterion):
+        """
+        Return if given criterion was triggered in the last call to should stop.
+
+        Parameters
+        ----------
+        criterion: stop criterion
+
+        Returns
+        -------
+        triggered: bool
+
+        """
+        return self.triggered[criterion]
 
 
 class NoDecrease(object):