EMGData#

class myoverse.datatypes.EMGData(input_data, sampling_frequency, grid_layouts=None)[source]#

Class for storing EMG data.

Parameters:

  • input_data (np.ndarray) –

    The raw EMG data. The shape of the array should be (n_channels, n_samples) or (n_chunks, n_channels, n_samples).#

    Important

    The class will only accept 2D or 3D arrays.

    There is no way to check if you actually have it in (n_chunks, n_samples) or (n_chunks, n_channels, n_samples) format. Please make sure to provide the correct shape of the data.

  • sampling_frequency (float) – The sampling frequency of the EMG data.

  • grid_layouts (Optional[List[np.ndarray]], optional) –

    List of 2D arrays specifying the exact electrode arrangement for each grid. Each array element contains the electrode index (0-based).

    Note

    All electrodes numbers must be unique and non-negative. The numbers must be contiguous (0 to n) spread over however many grids.

    Default is None.

input_data#

The raw EMG data. The shape of the array should be (n_channels, n_samples) or (n_chunks, n_channels, n_samples).

Type:

np.ndarray

sampling_frequency#

The sampling frequency of the EMG data.

Type:

float

grid_layouts#

List of 2D arrays specifying the exact electrode arrangement for each grid. Each array element contains the electrode index (0-based).

Type:

Optional[List[np.ndarray]]

processed_data#

A dictionary where the keys are the names of filters applied to the EMG data and the values are the processed EMG data.

Type:

Dict[str, np.ndarray]

Raises:

ValueError – If the shape of the raw EMG data is not (n_channels, n_samples) or (n_chunks, n_channels, n_samples). If the grid layouts are not provided or are not valid.

Parameters:

Examples

>>> import numpy as np
>>> from myoverse.datatypes import EMGData, create_grid_layout
>>>
>>> # Create sample EMG data (16 channels, 1000 samples)
>>> emg_data = np.random.randn(16, 1000)
>>> sampling_freq = 2000  # 2000 Hz
>>>
>>> # Create a basic EMGData object
>>> emg = EMGData(emg_data, sampling_freq)
>>>
>>> # Create an EMGData object with grid layouts
>>> # Define a 4×4 electrode grid with row-wise numbering
>>> grid = create_grid_layout(4, 4, fill_pattern='row')
>>> emg_with_grid = EMGData(emg_data, sampling_freq, grid_layouts=[grid])

Working with Multiple Grid Layouts#

Grid layouts enable precise specification of how electrodes are arranged physically. This is especially useful for visualizing and analyzing high-density EMG recordings with multiple electrode grids:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from myoverse.datatypes import EMGData, create_grid_layout
>>>
>>> # Create sample EMG data for 61 electrodes with 1000 samples each
>>> emg_data = np.random.randn(61, 1000)
>>> sampling_freq = 2048  # Hz
>>>
>>> # Create layouts for three different electrode grids
>>> # First grid: 5×5 array with sequential numbering (0-24)
>>> grid1 = create_grid_layout(5, 5, fill_pattern='row')
>>>
>>> # Second grid: 6×6 array with column-wise numbering
>>> grid2 = create_grid_layout(6, 6, fill_pattern='column')
>>> # Shift indices to start after the first grid (add 25)
>>> grid2[grid2 >= 0] += 25
>>>
>>> # Third grid: Irregular 3×4 array
>>> grid3 = create_grid_layout(3, 4, fill_pattern='row')
>>> grid3[grid3 >= 0] += 50
>>>
>>> # Create EMGData with all three grids
>>> emg = EMGData(emg_data, sampling_freq, grid_layouts=[grid1, grid2, grid3])
>>>
>>> # Visualize the three grid layouts
>>> for i in range(3):
...     emg.plot_grid_layout(i)
>>>
>>> # Plot the raw EMG data using the grid arrangements
>>> emg.plot('Input', scaling_factor=[15.0, 12.0, 20.0])
>>>
>>> # Access individual grid dimensions
>>> grid_dimensions = emg._get_grid_dimensions()
>>> for i, (rows, cols, electrodes) in enumerate(grid_dimensions):
...     print(f"Grid {i+1}: {rows}×{cols} with {electrodes} electrodes")

Methods

__init__(input_data, sampling_frequency[, ...])

_get_grid_dimensions()

Get dimensions and electrode counts for each grid.

plot(representation[, nr_of_grids, ...])

Plots the data for a specific representation.

plot_grid_layout([grid_idx, show_indices, ...])

Plots the 2D layout of a specific electrode grid with enhanced visualization.
plot(representation, nr_of_grids=None, nr_of_electrodes_per_grid=None, scaling_factor=20.0, use_grid_layouts=True)[source]#

Plots the data for a specific representation.

Parameters:

  • representation (str) – The representation to plot.

  • nr_of_grids (Optional[int], optional) – The number of electrode grids to plot. If None and grid_layouts is provided, will use the number of grids in grid_layouts. Default is None.

  • nr_of_electrodes_per_grid (Optional[int], optional) – The number of electrodes per grid to plot. If None, will be determined from data shape or grid_layouts if available. Default is None.

  • scaling_factor (Union[float, List[float]], optional) – The scaling factor for the data. The default is 20.0. If a list is provided, the scaling factor for each grid is used.

  • use_grid_layouts (bool, optional) – Whether to use the grid_layouts for plotting. Default is True. If False, will use the nr_of_grids and nr_of_electrodes_per_grid parameters.

