Skip to content

Decomposition Results

The Decomposition Results step provides tools for processing, manually cleaning, and visualizing motor unit decomposition results. It supports both automated visualization and manual quality control workflows using MUEdit.

Overview

This step provides three main workflows:

  1. File Mapping: Associate decomposition results with their source channel selection files
  2. Manual Cleaning: Export results to MUEdit format for manual inspection and editing
  3. Visualization: View processed results in openhdemg

Interface Components

Main Buttons

  • Apply Mapping: Opens a dialog to create mappings between decomposition and channel selection files
  • Export to MUEdit: Converts openhdemg JSON files to MUEdit MAT format
  • Open MUEdit: Launches MUEdit for manual cleaning of decomposition results
  • Show Decomposition Results: Launches openhdemg to visualize the processed results

File Watcher

The system automatically monitors the decomposition folder for: - .json files (openhdemg decomposition results) - .pkl files (pickle format decomposition results) - *_muedit.mat files (exported for manual cleaning) - Edited result files (saved from MUEdit)

Buttons are automatically enabled/disabled based on detected file types.

Mapping Process

Opening the Mapping Dialog

The mapping dialog provides a user-friendly interface to create 1:1 mappings between: - Decomposition result files (.json, .pkl) - Channel selection files (.mat)

Mapping Dialog

Dialog Components

  • Left List: Shows available decomposition files
  • Right List: Shows available channel selection files
  • Add Mapping Button: Creates a mapping between selected files
  • Mapping Table: Displays current mappings
  • OK/Cancel Buttons: Confirm or discard mappings

Creating Mappings

  1. Select a decomposition file from the left list
  2. Select a corresponding channel selection file from the right list
  3. Click "Add Mapping" to create the association
  4. The mapping appears in the table below
  5. Repeat for all required files
  6. Click OK to save mappings

Validation Rules

  • Each decomposition file can only be mapped once
  • Each channel selection file can only be mapped once
  • Both files must be selected to create a mapping
  • Existing mappings are preserved and can be extended

File Processing

Automatic Processing

When mappings are confirmed: 1. Each decomposition file is processed with its corresponding channel selection 2. The system updates metadata in the result files 3. Progress is tracked and displayed

File Types

The system handles different file formats: - .pkl files: Updated using update_extras_in_pickle_file - .json files: Updated using update_extras_in_json_file

Error Handling

The system provides feedback for common issues: - Missing files - Processing errors - Invalid mappings - File access problems

Manual Cleaning Workflow (MUEdit)

The application provides integrated support for manual quality control of decomposition results using MUEdit, a MATLAB-based tool for visual inspection and editing of motor unit decompositions.

MUEdit Repository: https://github.com/haripen/MUedit/tree/devHP

Workflow Overview

The manual cleaning workflow consists of three stages:

  1. Export: Convert openhdemg JSON files to MUEdit MAT format
  2. Edit: Manually inspect and clean results in MUEdit
  3. Track: Monitor progress as files are processed

Stage 1: Export to MUEdit Format

File Format Requirements

The application expects decomposition results in one of the following formats:

  • openhdemg JSON format (.json): Standard output from openhdemg decomposition
  • MUEdit MAT format (*_muedit.mat): Ready for loading into MUEdit

The pipeline automatically detects which format your files are in.

Exporting JSON Files

If you have openhdemg JSON files:

  1. Click "Export to MUEdit" button
  2. The system converts each .json file to *_muedit.mat or *_multigrid_muedit.mat format
  3. Export progress is displayed with success/error counts
  4. Files already exported are automatically skipped

What happens during export: - Raw EMG signal data is extracted and transposed - Motor unit pulse trains are normalized - Discharge times are converted to 1-indexed MATLAB format - Grid information and metadata are preserved - Files are saved with MATLAB compression - Multi-grid recordings: Automatically detected and exported with proper grid metadata

Button behavior: - Enabled when JSON files without corresponding *_muedit.mat or *_multigrid_muedit.mat files are detected - Disabled when all JSON files already have MUEdit exports

