braindecode 1.3.0.dev177069446__py3-none-any.whl

braindecode/regressor.py

@@ -0,0 +1,234 @@
+# Authors: Maciej Sliwowski <maciek.sliwowski@gmail.com>
+#          Robin Schirrmeister <robintibor@gmail.com>
+#          Lukas Gemein <l.gemein@gmail.com>
+#          Bruno Aristimunha <b.aristimunha@gmail.com>
+#          Pierre Guetschel <pierre.guetschel@gmail.com>
+#
+# License: BSD (3-clause)
+
+import warnings
+
+import numpy as np
+from skorch.regressor import NeuralNetRegressor
+
+from .eegneuralnet import _EEGNeuralNet
+from .training.scoring import predict_trials
+from .util import ThrowAwayIndexLoader, update_estimator_docstring
+
+
+class EEGRegressor(_EEGNeuralNet, NeuralNetRegressor):
+    doc = """Regressor that calls loss function directly.
+
+    Parameters
+    ----------
+    module: str or torch Module (class or instance)
+        Either the name of one of the braindecode models (see
+        :obj:`braindecode.models.util.models_dict`) or directly a PyTorch module.
+        When passing directly a torch module, uninstantiated class should be preferred,
+        although instantiated modules will also work.
+
+    cropped: bool (default=False)
+        Defines whether torch model passed to this class is cropped or not.
+        Currently used for callbacks definition.
+
+    callbacks: None or list of strings or list of Callback instances (default=None)
+        More callbacks, in addition to those returned by
+        ``get_default_callbacks``. Each callback should inherit from
+        :class:`skorch.callbacks.Callback`. If not ``None``, callbacks can be a
+        list of strings specifying `sklearn` scoring functions (for scoring
+        functions names see: https://scikit-learn.org/stable/modules/model_evaluation.html#scoring-parameter)
+        or a list of callbacks where the callback names are inferred from the
+        class name. Name conflicts are resolved by appending a count suffix
+        starting with 1, e.g. ``EpochScoring_1``. Alternatively,
+        a tuple ``(name, callback)`` can be passed, where ``name``
+        should be unique. Callbacks may or may not be instantiated.
+        The callback name can be used to set parameters on specific
+        callbacks (e.g., for the callback with name ``'print_log'``, use
+        ``net.set_params(callbacks__print_log__keys_ignored=['epoch',
+        'train_loss'])``).
+
+    iterator_train__shuffle: bool (default=True)
+        Defines whether train dataset will be shuffled. As skorch does not
+        shuffle the train dataset by default this one overwrites this option.
+
+    aggregate_predictions: bool (default=True)
+        Whether to average cropped predictions to obtain window predictions. Used only in the
+        cropped mode.
+
+    """  # noqa: E501
+    __doc__ = update_estimator_docstring(NeuralNetRegressor, doc)
+
+    def __init__(
+        self,
+        module,
+        *args,
+        cropped=False,
+        callbacks=None,
+        iterator_train__shuffle=True,
+        iterator_train__drop_last=True,
+        aggregate_predictions=True,
+        **kwargs,
+    ):
+        self.cropped = cropped
+        self.aggregate_predictions = aggregate_predictions
+        self._last_window_inds_ = None
+        super().__init__(
+            module,
+            *args,
+            callbacks=callbacks,
+            iterator_train__shuffle=iterator_train__shuffle,
+            iterator_train__drop_last=iterator_train__drop_last,
+            **kwargs,
+        )
+
+    def get_iterator(self, dataset, training=False, drop_index=True):
+        iterator = super().get_iterator(dataset, training=training)
+        if drop_index:
+            return ThrowAwayIndexLoader(self, iterator, is_regression=True)
+        else:
+            return iterator
+
+    def predict_proba(self, X):
+        """Return the output of the module's forward method as a numpy.
+
+        array. In case of cropped decoding returns averaged values for
+        each trial.
+
+        If the module's forward method returns multiple outputs as a
+        tuple, it is assumed that the first output contains the
+        relevant information and the other values are ignored.
+        If all values are relevant or module's output for each crop
+        is needed, consider using :func:`~skorch.NeuralNet.forward`
+        instead.
+
+        Parameters
+        ----------
+        X : input data, compatible with skorch.dataset.Dataset
+          By default, you should be able to pass:
+
+            * numpy arrays
+            * torch tensors
+            * pandas DataFrame or Series
+            * scipy sparse CSR matrices
+            * a dictionary of the former three
+            * a list/tuple of the former three
+            * a Dataset
+
+          If this doesn't work with your data, you have to pass a
+          ``Dataset`` that can deal with the data.
+
+        Returns
+        -------
+        y_proba : numpy ndarray
+
+        Warnings
+        --------
+        Regressors predict regression targets, so output of this method
+        can't be interpreted as probabilities. We advise you to use
+        `predict` method instead of `predict_proba`.
+        """
+        y_pred = super().predict_proba(X)
+        # Normally, we have to average the predictions across crops/timesteps
+        # to get one prediction per window/trial
+        # Predictions may be already averaged in CroppedTrialEpochScoring (y_pred.shape==2).
+        # However, when predictions are computed outside of CroppedTrialEpochScoring
+        # we have to average predictions, hence the check if len(y_pred.shape) == 3
+        if self.cropped and self.aggregate_predictions and len(y_pred.shape) == 3:
+            return y_pred.mean(-1)
+        else:
+            return y_pred
+
+    def predict_trials(self, X, return_targets=True):
+        """Create trialwise predictions and optionally also return trialwise.
+
+        labels from cropped dataset.
+
+        Parameters
+        ----------
+        X : braindecode.datasets.BaseConcatDataset
+            A braindecode dataset to be predicted.
+        return_targets : bool
+            If True, additionally returns the trial targets.
+
+        Returns
+        -------
+        trial_predictions : np.ndarray
+            3-dimensional array (n_trials x n_classes x n_predictions), where
+            the number of predictions depend on the chosen window size and the
+            receptive field of the network.
+        trial_labels : np.ndarray
+            2-dimensional array (n_trials x n_targets) where the number of
+            targets depends on the decoding paradigm and can be either a single
+            value, multiple values, or a sequence.
+        """
+        if not self.cropped:
+            warnings.warn(
+                "This method was designed to predict trials in cropped mode. "
+                "Calling it when cropped is False will give the same result as "
+                "'.predict'.",
+                UserWarning,
+            )
+            preds = self.predict(X)
+            if return_targets:
+                return preds, np.concatenate([X[i][1] for i in range(len(X))])
+            return preds
+        return predict_trials(
+            module=self.module,
+            dataset=X,
+            return_targets=return_targets,
+            batch_size=self.batch_size,
+            num_workers=self.get_iterator(X, training=False).loader.num_workers,
+        )
+
+    def fit(self, X, y=None, **kwargs):
+        """Initialize and fit the module.
+
+        If the module was already initialized, by calling fit, the
+        module will be re-initialized (unless ``warm_start`` is True).
+        If possible, signal-related parameters are inferred from the
+        data and passed to the module at initialisation.
+        Depending on the type of input passed, the following parameters
+        are inferred:
+
+          * mne.Epochs: ``n_times``, ``n_chans``, ``n_outputs``, ``chs_info``,
+            ``sfreq``, ``input_window_seconds``
+          * numpy array: ``n_times``, ``n_chans``, ``n_outputs``
+          * WindowsDataset with ``targets_from='metadata'``
+            (or BaseConcatDataset of such datasets): ``n_times``, ``n_chans``, ``n_outputs``
+          * other Dataset: ``n_times``, ``n_chans``
+          * other types: no parameters are inferred.
+
+        Parameters
+        ----------
+        X : input data, compatible with skorch.dataset.Dataset
+          By default, you should be able to pass:
+
+            * mne.Epochs
+            * numpy arrays
+            * torch tensors
+            * pandas DataFrame or Series
+            * scipy sparse CSR matrices
+            * a dictionary of the former three
+            * a list/tuple of the former three
+            * a Dataset
+
+          If this doesn't work with your data, you have to pass a
+          ``Dataset`` that can deal with the data.
+
+        y : target data, compatible with skorch.dataset.Dataset
+          The same data types as for ``X`` are supported. If your X is
+          a Dataset that contains the target, ``y`` may be set to
+          None.
+
+        **fit_params : dict
+          Additional parameters passed to the ``forward`` method of
+          the module and to the ``self.train_split`` call.
+        """
+        if y is not None:
+            if y.ndim == 1:
+                y = np.array(y).reshape(-1, 1)
+        super().fit(X=X, y=y, **kwargs)
+
+    @property
+    def mode(self):
+        return "regression"