Examples

>>> import numpy as np
>>> from myoverse.datatypes import EMGData, create_grid_layout
>>>
>>> # Create sample EMG data (64 channels, 1000 samples)
>>> emg_data = np.random.randn(64, 1000)
>>>
>>> # Create EMGData with two 4×8 grids (32 electrodes each)
>>> grid1 = create_grid_layout(4, 8, 32, fill_pattern='row')
>>> grid2 = create_grid_layout(4, 8, 32, fill_pattern='row')
>>>
>>> # Adjust indices for second grid
>>> grid2[grid2 >= 0] += 32
>>>
>>> emg = EMGData(emg_data, 2000, grid_layouts=[grid1, grid2])
>>>
>>> # Plot the raw data using the grid layouts
>>> emg.plot('Input')
>>>
>>> # Adjust scaling for better visualization
>>> emg.plot('Input', scaling_factor=[15.0, 25.0])
>>>
>>> # Plot without using grid layouts (specify manual grid configuration)
>>> emg.plot('Input', nr_of_grids=2, nr_of_electrodes_per_grid=32,
...         use_grid_layouts=False)
plot_grid_layout(grid_idx=0, show_indices=True, cmap=None, figsize=None, title=None, colorbar=True, grid_color='black', grid_alpha=0.7, text_color='white', text_fontsize=10, text_fontweight='bold', highlight_electrodes=None, highlight_color='red', save_path=None, dpi=150, return_fig=False, ax=None, autoshow=True)[source]#

Plots the 2D layout of a specific electrode grid with enhanced visualization.

Parameters:

  • grid_idx (int, optional) – The index of the grid to plot. Default is 0.

  • show_indices (bool, optional) – Whether to show the electrode indices in the plot. Default is True.

  • cmap (Optional[plt.cm.ScalarMappable], optional) – Custom colormap to use for visualization. If None, a default viridis colormap is used.

  • figsize (Optional[Tuple[float, float]], optional) – Custom figure size as (width, height) in inches. If None, size is calculated based on grid dimensions. Ignored if an existing axes object is provided.

  • title (Optional[str], optional) – Custom title for the plot. If None, a default title showing grid dimensions is used.

  • colorbar (bool, optional) – Whether to show a colorbar. Default is True.

  • grid_color (str, optional) – Color of the grid lines. Default is “black”.

  • grid_alpha (float, optional) – Transparency of grid lines (0-1). Default is 0.7.

  • text_color (str, optional) – Color of the electrode indices text. Default is “white”.

  • text_fontsize (int, optional) – Font size for electrode indices. Default is 10.

  • text_fontweight (str, optional) – Font weight for electrode indices. Default is “bold”.

  • highlight_electrodes (Optional[List[int]], optional) – List of electrode indices to highlight. Default is None.

  • highlight_color (str, optional) – Color to use for highlighting electrodes. Default is “red”.

  • save_path (Optional[str], optional) – Path to save the figure. If None, figure is not saved. Default is None.

  • dpi (int, optional) – DPI for saved figure. Default is 150.

  • return_fig (bool, optional) – Whether to return the figure and axes. Default is False.

  • ax (Optional[plt.Axes], optional) – Existing axes object to plot on. If None, a new figure and axes will be created.

  • autoshow (bool, optional) – Whether to automatically show the figure. Default is True. Set to False when plotting multiple grids on the same figure.

Returns:

Figure and axes objects if return_fig is True.

Return type:

Optional[Tuple[plt.Figure, plt.Axes]]

Raises:

ValueError – If grid_layouts is not available or the grid_idx is out of range.

Examples

>>> import numpy as np
>>> from myoverse.datatypes import EMGData, create_grid_layout
>>>
>>> # Create sample EMG data (64 channels, 1000 samples)
>>> emg_data = np.random.randn(64, 1000)
>>>
>>> # Create an 8×8 grid with some missing electrodes
>>> grid = create_grid_layout(8, 8, 64, fill_pattern='row',
...                          missing_indices=[(7, 7), (0, 0)])
>>>
>>> emg = EMGData(emg_data, 2000, grid_layouts=[grid])
>>>
>>> # Basic visualization
>>> emg.plot_grid_layout(0)
>>>
>>> # Advanced visualization
>>> emg.plot_grid_layout(
...     0,
...     figsize=(10, 10),
...     colorbar=True,
...     highlight_electrodes=[10, 20, 30],
...     grid_alpha=0.5
... )
>>>
>>> # Multiple grids in one figure
>>> import matplotlib.pyplot as plt
>>> fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))
>>> emg.plot_grid_layout(0, title="Grid 1", ax=ax1, autoshow=False)
>>> emg.plot_grid_layout(1, title="Grid 2", ax=ax2, autoshow=False)
>>> plt.tight_layout()
>>> plt.show()