Multi-Grid Support (New in v0.1.0+)

The export function now supports multi-grid recordings with automatic detection:

Single-Grid Export: - Files with one electrode grid are exported as filename_muedit.mat - Uses traditional single-grid structure

Multi-Grid Export: - Files with multiple electrode grids are automatically detected from EXTRAS field - Exported as filename_multigrid_muedit.mat - Includes grid-specific metadata for each electrode array: - Grid names and muscle labels - Inter-electrode distances (IED) per grid - Channel coordinates per grid - EMG channel masks per grid - Enables MUEdit's cross-grid duplicate detection: Identify and merge duplicate motor units detected by multiple grids

How Multi-Grid Detection Works: 1. The system reads the EXTRAS field from the decomposition JSON 2. Extracts grid information from the grid association step 3. Populates MUEdit structure with per-grid metadata 4. Creates proper cell arrays for coordinates, IED, EMGmask, etc.

Benefits: - Leverages MUEdit's native multi-grid capabilities - Enables cross-grid duplicate motor unit detection - Preserves spatial relationships between grids - More accurate decomposition results for multi-grid recordings

Note: Currently, all motor units are assigned to the first grid in the export. Future versions will support per-grid MU assignment when decomposition algorithms provide this information.

Stage 2: Launch MUEdit

Configuration (Settings)

Before launching MUEdit, configure the integration in Settings > MUEdit Configuration:

MUEdit Installation Path: - Specify the folder containing MUEdit MATLAB files (e.g., MUedit_exported.m) - This path is added to MATLAB's search path when launching - The application checks if the path is already present to avoid duplicates

Launch Method: - AUTO (recommended): Automatically tries all available methods - MATLAB Engine API: Reuses existing MATLAB sessions (requires pip install matlabengine) - MATLAB CLI: Starts a new MATLAB process (requires MATLAB in PATH) - Standalone: Launches MUEdit as a standalone executable

Launching MUEdit

  1. Click "Open MUEdit" button (enabled when *_muedit.mat files are detected)
  2. The application attempts to launch MUEdit using the configured method
  3. An instruction dialog appears with workflow guidance

Launch methods tried in AUTO mode: 1. MATLAB Engine (best - reuses session, avoids repeated path additions) 2. MATLAB CLI (starts new session with path check) 3. Standalone (executable mode)

Path Management: - MATLAB Engine: Checks current MATLAB path before adding MUEdit path - MATLAB CLI: Uses contains(path, ...) to avoid duplicate path entries - Prevents accumulation of duplicate paths across multiple launches

Stage 3: Instruction Dialog & Live Tracking

When MUEdit launches, an interactive instruction dialog guides you through the workflow.

MUedit Dialog

Dialog Features

Step-by-Step Instructions: 1. Load the highlighted file in MUEdit 2. Review and manually clean the motor unit decomposition 3. Save the file in MUEdit 4. Progress updates automatically when you save 5. Repeat for all remaining files

Live Progress Tracking: - File Status List: Shows all files with ✅ (completed) or ⏳ (pending) status - Next File to Edit: Highlights the next file that needs processing - Copyable Path: One-click copy of the full file path for easy loading - Live Indicator: Blinks to show the dialog is monitoring for changes - Auto-Update: Refreshes every 2 seconds to detect newly saved files

Progress Detection

The application automatically detects when you save edited files:

  • Monitors the decomposition folder for new .mat files
  • Recognizes edited files based on the base filename
  • Flexible naming: any .mat file containing the base name is detected as edited
  • Visual/audio feedback when a file is completed
  • Progress percentage updates in real-time

Example file flow:

Original:     filename.json
Exported:     filename_muedit.mat      (ready for editing)
Edited:       filename_*.mat           (saved from MUEdit, detected automatically)

Note: The exact naming of edited files may vary depending on your MUEdit version. The pipeline automatically detects any .mat file that matches the base filename.

Completion

When all files are cleaned: - Dialog shows "🎉 All files have been cleaned!" - Progress bar reaches 100% - Success message displayed