braindecode/samplers/__init__.py

@@ -0,0 +1,18 @@
+"""Classes to sample examples."""
+
+from .base import (
+    BalancedSequenceSampler,
+    DistributedRecordingSampler,
+    RecordingSampler,
+    SequenceSampler,
+)
+from .ssl import DistributedRelativePositioningSampler, RelativePositioningSampler
+
+__all__ = [
+    "RecordingSampler",
+    "SequenceSampler",
+    "BalancedSequenceSampler",
+    "RelativePositioningSampler",
+    "DistributedRecordingSampler",
+    "DistributedRelativePositioningSampler",
+]

braindecode/samplers/base.py

@@ -0,0 +1,399 @@
+"""
+Sampler classes.
+"""
+
+# Authors: Hubert Banville <hubert.jbanville@gmail.com>
+#          Theo Gnassounou <>
+#          Young Truong <dt.young112@gmail.com>
+#
+# License: BSD (3-clause)
+
+import numpy as np
+from sklearn.utils import check_random_state
+from torch.utils.data.distributed import DistributedSampler
+from torch.utils.data.sampler import Sampler
+
+
+class RecordingSampler(Sampler):
+    """Base sampler simplifying sampling from recordings.
+
+    Parameters
+    ----------
+    metadata : pd.DataFrame
+        DataFrame with at least one of {subject, session, run} columns for each
+        window in the BaseConcatDataset to sample examples from. Normally
+        obtained with `BaseConcatDataset.get_metadata()`. For instance,
+        `metadata.head()` might look like this:
+        +-------------------+-----------------+-----------------+--------+----------+-----------+-------+
+        | i_window_in_trial | i_start_in_trial| i_stop_in_trial | target | subject  | session   | run   |
+        +===================+=================+=================+========+==========+===========+=======+
+        | 0                 | 0               | 500             | -1     | 4        | session_T | run_0 |
+        +-------------------+-----------------+-----------------+--------+----------+-----------+-------+
+        | 1                 | 500             | 1000            | -1     | 4        | session_T | run_0 |
+        +-------------------+-----------------+-----------------+--------+----------+-----------+-------+
+        | 2                 | 1000            | 1500            | -1     | 4        | session_T | run_0 |
+        +-------------------+-----------------+-----------------+--------+----------+-----------+-------+
+        | 3                 | 1500            | 2000            | -1     | 4        | session_T | run_0 |
+        +-------------------+-----------------+-----------------+--------+----------+-----------+-------+
+        | 4                 | 2000            | 2500            | -1     | 4        | session_T | run_0 |
+        +-------------------+-----------------+-----------------+--------+----------+-----------+-------+
+
+    random_state : np.RandomState | int | None
+        Random state.
+
+    Attributes
+    ----------
+    info : pd.DataFrame
+        Series with MultiIndex index which contains the subject, session, run
+        and window indices information in an easily accessible structure for
+        quick sampling of windows.
+    n_recordings : int
+        Number of recordings available.
+    """
+
+    def __init__(self, metadata, random_state=None):
+        self.metadata = metadata
+        self.info = self._init_info(metadata)
+        self.rng = check_random_state(random_state)
+
+    def _init_info(self, metadata, required_keys=None):
+        """Initialize ``info`` DataFrame.
+
+        Parameters
+        ----------
+        required_keys : list(str) | None
+            List of additional columns of the metadata DataFrame that we should
+            groupby when creating ``info``.
+
+        Returns
+        -------
+            See class attributes.
+        """
+        keys = [k for k in ["subject", "session", "run"] if k in self.metadata.columns]
+        if not keys:
+            raise ValueError(
+                "metadata must contain at least one of the following columns: "
+                "subject, session or run."
+            )
+
+        if required_keys is not None:
+            missing_keys = [k for k in required_keys if k not in self.metadata.columns]
+            if len(missing_keys) > 0:
+                raise ValueError(f"Columns {missing_keys} were not found in metadata.")
+            keys += required_keys
+
+        metadata = metadata.reset_index().rename(columns={"index": "window_index"})
+        info = (
+            metadata.reset_index()
+            .groupby(keys)[["index", "i_start_in_trial"]]
+            .agg(["unique"])
+        )
+        info.columns = info.columns.get_level_values(0)
+
+        return info
+
+    def sample_recording(self):
+        """Return a random recording index."""
+        # XXX docstring missing
+        return self.rng.choice(self.n_recordings)
+
+    def sample_window(self, rec_ind=None):
+        """Return a specific window."""
+        # XXX docstring missing
+        if rec_ind is None:
+            rec_ind = self.sample_recording()
+        win_ind = self.rng.choice(self.info.iloc[rec_ind]["index"])
+        return win_ind, rec_ind
+
+    def __iter__(self):
+        raise NotImplementedError
+
+    @property
+    def n_recordings(self):
+        return self.info.shape[0]
+
+
+class DistributedRecordingSampler(DistributedSampler):
+    """Base sampler simplifying sampling from recordings in distributed setting.
+
+    Parameters
+    ----------
+    metadata : pd.DataFrame
+        DataFrame with at least one of {subject, session, run} columns for each
+        window in the BaseConcatDataset to sample examples from. Normally
+        obtained with `BaseConcatDataset.get_metadata()`. For instance,
+        `metadata.head()` might look like this::
+
+            i_window_in_trial  i_start_in_trial  i_stop_in_trial  target  subject    session    run
+            0                  0                 0              500      -1        4  session_T  run_0
+            1                  1               500             1000      -1        4  session_T  run_0
+            2                  2              1000             1500      -1        4  session_T  run_0
+            3                  3              1500             2000      -1        4  session_T  run_0
+            4                  4              2000             2500      -1        4  session_T  run_0
+
+    random_state : np.RandomState | int | None
+        Random state.
+
+    Attributes
+    ----------
+    info : pd.DataFrame
+        Series with MultiIndex index which contains the subject, session, run
+        and window indices information in an easily accessible structure for
+        quick sampling of windows.
+    n_recordings : int
+        Number of recordings available.
+    kwargs : dict
+        Additional keyword arguments to pass to torch DistributedSampler.
+        See https://pytorch.org/docs/stable/data.html#torch.utils.data.distributed.DistributedSampler
+    """
+
+    def __init__(
+        self,
+        metadata,
+        random_state=None,
+        **kwargs,
+    ):
+        self.metadata = metadata
+        self.info = self._init_info(metadata)
+        self.rng = check_random_state(random_state)
+        # send information to DistributedSampler parent to handle data splitting among workers
+        super().__init__(self.info, seed=random_state, **kwargs)
+
+    def _init_info(self, metadata, required_keys=None):
+        """Initialize ``info`` DataFrame.
+
+        Parameters
+        ----------
+        required_keys : list(str) | None
+            List of additional columns of the metadata DataFrame that we should
+            groupby when creating ``info``.
+
+        Returns
+        -------
+            See class attributes.
+        """
+        keys = [k for k in ["subject", "session", "run"] if k in self.metadata.columns]
+        if not keys:
+            raise ValueError(
+                "metadata must contain at least one of the following columns: "
+                "subject, session or run."
+            )
+
+        if required_keys is not None:
+            missing_keys = [k for k in required_keys if k not in self.metadata.columns]
+            if len(missing_keys) > 0:
+                raise ValueError(f"Columns {missing_keys} were not found in metadata.")
+            keys += required_keys
+
+        metadata = metadata.reset_index().rename(columns={"index": "window_index"})
+        info = (
+            metadata.reset_index()
+            .groupby(keys)[["index", "i_start_in_trial"]]
+            .agg(["unique"])
+        )
+        info.columns = info.columns.get_level_values(0)
+
+        return info
+
+    def sample_recording(self):
+        """Return a random recording index.
+        super().__iter__() contains indices of datasets specific to the current process
+        determined by the DistributedSampler
+        """
+        # XXX docstring missing
+        return self.rng.choice(list(super().__iter__()))
+
+    def sample_window(self, rec_ind=None):
+        """Return a specific window."""
+        # XXX docstring missing
+        if rec_ind is None:
+            rec_ind = self.sample_recording()
+        win_ind = self.rng.choice(self.info.iloc[rec_ind]["index"])
+        return win_ind, rec_ind
+
+    @property
+    def n_recordings(self):
+        return super().__len__()
+
+
+class SequenceSampler(RecordingSampler):
+    """Sample sequences of consecutive windows.
+
+    Parameters
+    ----------
+    metadata : pd.DataFrame
+        See RecordingSampler.
+    n_windows : int
+        Number of consecutive windows in a sequence.
+    n_windows_stride : int
+        Number of windows between two consecutive sequences.
+    random : bool
+        If True, sample sequences randomly. If False, sample sequences in
+        order.
+    random_state : np.random.RandomState | int | None
+        Random state.
+
+    Attributes
+    ----------
+    info : pd.DataFrame
+        See RecordingSampler.
+    file_ids : np.ndarray of ints
+        Array of shape (n_sequences,) that indicates from which file each
+        sequence comes from. Useful e.g. to do self-ensembling.
+    """
+
+    def __init__(
+        self, metadata, n_windows, n_windows_stride, randomize=False, random_state=None
+    ):
+        super().__init__(metadata, random_state=random_state)
+        self.randomize = randomize
+        self.n_windows = n_windows
+        self.n_windows_stride = n_windows_stride
+        self.start_inds, self.file_ids = self._compute_seq_start_inds()
+
+    def _compute_seq_start_inds(self):
+        """Compute sequence start indices.
+
+        Returns
+        -------
+        np.ndarray :
+            Array of shape (n_sequences,) containing the indices of the first
+            windows of possible sequences.
+        np.ndarray :
+            Array of shape (n_sequences,) containing the unique file number of
+            each sequence. Useful e.g. to do self-ensembling.
+        """
+        end_offset = 1 - self.n_windows if self.n_windows > 1 else None
+        start_inds = (
+            self.info["index"]
+            .apply(lambda x: x[: end_offset : self.n_windows_stride])
+            .values
+        )
+        file_ids = [[i] * len(inds) for i, inds in enumerate(start_inds)]
+        return np.concatenate(start_inds), np.concatenate(file_ids)
+
+    def __len__(self):
+        return len(self.start_inds)
+
+    def __iter__(self):
+        if self.randomize:
+            start_inds = self.start_inds.copy()
+            self.rng.shuffle(start_inds)
+            for start_ind in start_inds:
+                yield tuple(range(start_ind, start_ind + self.n_windows))
+        else:
+            for start_ind in self.start_inds:
+                yield tuple(range(start_ind, start_ind + self.n_windows))
+
+
+class BalancedSequenceSampler(RecordingSampler):
+    """Balanced sampling of sequences of consecutive windows with categorical
+    targets.
+
+    Balanced sampling of sequences inspired by the approach of [Perslev2021]_:
+    1. Uniformly sample a recording out of the available ones.
+    2. Uniformly sample one of the classes.
+    3. Sample a window of the corresponding class in the selected recording.
+    4. Extract a sequence of windows around the sampled window.
+
+    Parameters
+    ----------
+    metadata : pd.DataFrame
+        See RecordingSampler.
+        Must contain a column `target` with categorical targets.
+    n_windows : int
+        Number of consecutive windows in a sequence.
+    n_sequences : int
+        Number of sequences to sample.
+    random_state : np.random.RandomState | int | None
+        Random state.
+
+    References
+    ----------
+    .. [Perslev2021] Perslev M, Darkner S, Kempfner L, Nikolic M, Jennum PJ,
+           Igel C. U-Sleep: resilient high-frequency sleep staging. npj Digit.
+           Med. 4, 72 (2021).
+           https://github.com/perslev/U-Time/blob/master/utime/models/usleep.py
+    """
+
+    def __init__(self, metadata, n_windows, n_sequences=10, random_state=None):
+        super().__init__(metadata, random_state=random_state)
+
+        self.n_windows = n_windows
+        self.n_sequences = n_sequences
+        self.info_class = self._init_info(metadata, required_keys=["target"])
+
+    def sample_class(self, rec_ind=None):
+        """Return a random class.
+
+        Parameters
+        ----------
+        rec_ind : int | None
+            Index to the recording to sample from. If None, the recording will
+            be uniformly sampled across available recordings.
+
+        Returns
+        -------
+        int
+            Sampled class.
+        int
+            Index to the recording the class was sampled from.
+        """
+        if rec_ind is None:
+            rec_ind = self.sample_recording()
+        available_classes = self.info_class.loc[self.info.iloc[rec_ind].name].index
+        return self.rng.choice(available_classes), rec_ind
+
+    def _sample_seq_start_ind(self, rec_ind=None, class_ind=None):
+        """Sample a sequence and return its start index.
+
+        Sample a window associated with a random recording and a random class
+        and randomly sample a sequence with it inside. The function returns the
+        index of the beginning of the sequence.
+
+        Parameters
+        ----------
+        rec_ind : int | None
+            Index to the recording to sample from. If None, the recording will
+            be uniformly sampled across available recordings.
+        class_ind : int | None
+            If provided as int, sample a window of the corresponding class. If
+            None, the class will be uniformly sampled across available classes.
+
+        Returns
+        -------
+        int
+            Index of the first window of the sequence.
+        int
+            Corresponding recording index.
+        int
+            Class of the sampled window.
+        """
+        if class_ind is None:
+            class_ind, rec_ind = self.sample_class(rec_ind)
+
+        rec_inds = self.info.iloc[rec_ind]["index"]
+        len_rec_inds = len(rec_inds)
+
+        row = self.info.iloc[rec_ind].name
+        if not isinstance(row, tuple):
+            # Theres's only one category, e.g. "subject"
+            row = tuple([row])
+        available_indices = self.info_class.loc[row + tuple([class_ind]), "index"]
+        win_ind = self.rng.choice(available_indices)
+        win_ind_in_rec = np.where(rec_inds == win_ind)[0][0]
+
+        # Minimum and maximum start indices in the sequence
+        min_pos = max(0, win_ind_in_rec - self.n_windows + 1)
+        max_pos = min(len_rec_inds - self.n_windows, win_ind_in_rec)
+        start_ind = rec_inds[self.rng.randint(min_pos, max_pos + 1)]
+
+        return start_ind, rec_ind, class_ind
+
+    def __len__(self):
+        return self.n_sequences
+
+    def __iter__(self):
+        for _ in range(self.n_sequences):
+            start_ind, _, _ = self._sample_seq_start_ind()
+            yield tuple(range(start_ind, start_ind + self.n_windows))