SurfaceEMG

class SurfaceEMG(

muscle_model: Muscle,

electrode_arrays: list[SurfaceElectrodeArray],

sampling_frequency__Hz: Quantity__Hz = 2048.0 * pq.Hz,

sampling_points_in_t_and_z_domains: int = 256,

sampling_points_in_theta_domain: int = 32,

MUs_to_simulate: list[int] | None = None,

internal_sampling_frequency__Hz: Quantity__Hz | None = None,

iap_kernel_length__mm: float | None = None,

)

Bases: object

Surface Electromyography (sEMG) Simulation.

This class provides a simulation framework for generating surface electromyography signals from the muscle. It implements the multi-layered cylindrical volume conductor model from Farina et al. 2004 [1].

Parameters:

• muscle_model (Muscle) – Pre-computed muscle model (see myogen.simulator.Muscle).

• electrode_arrays (list[SurfaceElectrodeArray]) – List of electrode arrays to use for simulation (see myogen.simulator.SurfaceElectrodeArray).

• sampling_frequency__Hz (float, default=2048.0) – Sampling frequency in Hz. Default is set to 2048 Hz as used by the Quattrocento (OT Bioelettronica, Turin, Italy) system.

• sampling_points_in_t_and_z_domains (int, default=256) – Spatial and temporal discretization resolution for numerical integration. Controls the accuracy of the volume conductor calculations but significantly impacts computational cost (scales quadratically). Higher values provide better numerical accuracy at the expense of simulation time. Default is set to 256 samples.

• sampling_points_in_theta_domain (int, default=32) – Angular discretization for cylindrical coordinate system in degrees. Higher values provide better spatial resolution but cause numerical overflow in Bessel functions. Default is set to 32 points to avoid numerical instability. WARNING: Values >64 cause extreme Bessel function overflow leading to incorrect results. This is suitable for most EMG studies.

• MUs_to_simulate (list[int], optional) – Indices of motor units to simulate. If None, all motor units are simulated. Default is None. For computational efficiency, consider simulating subsets for initial analysis. Indices correspond to the recruitment order (0 is recruited first).

• internal_sampling_frequency__Hz (Quantity__Hz, optional) – Internal sampling frequency for MUAP computation before downsampling. If None, defaults to 10 kHz. Higher values provide better temporal resolution but increase computation time. Default is 10 kHz.

• iap_kernel_length__mm (float, optional) –

  Physical spatial extent for intracellular action potential (IAP) kernel evaluation in mm. If None (default), uses individual fiber lengths from muscle model, ensuring MUAP duration is physiologically accurate and independent of sampling resolution.

  Recommended: Leave as None to use fiber-specific lengths for most realistic MUAPs.

  Alternatively, set to a fixed value (e.g., 80-100 mm) to use the same kernel extent for all fibers, which can simplify analysis but may be less physiologically accurate for muscles with variable fiber lengths.

  This parameter controls the spatial extent over which the IAP waveform is computed, directly affecting MUAP duration: duration ≈ iap_kernel_length__mm / (2 * v) ms.

muaps__Block

Motor Unit Action Potential (MUAP) templates for each electrode array as a neo.Block. Available after simulate_muaps().

Type:

SURFACE_MUAP__Block

surface_emg__Block

Surface EMG signals for each electrode array as a neo.Block. Available after simulate_surface_emg().

Type:

SURFACE_EMG__Block

noisy_surface_emg__Block

Noisy surface EMG signals for each electrode array as a neo.Block. Available after add_noise().

Type:

SURFACE_EMG__Block

spike_train__Block

Spike train block used for EMG generation signals. Available after simulate_surface_emg().

Type:

SPIKE_TRAIN__Block

References

[1]

Farina, D., Mesin, L., Martina, S., Merletti, R., 2004. A surface EMG generation model with multilayer cylindrical description of the volume conductor. IEEE Transactions on Biomedical Engineering 51, 415–426. https://doi.org/10.1109/TBME.2003.820998

Methods

__init__
add_noise	Add noise to all electrode arrays.
simulate_muaps	Simulate MUAPs for all electrode arrays using the provided muscle model.
simulate_surface_emg	Generate surface EMG signals for all electrode arrays using the provided spike train block.

Attributes

