braindecode 0.1.0__tar.gz → 0.1.2__tar.gz

{Braindecode-0.1.0 → Braindecode-0.1.2}/Braindecode.egg-info/PKG-INFO

@@ -1,16 +1,29 @@
 Metadata-Version: 1.1
 Name: Braindecode
-Version: 0.1.0
+Version: 0.1.2
 Summary: A deep learning for raw time-domain EEG decoding toolbox.
 Home-page: https://github.com/robintibor/braindecode
 Author: Robin Tibor Schirrmeister
 Author-email: robintibor@gmail.com
 License: BSD 3-Clause
-Description: Note: The old braindecode repository has been moved to https://github.com/robintibor/braindevel.
+Description: Note: The old braindecode repository has been moved to
+        https://github.com/robintibor/braindevel.
+        
+        Braindecode
+        ===========
         
-        # Braindecode
         A deep learning for raw time-domain EEG decoding toolbox.
         
+        Installation
+        ============
+        
+        Install pytorch from http://pytorch.org/.
+        
+        Documentation
+        =============
+        
+        Documentation is online under http://braindecode.readthedocs.io/
+        
 Keywords: eeg deep-learning brain-state-decoding
 Platform: UNKNOWN
 Classifier: Development Status :: 3 - Alpha

Braindecode-0.1.2/Braindecode.egg-info/SOURCES.txt

@@ -0,0 +1,39 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+setup.py
+Braindecode.egg-info/PKG-INFO
+Braindecode.egg-info/SOURCES.txt
+Braindecode.egg-info/dependency_links.txt
+Braindecode.egg-info/not-zip-safe
+Braindecode.egg-info/requires.txt
+Braindecode.egg-info/top_level.txt
+braindecode/__init__.py
+braindecode/iterators.py
+braindecode/splitters.py
+braindecode/trial_segment.py
+braindecode/util.py
+braindecode/datasets/__init__.py
+braindecode/datasets/signal_target.py
+braindecode/experiments/__init__.py
+braindecode/experiments/experiment.py
+braindecode/experiments/monitors.py
+braindecode/experiments/stopcriteria.py
+braindecode/models/__init__.py
+braindecode/models/shallow_fbcsp.py
+braindecode/torchext/__init__.py
+braindecode/torchext/constraints.py
+braindecode/torchext/functions.py
+braindecode/torchext/losses.py
+braindecode/torchext/modules.py
+braindecode/torchext/util.py
+docs/Makefile
+docs/conf.py
+docs/index.rst
+docs/notebooks/TrialWise_Decoding.ipynb
+docs/source/braindecode.datasets.rst
+docs/source/braindecode.experiments.rst
+docs/source/braindecode.models.rst
+docs/source/braindecode.rst
+docs/source/braindecode.torchext.rst
+docs/source/modules.rst

Braindecode-0.1.2/Braindecode.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

Braindecode-0.1.2/LICENSE.txt

@@ -0,0 +1,31 @@
+BSD 3-Clause License
+
+Copyright (c) 2017 Robin Tibor Schirrmeister
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A P
+ARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

Braindecode-0.1.2/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE.txt
+
+recursive-include docs *.ipynb *.rst conf.py Makefile
+recursive-exclude docs *checkpoint.ipynb

{Braindecode-0.1.0 → Braindecode-0.1.2}/PKG-INFO

@@ -1,16 +1,29 @@
 Metadata-Version: 1.1
 Name: Braindecode
-Version: 0.1.0
+Version: 0.1.2
 Summary: A deep learning for raw time-domain EEG decoding toolbox.
 Home-page: https://github.com/robintibor/braindecode
 Author: Robin Tibor Schirrmeister
 Author-email: robintibor@gmail.com
 License: BSD 3-Clause
-Description: Note: The old braindecode repository has been moved to https://github.com/robintibor/braindevel.
+Description: Note: The old braindecode repository has been moved to
+        https://github.com/robintibor/braindevel.
+        
+        Braindecode
+        ===========
         
-        # Braindecode
         A deep learning for raw time-domain EEG decoding toolbox.
         
