Ctrl+K

braindecode.samplers package#

Classes to sample examples.

class braindecode.samplers.BalancedSequenceSampler(metadata, n_windows, n_sequences=10, random_state=None)[source]#

Bases: 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). perslev/U-Time

sample_class(rec_ind=None)[source]#

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.

class braindecode.samplers.RecordingSampler(metadata, random_state=None)[source]#

Bases: 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 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.

info#

Series with MultiIndex index which contains the subject, session, run and window indices information in an easily accessible structure for quick sampling of windows.

Type:

pd.DataFrame

n_recordings#

Number of recordings available.

Type:

int

property n_recordings#
sample_recording()[source]#

Return a random recording index.

sample_window(rec_ind=None)[source]#

Return a specific window.

class braindecode.samplers.RelativePositioningSampler(metadata, tau_pos, tau_neg, n_examples, tau_max=None, same_rec_neg=True, random_state=None)[source]#

Bases: RecordingSampler

Sample examples for the relative positioning task from [Banville2020].

Sample examples as tuples of two window indices, with a label indicating whether the windows are close or far, as defined by tau_pos and tau_neg.

Parameters:

  • metadata (pd.DataFrame) – See RecordingSampler.

  • tau_pos (int) – Size of the positive context, in samples. A positive pair contains two windows x1 and x2 which are separated by at most tau_pos samples.

  • tau_neg (int) – Size of the negative context, in samples. A negative pair contains two windows x1 and x2 which are separated by at least tau_neg samples and at most tau_max samples. Ignored if same_rec_neg is False.

  • n_examples (int) – Number of pairs to extract.

  • tau_max (int | None) – See tau_neg.

  • same_rec_neg (bool) – If True, sample negative pairs from within the same recording. If False, sample negative pairs from two different recordings.

  • random_state (None | np.RandomState | int) – Random state.

References

[Banville2020]

Banville, H., Chehab, O., Hyvärinen, A., Engemann, D. A., & Gramfort, A. (2020). Uncovering the structure of clinical EEG signals with self-supervised learning. arXiv preprint arXiv:2007.16104.

presample()[source]#

Presample examples.

Once presampled, the examples are the same from one epoch to another.

class braindecode.samplers.SequenceSampler(metadata, n_windows, n_windows_stride, randomize=False, random_state=None)[source]#

Bases: 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.

info#

See RecordingSampler.

Type:

pd.DataFrame

file_ids#

Array of shape (n_sequences,) that indicates from which file each sequence comes from. Useful e.g. to do self-ensembling.

Type:

np.ndarray of ints

Submodules#

braindecode.samplers.base module#

Sampler classes.

class braindecode.samplers.base.BalancedSequenceSampler(metadata, n_windows, n_sequences=10, random_state=None)[source]#

Bases: 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). perslev/U-Time

sample_class(rec_ind=None)[source]#

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.

class braindecode.samplers.base.RecordingSampler(metadata, random_state=None)[source]#

Bases: 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 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.

info#

Series with MultiIndex index which contains the subject, session, run and window indices information in an easily accessible structure for quick sampling of windows.

Type:

pd.DataFrame

n_recordings#

Number of recordings available.

Type:

int

property n_recordings#
sample_recording()[source]#

Return a random recording index.

sample_window(rec_ind=None)[source]#

Return a specific window.

class braindecode.samplers.base.SequenceSampler(metadata, n_windows, n_windows_stride, randomize=False, random_state=None)[source]#

Bases: 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.

info#

See RecordingSampler.

Type:

pd.DataFrame

file_ids#

Array of shape (n_sequences,) that indicates from which file each sequence comes from. Useful e.g. to do self-ensembling.

Type:

np.ndarray of ints

braindecode.samplers.ssl module#

Self-supervised learning samplers.

class braindecode.samplers.ssl.RelativePositioningSampler(metadata, tau_pos, tau_neg, n_examples, tau_max=None, same_rec_neg=True, random_state=None)[source]#

Bases: RecordingSampler

Sample examples for the relative positioning task from [Banville2020].

Sample examples as tuples of two window indices, with a label indicating whether the windows are close or far, as defined by tau_pos and tau_neg.

Parameters:

  • metadata (pd.DataFrame) – See RecordingSampler.

  • tau_pos (int) – Size of the positive context, in samples. A positive pair contains two windows x1 and x2 which are separated by at most tau_pos samples.

  • tau_neg (int) – Size of the negative context, in samples. A negative pair contains two windows x1 and x2 which are separated by at least tau_neg samples and at most tau_max samples. Ignored if same_rec_neg is False.

  • n_examples (int) – Number of pairs to extract.

  • tau_max (int | None) – See tau_neg.

  • same_rec_neg (bool) – If True, sample negative pairs from within the same recording. If False, sample negative pairs from two different recordings.

  • random_state (None | np.RandomState | int) – Random state.

References

[Banville2020]

Banville, H., Chehab, O., Hyvärinen, A., Engemann, D. A., & Gramfort, A. (2020). Uncovering the structure of clinical EEG signals with self-supervised learning. arXiv preprint arXiv:2007.16104.

presample()[source]#

Presample examples.

Once presampled, the examples are the same from one epoch to another.

On this page