Result Visualization

openhdemg Integration

To view results: 1. Click "Show Decomposition Results" 2. The system launches openhdemg application 3. Results are automatically loaded 4. The button shows a loading animation during startup

Requirements

  • openhdemg virtual environment must be configured in Settings
  • The path must be valid and accessible
  • Python environment must include required dependencies

Configuration

Required Settings

In the application settings:

Settings > openhdemg Virtual Environment Path

File Paths

The system uses several important paths: - Decomposition results folder - Channel selection folder - openhdemg virtual environment

Best Practices

  1. Before Processing
  2. Ensure all decomposition results are available
  3. Verify channel selection files are in place
  4. Check openhdemg configuration

  5. Configure MUEdit settings if planning manual workflow

  6. During Mapping

  7. Create mappings systematically
  8. Verify mappings before confirming

  9. Monitor processing progress

  10. Manual Cleaning Workflow

  11. Recommended: Install MATLAB Engine API (pip install matlabengine) for best performance
  12. Configure MUEdit path in Settings before first use
  13. Export all files before starting manual cleaning
  14. Keep the instruction dialog open while working in MUEdit
  15. Save files in MUEdit after each edit to trigger progress tracking

  16. Work sequentially through files using the "Next File" guidance

  17. Viewing Results

  18. Wait for processing to complete
  19. Ensure openhdemg launches successfully
  20. Check for any error messages

Troubleshooting

Common Issues

  1. Missing Files
  2. Verify decomposition results are in the correct folder
  3. Check channel selection files are available

  4. Ensure file permissions are correct

  5. openhdemg Issues

  6. Verify virtual environment path
  7. Check Python dependencies

  8. Monitor application logs

  9. Processing Errors

  10. Check file format compatibility
  11. Verify file contents

  12. Review error messages in application logs

  13. MUEdit Launch Issues

  14. "MATLAB Engine API not available": Install with pip install matlabengine
  15. "MATLAB executable not found in PATH": Add MATLAB to system PATH or use Engine mode
  16. "Failed to launch using any available method":
    • Check MATLAB installation
    • Verify MUEdit path in Settings
    • Try manual MATLAB launch and then use Engine mode

  17. "MUEdit path not set": Configure in Settings > MUEdit Configuration

  18. Export Issues

  19. "No JSON files found": Only .json files can be exported to MUEdit format
  20. "openhdemg library not available": Install openhdemg via Settings
  21. Export button disabled: All JSON files already have *_muedit.mat or *_multigrid_muedit.mat exports
  22. Multi-grid detection issues: Check that EXTRAS field contains proper grid metadata from grid association step

  23. "No 'grids' list found in EXTRAS": The decomposition file may not have been created from a grid-associated file

  24. Progress Tracking Issues

  25. Files not detected after saving: Check file naming contains the base filename
  26. Live indicator not updating: Dialog auto-refreshes every 2 seconds, wait briefly
  27. Edited file not recognized: Ensure the saved .mat file contains the original base name

Error Messages

Common error messages and solutions:

  • "openhdemg virtual environment path is not set"
  • Configure the path in Settings

  • Verify the environment exists

  • "The decomposition folder does not exist"

  • Check folder structure
  • Verify workspace configuration

  • Ensure previous steps completed successfully

  • "MATLAB Engine API not available"

  • Install MATLAB Engine: pip install matlabengine

  • Or switch to CLI/Standalone mode in Settings

  • "Failed to launch via MATLAB Engine/CLI/Standalone"

  • AUTO mode will try all methods sequentially
  • Check specific launch method configuration
  • Verify MATLAB installation and PATH

Next Steps

After completing this step:

If Using Manual Cleaning Workflow:

  1. Verify all files are exported to MUEdit format
  2. Complete manual cleaning of all files in MUEdit
  3. Confirm all files show ✅ status in the progress dialog
  4. View cleaned results in openhdemg

If Using Direct Visualization:

  1. Verify all mappings are processed
  2. Check results in openhdemg
  3. Export or save final results as needed

Additional Resources