+        Installation
+        ============
+        
+        Install pytorch from http://pytorch.org/.
+        
+        Documentation
+        =============
+        
+        Documentation is online under http://braindecode.readthedocs.io/
+        
 Keywords: eeg deep-learning brain-state-decoding
 Platform: UNKNOWN
 Classifier: Development Status :: 3 - Alpha

Braindecode-0.1.2/README.md

@@ -0,0 +1,17 @@
+Note: The old braindecode repository has been moved to
+https://github.com/robintibor/braindevel.
+
+Braindecode
+===========
+
+A deep learning for raw time-domain EEG decoding toolbox.
+
+Installation
+============
+
+Install pytorch from http://pytorch.org/.
+
+Documentation
+=============
+
+Documentation is online under http://braindecode.readthedocs.io/

Braindecode-0.1.2/braindecode/datasets/signal_target.py

@@ -0,0 +1,20 @@
+class SignalAndTarget(object):
+    def __init__(self, X, y):
+        assert len(X) == len(y)
+        self.X = X
+        self.y = y
+
+
+def apply_to_X_y(fn, *sets):
+    X = fn(*[s.X for s in sets])
+    y = fn(*[s.y for s in sets])
+    return SignalAndTarget(X,y)
+
+
+def split_into_two_sets(dataset, fraction=None, n_boundary=None):
+    assert fraction is not None or n_boundary is not None
+    if n_boundary is None:
+        n_boundary = int(round(len(dataset.X) * fraction))
+    first_set = apply_to_X_y(lambda a: a[:n_boundary], dataset)
+    second_set = apply_to_X_y(lambda a: a[n_boundary:], dataset)
+    return first_set, second_set

Braindecode-0.1.2/braindecode/experiments/experiment.py

