.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/03_simulate_surface_muaps.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_03_simulate_surface_muaps.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_03_simulate_surface_muaps.py:


Surface Motor Unit Action Potentials
====================================

After having created the **muscle model**, we can simulate the **surface EMG** by creating a **surface EMG model**.

First step is to create **MUAPs** from the **muscle model**.

.. note::
    The **MUAPs** are the **action potentials** of the **motor units** at the surface of the skin.

.. GENERATED FROM PYTHON SOURCE LINES 12-22

.. code-block:: Python


    from pathlib import Path

    import joblib
    import matplotlib.pyplot as plt
    import numpy as np

    from myogen import simulator
    from myogen.utils.plotting import plot_muap_grid








.. GENERATED FROM PYTHON SOURCE LINES 23-36

Define Parameters
-----------------

The **surface EMG** is created using the **SurfaceEMG** object.

The **SurfaceEMG** object takes the following parameters:

- ``muscle_model``: Muscle model
- ``sampling_frequency``: Sampling frequency
- ``electrode_grid_dimensions``: Electrode grid dimensions
- ``inter_electrode_distance``: Inter-electrode distance
- ``fat_thickness``: Fat thickness
- ``skin_thickness``: Skin thickness

.. GENERATED FROM PYTHON SOURCE LINES 36-46

.. code-block:: Python


    # Define simulation parameters
    sampling_frequency = 2048.0  # Hz - standard for surface EMG
    electrode_grid_size = (5, 5)
    inter_electrode_distance = 4.0  # mm - standard spacing

    # Define volume conductor parameters
    fat_thickness = 1.0  # mm
    skin_thickness = 1.0  # mm








.. GENERATED FROM PYTHON SOURCE LINES 47-51

Load Muscle Model
----------------------------

Load muscle model from previous example

.. GENERATED FROM PYTHON SOURCE LINES 51-55

.. code-block:: Python


    save_path = Path("./results")
    muscle = joblib.load(save_path / "muscle_model.pkl")








.. GENERATED FROM PYTHON SOURCE LINES 56-67

Create Surface EMG Model
-------------------------

The **SurfaceEMG** object is initialized with the **muscle model** and the **simulation parameters**.

.. note::
   For simplicity, we only simulate the first motor unit.
   This can be changed by modifying the ``MUs_to_simulate`` parameter.

  This is to simulate the **surface EMG** from two different directions.


.. GENERATED FROM PYTHON SOURCE LINES 67-79

.. code-block:: Python


    surface_emg = simulator.SurfaceEMG(
        muscle_model=muscle,
        sampling_frequency__Hz=sampling_frequency,
        electrode_grid_dimensions__rows_cols=electrode_grid_size,
        inter_electrode_distance__mm=inter_electrode_distance,
        MUs_to_simulate=[0],
        electrode_grid_center_positions=[(0, 0)],
        fat_thickness__mm=fat_thickness,
        skin_thickness__mm=skin_thickness,
    )








.. GENERATED FROM PYTHON SOURCE LINES 80-84

Simulate MUAPs
--------------

To generate the **MUAPs**, we need to run the ``simulate_muaps`` method of the **SurfaceEMG** object.

.. GENERATED FROM PYTHON SOURCE LINES 84-99

.. code-block:: Python



    # Run simulation with progress output
    muaps = surface_emg.simulate_muaps(show_plots=False, verbose=False)

    print(f"\nMUAP simulation completed!")
    print(f"Generated MUAPs shape: {muaps.shape}")
    print(f"  - {muaps.shape[0]} electrode position(s)")
    print(f"  - {muaps.shape[1]} motor units")
    print(f"  - {muaps.shape[2]}×{muaps.shape[3]} electrode grid")
    print(f"  - {muaps.shape[4]} time samples")

    # Save results
    joblib.dump(surface_emg, save_path / "surface_emg.pkl")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    MU 1 Position 1:   0%|          | 0/5 [00:00<?, ?it/s]
    MU 1 Position 1:  20%|██        | 1/5 [00:00<00:00,  4.34it/s]
    MU 1 Position 1:  40%|████      | 2/5 [00:00<00:00,  6.09it/s]
    MU 1 Position 1:  60%|██████    | 3/5 [00:00<00:00,  6.99it/s]
    MU 1 Position 1:  80%|████████  | 4/5 [00:00<00:00,  7.51it/s]
    MU 1 Position 1: 100%|██████████| 5/5 [00:00<00:00,  7.83it/s]
    MU 1 Position 1: 100%|██████████| 5/5 [00:00<00:00,  7.12it/s]

    MUAP simulation completed!
    Generated MUAPs shape: (1, 1, 5, 5, 256)
      - 1 electrode position(s)
      - 1 motor units
      - 5×5 electrode grid
      - 256 time samples

    ['results/surface_emg.pkl']



.. GENERATED FROM PYTHON SOURCE LINES 100-108

Plot MUAPs
------------------------------------

The MUAPs can be plotted using the ``plot_muap_grid`` function.

.. note::
  **Plotting helper functions** are available in the ``myogen.utils.plotting`` module.
  The new API requires creating matplotlib axes and passing them to the plotting function.

.. GENERATED FROM PYTHON SOURCE LINES 108-138

.. code-block:: Python


    # Concatenate MUAPs from all electrode positions and motor units
    muaps_concatenated = np.concatenate(muaps)
    print(f"Concatenated MUAPs shape: {muaps_concatenated.shape}")

    # Create subplot grid for each MUAP (matches electrode grid layout)
    n_muaps = muaps_concatenated.shape[0]
    electrode_rows = muaps_concatenated.shape[1]
    electrode_cols = muaps_concatenated.shape[2]

    # Create axes for each MUAP - one subplot grid per MUAP
    axes_list = []
    for muap_idx in range(n_muaps):
        fig, axes = plt.subplots(
            electrode_rows,
            electrode_cols,
            figsize=(electrode_cols * 2, electrode_rows * 2),
            sharex=True,
            sharey=True,
        )
        fig.suptitle(f"MUAP {muap_idx}")
        axes_list.append(axes)

    # Plot MUAPs using the new API
    plot_muap_grid(
        muaps_concatenated[:, :, :, 100:-100], axes_list, apply_default_formatting=True
    )

    # Show all plots
    plt.show()



.. image-sg:: /auto_examples/images/sphx_glr_03_simulate_surface_muaps_001.png
   :alt: MUAP 0
   :srcset: /auto_examples/images/sphx_glr_03_simulate_surface_muaps_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Concatenated MUAPs shape: (1, 5, 5, 256)

    Plotting MUAPs:   0%|          | 0/1 [00:00<?, ?it/s]
    Plotting MUAPs: 100%|██████████| 1/1 [00:00<00:00,  6.24it/s]
    Plotting MUAPs: 100%|██████████| 1/1 [00:00<00:00,  6.23it/s]





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 1.102 seconds)


.. _sphx_glr_download_auto_examples_03_simulate_surface_muaps.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 03_simulate_surface_muaps.ipynb <03_simulate_surface_muaps.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 03_simulate_surface_muaps.py <03_simulate_surface_muaps.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 03_simulate_surface_muaps.zip <03_simulate_surface_muaps.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_