braindecode.augmentation.BandRotation#

class braindecode.augmentation.BandRotation(probability, num_bands=2, electrodes_per_band=16, band_offsets=(-1, 0, 1), max_temporal_jitter=0, circular_jitter=True, random_state=None)[source]#

Per-band electrode rotation + inter-band temporal jitter.

Models small wristband rotation between sessions and relative timing noise between two arms. Introduced in [Sivakumar2024] for the emg2qwerty surface-EMG keystroke decoding task: the channel axis is laid out as (B, num_bands * electrodes_per_band, T) with bands contiguous, each band gets a uniform circular roll along the channel axis, and when num_bands >= 2, band 1 also gets a sample-level temporal shift. The same offset / shift is applied to every sample in a transformed sub-batch (one set of parameters per call).

Parameters:

  • probability (float) – Float setting the probability of applying the operation.

  • num_bands (int, optional) – Number of electrode bands (e.g. 2 for left + right wristband). Must be >= 1. Defaults to 2.

  • electrodes_per_band (int, optional) – Electrodes per band (e.g. 16). Must be >= 1. Defaults to 16.

  • band_offsets (tuple of int, optional) – Per-band roll values to sample from uniformly. (-1, 0, 1) covers ±1-electrode misalignment. Must be non-empty. Defaults to (-1, 0, 1).

  • max_temporal_jitter (int, optional) – Max ±-sample temporal shift applied to band 1. Defaults to 0 (jitter disabled). Must be >= 0. The emg2qwerty paper uses 120 samples (60 ms at 2 kHz).

  • circular_jitter (bool, optional) – If True (default, paper-faithful) the jitter is a circular roll; if False the gap left by the shift is zero-padded. See band_rotation().

  • random_state (int | numpy.random.RandomState, optional) – Seed for the rotation / jitter sampler. Defaults to None.

References

[Sivakumar2024]

Sivakumar, V., Seely, J., Du, A., Bittner, S. R., Berenzweig, A., Bolarinwa, A., Gramfort, A., & Mandel, M. I. (2024). “emg2qwerty: A Large Dataset with Baselines for Touch Typing using Surface Electromyography.” NeurIPS Datasets and Benchmarks Track.

Methods

get_augmentation_params(*batch)[source]#
static operation(y, num_bands=2, electrodes_per_band=16, band_offsets=(-1, 0, 1), max_temporal_jitter=0, circular_jitter=True, random_state=None)[source]#

Per-band electrode rotation + inter-band temporal jitter.

Models small wristband rotation between sessions and relative timing noise between two arms. Introduced in [Sivakumar2024] for the emg2qwerty CTC keystroke decoding task: each electrode band gets its own circular roll along the channel axis (Uniform(band_offsets) positions), and band 1 also gets a sample-level temporal shift (Uniform(-max_temporal_jitter, +max_temporal_jitter)) along the time axis.

Channel layout assumes (B, num_bands * electrodes_per_band, T) with bands contiguous along the channel axis. Same offset / shift is applied to every sample in the batch (one set of parameters per call).

Parameters:

  • X (Tensor) – EMG input batch of shape (B, C, T) with C == num_bands * electrodes_per_band.

  • y (Tensor) – Labels (returned unchanged).

  • num_bands (int) – Number of electrode bands (e.g. 2 for left + right wristband). Must be >= 1. Defaults to 2.

  • electrodes_per_band (int) – Electrodes per band (e.g. 16). Must be >= 1. Defaults to 16.

  • band_offsets (tuple[int, ...]) – Per-band roll values to sample from uniformly. (-1, 0, 1) covers ±1-electrode misalignment. Must be non-empty. Defaults to (-1, 0, 1).

  • max_temporal_jitter (int) – Max ±-sample temporal shift applied to band 1 only when num_bands >= 2. Defaults to 0 (disabled). Must be >= 0.

  • circular_jitter (bool) – If True (the default, paper-faithful), the temporal jitter is a circular torch.roll — samples shifted off one edge wrap to the other. If False, the gap left by the shift is zero-padded and the shifted-off samples are dropped, avoiding wrap-around discontinuity at the cost of a small zeroed margin. Has no effect when max_temporal_jitter == 0.

  • random_state (int | RandomState | None) – Seed / generator for sampling rotation + jitter values.

Return type:

tuple[Tensor, Tensor]

Returns:

  • torch.Tensor – Transformed inputs.

  • torch.Tensor – Labels (unchanged).

References

[Sivakumar2024]

Sivakumar, V., Seely, J., Du, A., Bittner, S. R., Berenzweig, A., Bolarinwa, A., Gramfort, A., & Mandel, M. I. (2024). “emg2qwerty: A Large Dataset with Baselines for Touch Typing using Surface Electromyography.” NeurIPS Datasets and Benchmarks Track.