@@ -0,0 +1,207 @@
+from collections import OrderedDict
+import logging
+from copy import deepcopy
+import pandas as pd
+import numpy as np
+
+from braindecode.splitters import concatenate_sets
+from braindecode.experiments.stopcriteria import MaxEpochs, ColumnBelow, Or
+from braindecode.torchext.util import np_to_var, set_random_seeds
+
+log = logging.getLogger(__name__)
+
+
+class RememberBest(object):
+    def __init__(self, column_name):
+        self.column_name = column_name
+        self.best_epoch = 0
+        self.lowest_val = float('inf')
+        self.model_state_dict = None
+        self.optimizer_state_dict = None
+
+    def remember_epoch(self, epochs_df, model, optimizer):
+        i_epoch = len(epochs_df) - 1
+        current_val = float(epochs_df[self.column_name].iloc[-1])
+        if current_val <= self.lowest_val:
+            self.best_epoch = i_epoch
+            self.lowest_val = current_val
+            self.model_state_dict = deepcopy(model.state_dict())
+            self.optimizer_state_dict = deepcopy(optimizer.state_dict())
+            log.info("New best {:s}: {:5f}".format(self.column_name,
+                                                   current_val))
+            log.info("")
+
+    def reset_to_best_model(self, epochs_df, model, optimizer):
+        # Remove epochs past the best one from epochs dataframe
+        epochs_df.drop(range(self.best_epoch+1, len(epochs_df)), inplace=True)
+        model.load_state_dict(self.model_state_dict)
+        optimizer.load_state_dict(self.optimizer_state_dict)
+
+
+class Experiment(object):
+    def __init__(self, model, train_set, valid_set, test_set,
+                 iterator, loss_function, optimizer, model_constraint,
+                 monitors, stop_criterion, remember_best_column,
+                 run_after_early_stop,
+                 batch_modifier=None, cuda=True):
+        self.model = model
+        self.datasets = OrderedDict(
+            (('train', train_set), ('valid', valid_set), ('test', test_set)))
+        self.iterator = iterator
+        self.loss_function = loss_function
+        self.optimizer = optimizer
+        self.model_constraint = model_constraint
+        self.monitors = monitors
+        self.stop_criterion = stop_criterion
+        self.remember_best_column = remember_best_column
+        self.run_after_early_stop = run_after_early_stop
+        self.batch_modifier = batch_modifier
+        self.cuda = cuda
+        self.epochs_df = pd.DataFrame()
+        self.before_stop_df = None
+        self.rememberer = None
+
+    def run(self):
+        self.setup_training()
+        log.info("Run until first stop...")
+        self.run_until_early_stop()
+        # always setup for second stop, in order to get best model
+        # even if not running after early stop...
+        log.info("Setup for second stop...")
+        self.setup_after_stop_training()
+        if self.run_after_early_stop:
+            log.info("Run until second stop...")
+            self.run_until_second_stop()
+
+    def setup_training(self):
+        # reset remember best extension in case you rerun some experiment
+        self.rememberer = RememberBest(self.remember_best_column)
+        self.epochs_df = pd.DataFrame()
+        set_random_seeds(seed=2382938, cuda=self.cuda)
+        if self.cuda:
+            self.model.cuda()
+
+    def run_until_early_stop(self):
+        self.run_until_stop(self.datasets, remember_best=True)
+
+    def run_until_second_stop(self):
+        datasets = self.datasets
+        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)
+
+    def run_until_stop(self, datasets, remember_best):
+        self.monitor_epoch(datasets)
+        self.print_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):
+            self.run_one_epoch(datasets, remember_best)
+
+    def run_one_epoch(self, datasets, remember_best):
+        batch_generator = self.iterator.get_batches(datasets['train'],
+                                                    shuffle=True)
+        # TODO, add timing again?
+        for inputs, targets in batch_generator:
+            if self.batch_modifier is not None:
+                inputs, targets = self.batch_modifier.process(inputs,
+                                                              targets)
+            # could happen that batch modifier has removed all inputs...
+            if len(inputs) > 0:
+                self.train_batch(inputs, targets)
+
+        self.monitor_epoch(datasets)
+        self.print_epoch()
+        if remember_best:
+            self.rememberer.remember_epoch(self.epochs_df, self.model,
+                                           self.optimizer)
+
+    def monitor_epoch(self, datasets):
+        result_dicts_per_monitor = OrderedDict()
+        for m in self.monitors:
+            result_dicts_per_monitor[m] = OrderedDict()
+        for m in self.monitors:
+            result_dict = m.monitor_epoch()
+            if result_dict is not None:
+                result_dicts_per_monitor[m].update(result_dict)
+        for setname in datasets:
+            assert setname in ['train', 'valid', 'test']
+            dataset = datasets[setname]
+            all_preds = []
+            all_losses = []
+            all_batch_sizes = []
+            all_targets = []
+            for batch in self.iterator.get_batches(dataset, shuffle=False):
+                preds, loss = self.eval_on_batch(batch[0], batch[1])
+                all_preds.append(preds)
+                all_losses.append(loss)
+                all_batch_sizes.append(len(batch[0]))
+                all_targets.append(batch[1])
+
+            for m in self.monitors:
+                result_dict = m.monitor_set(setname, all_preds, all_losses,
+                                            all_batch_sizes, all_targets,
+                                            dataset)
+                if result_dict is not None:
+                    result_dicts_per_monitor[m].update(result_dict)
+        row_dict = OrderedDict()
+        for m in self.monitors:
+            row_dict.update(result_dicts_per_monitor[m])
+        self.epochs_df = self.epochs_df.append(row_dict, ignore_index=True)
+        assert set(self.epochs_df.columns) == set(row_dict.keys())
+        self.epochs_df = self.epochs_df[list(row_dict.keys())]
+
+    def print_epoch(self):
+        # -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("")
+
+    def eval_on_batch(self, inputs, targets):
+        self.model.eval()
+        input_vars = np_to_var(inputs)
+        target_vars = np_to_var(targets)
+        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)
+        outputs = outputs.cpu().data.numpy()
+        loss = loss.cpu().data.numpy()
+        return outputs, loss
+
+    def train_batch(self, inputs, targets):
+        self.model.train()
+        input_vars = np_to_var(inputs)
+        target_vars = np_to_var(targets)
+        if self.cuda:
+            input_vars = input_vars.cuda()
+            target_vars = target_vars.cuda()
+        self.optimizer.zero_grad()
+        outputs = self.model(input_vars)
+        loss = self.loss_function(outputs, target_vars)
+        loss.backward()
+        self.optimizer.step()
+        if self.model_constraint is not None:
+            self.model_constraint.apply(self.model)
+
+    def setup_after_stop_training(self):
+        # also remember old monitor chans, will be put back into
+        # monitor chans after experiment finished
+        self.before_stop_df = deepcopy(self.epochs_df)
+        self.rememberer.reset_to_best_model(self.epochs_df, self.model,
+                                            self.optimizer)
+        loss_to_reach = float(self.epochs_df['train_loss'].iloc[-1])
+        self.stop_criterion = Or(stop_criteria=[
+            MaxEpochs(max_epochs=self.rememberer.best_epoch * 2),
+            ColumnBelow(column_name='valid_loss', target_value=loss_to_reach)])
+        log.info("Train loss to reach {:.5f}".format(loss_to_reach))