muaps__Block	Motor Unit Action Potential (MUAP) templates for each electrode array.
noisy_surface_emg__Block	Noisy surface EMG signals for each electrode array.
spike_train__Block	Spike train block used for EMG generation.
surface_emg__Block	Surface EMG signals for each electrode array stored in a neo.Block.

simulate_muaps(

n_jobs: int = -2,

) → SURFACE_EMG__Block

Simulate MUAPs for all electrode arrays using the provided muscle model.

This method generates Motor Unit Action Potential (MUAP) templates that represent the electrical signature of each motor unit as recorded by the surface electrodes. The simulation uses the multi-layered cylindrical volume conductor model with parallel processing for improved performance.

Parameters:

n_jobs (int, optional) – Number of parallel workers for motor unit processing. Default is -2. - n_jobs=-1: Use all CPU cores - n_jobs=-2: Use all cores except one (recommended, keeps system responsive) - n_jobs=-3: Use all cores except two - n_jobs=1: No parallelization - n_jobs=N: Use exactly N cores

Returns:

neo.Block of generated MUAP templates for each electrode array. Results are stored in the muaps property after execution.

Return type:

SURFACE_MUAP__Block

Notes

This method must be called before simulate_surface_emg(). The generated MUAP templates are used as basis functions for EMG signal synthesis.

The motor units are processed in parallel using joblib, with each motor unit’s fibers processed sequentially to maintain optimization efficiency.

simulate_surface_emg(

spike_train__Block: SPIKE_TRAIN__Block,

) → SURFACE_EMG__Block

Generate surface EMG signals for all electrode arrays using the provided spike train block.

This method convolves the pre-computed MUAP templates with the spike trains to synthesize realistic surface EMG signals. The process includes temporal resampling to match the spike train timestep and supports both CPU and GPU acceleration.

Parameters:

spike_train__Block (SPIKE_TRAIN__Block) – Block containing spike trains organized as segments (pools) with spiketrains.

Returns:

Surface EMG signals for each electrode array stored in a neo.Block. Results are stored in the surface_emg__tensors property after execution.

Return type:

SURFACE_EMG__Block

Raises:

ValueError – If MUAP templates have not been generated. Call simulate_muaps() first.

add_noise(

snr__dB: float,

noise_type: str = 'gaussian',

) → SURFACE_EMG__Block

Add noise to all electrode arrays.

This method adds realistic noise to the simulated surface EMG signals based on a specified signal-to-noise ratio. The noise is calculated and applied independently for each electrode channel to ensure that channels with different signal amplitudes maintain the specified SNR.

Parameters:

• snr__dB (float) – Signal-to-noise ratio in dB. Higher values result in cleaner signals. Typical physiological EMG has SNR ranging from 10-40 dB. The SNR is applied independently to each electrode channel.

• noise_type (str, default="gaussian") – Type of noise to add. Currently supports “gaussian” for white noise.

Returns:

Noisy EMG signals for each electrode array as a neo.Block. Results are stored in the noisy_surface_emg__Block property after execution.

Return type:

SURFACE_EMG__Block

Raises:

ValueError – If surface EMG has not been simulated. Call simulate_surface_emg() first.

Notes

The noise is computed per-channel (per electrode) to maintain the specified SNR independently across all channels. This ensures that electrodes with different signal amplitudes receive appropriately scaled noise.

property muaps__Block: segments))]]

Motor Unit Action Potential (MUAP) templates for each electrode array.

Returns:

List of MUAP templates for each electrode array.

Return type:

list[SURFACE_MUAP_SHAPE__TENSOR]

Raises:

ValueError – If MUAP templates have not been computed yet.

property surface_emg__Block: segments))]]

Surface EMG signals for each electrode array stored in a neo.Block.

Returns:

Surface EMG signals for each electrode array stored in a neo.Block.

Return type:

SURFACE_EMG__Block

Raises:

ValueError – If surface EMG has not been computed yet.

property noisy_surface_emg__Block: segments))]]

Noisy surface EMG signals for each electrode array.

Returns:

Noisy surface EMG signals for each electrode array.

Return type:

SURFACE_EMG__Block

Raises:

ValueError – If noisy surface EMG has not been computed yet.

property spike_train__Block: segments))]]

Spike train block used for EMG generation.

Returns:

The spike train block used in the simulation.

Return type:

SPIKE_TRAIN__Block

Raises:

ValueError – If spike train block has not been set yet.