Braindecode-0.1.2/braindecode/experiments/monitors.py

@@ -0,0 +1,142 @@
+import numpy as np
+import time
+
+from braindecode.trial_segment import compute_trial_start_stop_samples
+
+
+class MisclassMonitor(object):
+    def __init__(self, exponentiate_preds=False, col_suffix='misclass'):
+        self.col_suffix = col_suffix
+        self.exponentiate_preds = exponentiate_preds
+
+    def monitor_epoch(self, ):
+        return
+
+    def monitor_set(self, setname, all_preds, all_losses,
+                    all_batch_sizes, all_targets, dataset):
+        all_pred_labels = []
+        all_target_labels = []
+        for i_batch in range(len(all_batch_sizes)):
+            preds = all_preds[i_batch]
+            if True:
+                preds = np.exp(preds)
+            pred_labels = np.argmax(preds, axis=1)
+            all_pred_labels.extend(pred_labels)
+            targets = all_targets[i_batch]
+            # targets may be one-hot-encoded or not
+            if targets.ndim >= pred_labels.ndim:
+                targets = np.argmax(targets, axis=1)
+            assert targets.shape == pred_labels.shape
+            all_target_labels.extend(targets)
+        all_pred_labels = np.array(all_pred_labels)
+        all_target_labels = np.array(all_target_labels)
+        assert all_pred_labels.shape == all_target_labels.shape
+
+        misclass = 1 - np.mean(all_target_labels == all_pred_labels)
+        column_name = "{:s}_{:s}".format(setname, self.col_suffix)
+        return {column_name: float(misclass)}
+
+
+class LossMonitor(object):
+    def monitor_epoch(self,):
+        return
+
+    def monitor_set(self, setname, all_preds, all_losses,
+                    all_batch_sizes, all_targets, dataset):
+        batch_weights = np.array(all_batch_sizes)/ np.sum(all_batch_sizes)
+        loss_per_batch = [np.mean(loss) for loss in all_losses]
+        mean_loss = np.sum(batch_weights * loss_per_batch)
+        column_name = "{:s}_loss".format(setname)
+        return {column_name: mean_loss}
+
+
+class CroppedTrialMisclassMonitor(object):
+    def __init__(self, input_time_length=None):
+        self.input_time_length = input_time_length
+
+    def monitor_epoch(self,):
+        return
+
+    def monitor_set(self, setname, all_preds, all_losses,
+                    all_batch_sizes, all_targets, dataset):
+        """Assuming one hot encoding for now"""
+        assert self.input_time_length is not None, "Need to know input time length..."
+        all_pred_labels = self.compute_pred_labels(dataset, all_preds)
+        assert all_pred_labels.shape == dataset.y.shape
+        misclass = 1 - np.mean(all_pred_labels == dataset.y)
+        column_name = "{:s}_misclass".format(setname)
+        return {column_name: float(misclass)}
+
+    def compute_pred_labels(self, dataset, all_preds,):
+        n_preds_per_input = all_preds[0].shape[2]
+        n_receptive_field = self.input_time_length - n_preds_per_input + 1
+
+        n_preds_per_trial = [trial.shape[1] - n_receptive_field + 1
+                        for trial in dataset.X]
+        preds_per_trial = compute_preds_per_trial_from_n_preds_per_trial(
+            all_preds, n_preds_per_trial)
+        all_pred_labels = [np.argmax(np.mean(p, axis=1))
+                           for p in preds_per_trial]
+
+        all_pred_labels = np.array(all_pred_labels)
+        assert all_pred_labels.shape == dataset.y.shape
+        return all_pred_labels
+
+
+def compute_preds_per_trial_for_set(all_preds, input_time_length,
+                                        dataset, ):
+        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]
+        preds_per_trial = compute_preds_per_trial_from_n_preds_per_trial(
+            all_preds, n_preds_per_trial)
+        return preds_per_trial
+
+
+def compute_preds_per_trial_from_n_preds_per_trial(
+        all_preds, n_preds_per_trial):
+    # all_preds_arr has shape forward_passes x classes x time
+    all_preds_arr = np.concatenate(all_preds, axis=0)
+    preds_per_trial = []
+    i_pred_block = 0
+    for i_trial in range(len(n_preds_per_trial)):
+        n_needed_preds = n_preds_per_trial[i_trial]
+        preds_this_trial = []
+        while n_needed_preds > 0:
+            # - n_needed_preds: only has an effect
+            # in case there are more samples than we actually still need
+            # in the block.
+            # That can happen since final block of a trial can overlap
+            # with block before so we can have some redundant preds.
+            pred_samples = all_preds_arr[i_pred_block,:,
+                           -n_needed_preds:]
+            preds_this_trial.append(pred_samples)
+            n_needed_preds -= pred_samples.shape[1]
+            i_pred_block += 1
+
+        preds_this_trial = np.concatenate(preds_this_trial, axis=1)
+        preds_per_trial.append(preds_this_trial)
+    assert i_pred_block == len(all_preds_arr), (
+        "Expect that all prediction forward passes are needed, "
+        "used {:d}, existing {:d}".format(
+            i_pred_block, len(all_preds_arr)))
+    return preds_per_trial
+
+
+class RuntimeMonitor(object):
+    def __init__(self):
+        self.last_call_time = None
+
+    def monitor_epoch(self,):
+        cur_time = time.time()
+        if self.last_call_time is None:
+            # just in case of first call
+            self.last_call_time = cur_time
+        epoch_runtime = cur_time - self.last_call_time
+        self.last_call_time = cur_time
+        return {'runtime': epoch_runtime}
+
+    def monitor_set(self, setname, all_preds, all_losses,
+                    all_batch_sizes, all_targets, dataset):
+        return {}

Braindecode-0.1.2/braindecode/experiments/stopcriteria.py

@@ -0,0 +1,53 @@
+import numpy as np
+
+
+class MaxEpochs(object):
+    def __init__(self, max_epochs):
+        self.max_epochs = max_epochs
+
+    def should_stop(self, epochs_df):
+        # Keep in mind  epoch 0 without training is also part of dataframe
+        return len(epochs_df) - 1 >= self.max_epochs
+
+
+class Or(object):
+    def __init__(self, stop_criteria):
+        self.stop_criteria = stop_criteria
+
+    def should_stop(self, epochs_df):
+        return np.any([s.should_stop(epochs_df)
+                       for s in self.stop_criteria])
+
+
+class NoDecrease(object):
+    """ Stops if there is no decrease on a given monitor channel
+    for given number of epochs."""
+
+    def __init__(self, column_name, num_epochs, min_decrease=1e-6):
+        self.column_name = column_name
+        self.num_epochs = num_epochs
+        self.min_decrease = min_decrease
+        self.best_epoch = 0
+        self.lowest_val = float('inf')
+
+    def should_stop(self, epochs_df):
+        # -1 due to doing one monitor at start of training
+        i_epoch = len(epochs_df) - 1
+        current_val = float(epochs_df[self.column_name].iloc[-1])
+        if current_val < ((1 - self.min_decrease) * self.lowest_val):
+            self.best_epoch = i_epoch
+            self.lowest_val = current_val
+
+        return (i_epoch - self.best_epoch) >= self.num_epochs
+
+
+class ColumnBelow():
+    """ Stops if the given column is below the given value."""
+    def __init__(self, column_name, target_value):
+        self.column_name = column_name
+        self.target_value = target_value
+
+    def should_stop(self, epochs_df):
+        # -1 due to doing one monitor at start of training
+        current_val = float(epochs_df[self.column_name].iloc[-1])
+        return current_val < self.target_value