openfiles

Description¶

New in version 0.2.0

The recommended workflow for saving and loading openhdemg data now relies on the following high-level functions and classes for binary files:

save_openhdemg_module
asksavemodule
load_openhdemg_module
askloadmodule
openhdemg_Collection

This module contains all the functions that are necessary to open or save openhdemg binary files for modules and collections, in addition to MATLAB (.mat), text (.txt), JSON (.json) or custom (.csv) files. MATLAB files are used to store data from a number of software including DEMUSE, OTBiolab+ and Delsys, while JSON files are the older format used by the openhdemg library.

If you are using an openhdemg version >= 0.2, it is recommended to use binary data (modules and collections), as these provide the best performance and flexibility within the openhdemg framework, but also for optimal portability across operating systems and storage in private and public repositories. Indeed, our binary structures allow to compress files and check their integrity, if needed.

The content of the loaded emgfile can differ depending on the file type. In general, decomposed files are dictionaries containing the following keys:

"SOURCE" : source of the file (e.g., "OPENHDEMG", "CUSTOMCSV")
"FILENAME" : the name of the opened file
"RAW_SIGNAL" : the raw EMG signal
"REF_SIGNAL" : the reference signal
"ACCURACY" : accuracy score (depending on source file type)
"IPTS" : pulse train (decomposed source, depending on source file type)
"MUPULSES" : instants of firing
"FSAMP" : sampling frequency
"IED" : interelectrode distance
"EMG_LENGTH" : length of the emg file (in samples)
"NUMBER_OF_MUS" : total number of MUs
"BINARY_MUS_FIRING" : binary representation of MU firings
"EXTRAS" : additional custom values

More keys might be present if additional pd.DataFrames or Dictionaries are present in the emgfiles saved with 'save_emgfile_module'.

Similarly, less keys might be present if there is no decomposition result or no EMG signal.

As an example, when files are loaded with just the reference signal:

"SOURCE" : source of the file (i.e., "CUSTOMCSV_REFSIG", "OTB_REFSIG", "DELSYS_REFSIG")
"FILENAME" : the name of the opened file
"FSAMP" : sampling frequency
"REF_SIGNAL" : the reference signal
"EXTRAS" : additional custom values

Additional information can be found in the info module and in the function's description.

Structure of the emgfile

To really understand the official structure of the emgfile, all the users are encouraged to read the dedicated tutorial Structure of the emgfile.

`save_openhdemg_module(emgfile, path, module_name, filename=None, compresslevel=None, add_checksum=False)` ¶

Save an openhdemg module to a structured directory.

This function serialises an emgfile into a folder containing a manifest file (manifest.json) and binary uncompressed or gzip-compressed data files. It supports optional checksum generation and performs automatic overwriting of existing module directories.

PARAMETER	DESCRIPTION
`emgfile`	The dictionary containing the emgfile. TYPE: `dict`
`path`	Directory where the module folder should be created. The use of absolute paths should be preferred. TYPE: `str`
`module_name`	Name of the module folder to create under `path`. TYPE: `str`
`filename`	Optional filename to override the existing `emgfile["FILENAME"]`. TYPE: `str` DEFAULT: `None`
`compresslevel`	Compression level (0-9). If `None`, saves as raw binary files without compression. Saving the file without compression will allow for random access in the future (not yet implemented). Consider saving always uncompressed binary if you are working with large files. If you prefer working with compressed files to save space, we suggest using a `compresslevel=1`` for the best compression/performance balance. TYPE: `(None, int)` DEFAULT: `None`
`add_checksum`	If `True`, compute and store a SHA-256 checksum for each binary file to enable integrity verification on load. Default is `False`. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Path`	Path to the root directory where the openhdemg module has been saved.

See also

asksavemodule : Select the folder where to save the module with an UI and save it.

Notes

If a folder with the same module_name already exists at path, it will be completely overwritten.

The resulting folder contains:

.openhdemg_module : Marker file indicating an openhdemg module
manifest.json : Metadata and file index
files/ : Binary data files (optionally compressed)

`asksavemodule(emgfile, filename=None, compresslevel=None, add_checksum=False)` ¶

Select or create the folder where to save the module with an UI.

PARAMETER	DESCRIPTION
`emgfile`	The dictionary containing the emgfile. TYPE: `dict`
`filename`	Optional filename to override the existing `emgfile["FILENAME"]`. If `None`, the saving name will be used. TYPE: `str or None` DEFAULT: `None`
`compresslevel`	Compression level (0-9). If `None`, saves as raw binary files without compression. Saving the file without compression will allow for random access in the future (not yet implemented). Consider saving always uncompressed binary if you are working with large files. If you prefer working with compressed files to save space, we suggest using a `compresslevel=1`` for the best compression/performance balance. TYPE: `(None, int)` DEFAULT: `None`
`add_checksum`	If `True`, compute and store a SHA-256 checksum for each binary file to enable integrity verification on load. Default is `False`. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Path`	Path to the root directory where the openhdemg module has been saved.

See also

save_openhdemg_module : Save an openhdemg module to a structured directory.

Notes

If a folder with the same module_name already exists at path, it will be completely overwritten.

The resulting folder contains:

.openhdemg_module : Marker file indicating an openhdemg module
manifest.json : Metadata and file index
files/ : Binary data files (optionally compressed)

`load_openhdemg_module(path, module_name, verify_checksum=False, return_metadata=False)` ¶

Load an openhdemg module saved with save_openhdemg_module.

This function reconstructs the original emgfile dictionary (including pandas DataFrames and NumPy arrays) from the directory created by save_openhdemg_module. Optionally, it verifies the integrity of stored binary files using SHA-256 checksums if they are present in the manifest.

PARAMETER	DESCRIPTION
`path`	Directory containing the module folder. The use of absolute paths should be preferred. TYPE: `str`
`module_name`	Name of the module folder to load. The module folder is the one containing the module's `manifest.json` file and associated binary files. TYPE: `str`
`verify_checksum`	If `True`, verify SHA-256 checksums of all data files when present in the manifest. TYPE: `bool` DEFAULT: `False`
`return_metadata`	Whether to return the module metadata. If true, an additional object is returned. TYPE: `bool` DEFAULT: `False`

RETURNS DESCRIPTION

emgfile

A reconstructed dictionary representing the original emgfile. Keys and values mirror those in the saved structure, including:

- Scalar data (e.g. ``FSAMP``, ``EMG_LENGTH``)
- ``pandas.DataFrame`` objects
- Lists of NumPy array (``MUPULSES``)
- Other emgfile-related metadata from the manifest

TYPE: dict

metadata

This is returned only if return_metadata is True. An example of it content is:

- "created": "2025-10-06T15:36:11.084657+00:00",
- "system_byte_order": "little",
- "os": "Windows",
- "os_version": "10.0.19045",
- "platform": "Windows-10-10.0.19045-SP0",
- "python_version": "3.13.1",
- "openhdemg_version": "0.2.0-beta.1",
- "data_structure_version": "1.0"

TYPE: dict

See also

askloadmodule : Select the module folder to load with an UI.

RAISES	DESCRIPTION
`FileNotFoundError`	If the manifest file (`manifest.json`) is missing from the module directory.
`ValueError`	If `verify_checksum` is enabled and a checksum mismatch is detected.
`Warning`	If unexpected keys or malformed entries are found in the manifest.

`askloadmodule(verify_checksum=False, return_metadata=False, return_path=False)` ¶

Select the module folder to load with an UI and load it.

This function reconstructs the original emgfile dictionary (including pandas DataFrames and NumPy arrays) from the directory created by save_openhdemg_module. Optionally, it verifies the integrity of stored binary files using SHA-256 checksums if they are present in the manifest.

PARAMETER	DESCRIPTION
`verify_checksum`	If `True`, verify SHA-256 checksums of all data files when present in the manifest. TYPE: `bool` DEFAULT: `False`
`return_metadata`	Whether to return the module metadata. If true, an additional object is returned. TYPE: `bool` DEFAULT: `False`
`return_path`	Whether to return the path to the module, including module name. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`emgfile`	A reconstructed dictionary representing the original `emgfile`. Keys and values mirror those in the saved structure, including: - Scalar data (e.g. ``FSAMP``, ``EMG_LENGTH``) - ``pandas.DataFrame`` objects - Lists of NumPy array (``MUPULSES``) - Other emgfile-related metadata from the manifest TYPE: `dict`
`metadata`	This is returned only if `return_metadata` is `True`. An example of it content is: `- "created": "2025-10-06T15:36:11.084657+00:00", - "system_byte_order": "little", - "os": "Windows", - "os_version": "10.0.19045", - "platform": "Windows-10-10.0.19045-SP0", - "python_version": "3.13.1", - "openhdemg_version": "0.2.0-beta.1", - "data_structure_version": "1.0"` TYPE: `(dict, optional)`
`path`	The resolved (absolute) path to the module, including module name. This is returned only if `return_path` is `True`. TYPE: `(Path, optional)`

See also

load_openhdemg_module : Load an openhdemg module saved with save_openhdemg_module.

RAISES	DESCRIPTION
`FileNotFoundError`	If the manifest file (`manifest.json`) is missing from the module directory.
`ValueError`	If `verify_checksum` is enabled and a checksum mismatch is detected.
`RuntimeError`	If the selected directory is not a valid openhdemg module folder.
`Warning`	If unexpected keys or malformed entries are found in the manifest.

`openhdemg_Collection` ¶

A container for managing openhdemg collections.

This class represents a collection of openhdemg modules, along with shared data (e.g. reference signals) and participant metadata. It provides methods to set, retrieve, and reset each component, and to save/load the entire collection to disk in a structured and versioned format.

ATTRIBUTE	DESCRIPTION
`root`	Root directory where the collection is saved. TYPE: `Path or None`
`manifest_path`	Path to the manifest file (`manifest.json`). TYPE: `Path or None`
`marker_path`	Path to the marker file (`.openhdemg_collection`) identifying a valid collection directory. TYPE: `Path or None`
`modules`	Dictionary of openhdemg modules belonging to the collection. TYPE: `dict`
`shared_dataframe`	Shared data (e.g. reference or synchronisation signals). TYPE: `DataFrame or None`
`participant_info`	Dictionary containing participant-level metadata (e.g. ID, age, etc.). TYPE: `dict or None`
`manifest`	Dictionary describing the structure and metadata of the collection. TYPE: `dict`

METHOD	DESCRIPTION
`set_root`	Define the root directory for the collection.
`get_root`	Return the collection root path as a string.
`reset_root`	Reset root and related paths to None.
`set_shared_dataframe`	Assign a shared DataFrame for data common to all the modules.
`get_shared_dataframe`	Retrieve a deep copy of the shared DataFrame.
`reset_shared_dataframe`	Reset the shared DataFrame to None.
`set_participant_info`	Set and validate participant information (must be JSON serialisable).
`get_participant_info`	Retrieve a deep copy of participant information.
`reset_participant_info`	Reset the participant information to None.
`add_module`	Add a module to the collection.
`get_module`	Retrieve a module by name.
`remove_module`	Remove a module from the collection.
`save_module`	Save a single module to disk.
`save_shared_dataframe`	Save the shared DataFrame to disk and update the manifest.
`save_manifest`	Write the current manifest file (`manifest.json`).
`save`	Save the entire collection to disk, overwriting existing content.
`asksave`	Save the entire collection to disk using a UI to select the location.
`load_manifest`	Load the manifest file (manifest.json) and update internal metadata.
`load_module`	Load a specific module from disk and add it to the collection.
`load_shared_dataframe`	Load the shared DataFrame from disk and add it to the collection.
`load`	Load the entire openhdemg collection from disk.
`askload`	Load the entire openhdemg collection using an UI to select the directory.

`set_root(root)` ¶

Define the root directory for the collection.

PARAMETER	DESCRIPTION
`root`	Path to the root directory where the collection will be saved. TYPE: `str or Path`

`get_root()` ¶

Return the root directory.

RETURNS	DESCRIPTION
`str`	Absolute path of the collection root directory.

`reset_root()` ¶

Reset root and related paths to None.

`set_shared_dataframe(df)` ¶

Set the shared DataFrame for the collection.

This DataFrame should contain data that is common across modules (e.g. triggers, reference signals, synchronisation traces).

PARAMETER	DESCRIPTION
`df`	Shared data to attach to the collection. A deep copy is stored. TYPE: `DataFrame`

`get_shared_dataframe()` ¶

Get a deep copy of the shared DataFrame.

RETURNS	DESCRIPTION
`DataFrame or None`	The shared DataFrame, or `None` if not set.

`reset_shared_dataframe()` ¶

Reset the shared_dataframe to None.

`set_participant_info(info)` ¶

Set participant information and ensure it is JSON serialisable.

PARAMETER	DESCRIPTION
`info`	Dictionary containing participant details such as ID, age, height, weight, and notes. TYPE: `dict`

RAISES	DESCRIPTION
`TypeError`	If the dictionary is not JSON serialisable.

`get_participant_info()` ¶

Get a deep copy of participant information.

RETURNS	DESCRIPTION
`dict or None`	Participant information, or `None` if not set.

`reset_participant_info()` ¶

Reset the participant_info to None and update the manifest accordingly.

`add_module(module, module_name, replace=True)` ¶

Add a module to the collection.

PARAMETER	DESCRIPTION
`module`	Module data to add. TYPE: `dict`
`module_name`	Name of the module (used as an identifier). TYPE: `str`
`replace`	If `False`, a warning is raised and the module is not replaced when a module with the same name already exists. TYPE: `bool` DEFAULT: `True`

WARNS	DESCRIPTION
`UserWarning`	If `replace=False` and the module already exists.

`get_module(module_name)` ¶

Retrieve a module by name.

PARAMETER	DESCRIPTION
`module_name`	Name of the module. TYPE: `str`

RETURNS	DESCRIPTION
`dict or None`	A deep copy of the module dictionary, or `None` if not found.

`remove_module(module_name)` ¶

Remove a module from the collection and its reference from the manifest.

PARAMETER	DESCRIPTION
`module_name`	Name of the module to remove. TYPE: `str`

RETURNS	DESCRIPTION
`dict`	A deep copy of the removed module.

RAISES	DESCRIPTION
`KeyError`	If the key is not found.

`save_module(module_name, filename=None, compresslevel=None, add_checksum=False, save_updated_manifest=True)` ¶

Save an individual module to disk.

PARAMETER	DESCRIPTION
`module_name`	Name of the module to save. TYPE: `str`
`filename`	Optional filename to override the existing `emgfile["FILENAME"]`. TYPE: `str` DEFAULT: `None`
`compresslevel`	Compression level (0-9). If `None`, saves as raw binary files without compression. Saving the file without compression will allow for random access in the future (not yet implemented). Consider saving always uncompressed binary if you are working with large files. If you prefer working with compressed files to save space, we suggest using a `compresslevel=1`` for the best compression/performance balance. TYPE: `(None, int)` DEFAULT: `None`
`add_checksum`	If `True`, compute and store a SHA-256 checksum for each binary file to enable integrity verification on load. Default is `False`. TYPE: `bool` DEFAULT: `False`
`save_updated_manifest`	If True, automatically save also the updated manifest. If False, The user should take care of this by calling the `save_manifest` method. TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`ValueError`	If the module does not exist in the collection.

`save_shared_dataframe(compresslevel=None, add_checksum=False, save_updated_manifest=True)` ¶

Save the shared DataFrame to disk.

PARAMETER	DESCRIPTION
`compresslevel`	Compression level (0-9). If `None`, saves as raw binary files without compression. Saving the file without compression will allow for random access in the future (not yet implemented). Consider saving always uncompressed binary if you are working with large files. If you prefer working with compressed files to save space, we suggest using a `compresslevel=1`` for the best compression/performance balance. TYPE: `(None, int)` DEFAULT: `None`
`add_checksum`	If `True`, compute and store a SHA-256 checksum for each binary file to enable integrity verification on load. Default is `False`. TYPE: `bool` DEFAULT: `False`
`save_updated_manifest`	If True, automatically save also the updated manifest. If False, The user should take care of this by calling the `save_manifest` method. TYPE: `bool` DEFAULT: `True`

WARNS	DESCRIPTION
`UserWarning`	If no shared DataFrame is set or if it is empty.

`save_manifest()` ¶

Write the current manifest to disk in JSON format.

`save(update_filename=True, compresslevel=None, add_checksum=False)` ¶

Save the entire collection to disk.

Deletes any pre-existing content in the target directory if it is recognised as a valid openhdemg folder (checked via marker file).

PARAMETER	DESCRIPTION
`update_filename`	If True, override the existing `emgfile["FILENAME"]` for all modules to match module name. TYPE: `bool` DEFAULT: `True`
`compresslevel`	Compression level (0-9). If `None`, saves as raw binary files without compression. Saving the file without compression will allow for random access in the future (not yet implemented). Consider saving always uncompressed binary if you are working with large files. If you prefer working with compressed files to save space, we suggest using a `compresslevel=1`` for the best compression/performance balance. TYPE: `(None, int)` DEFAULT: `None`
`add_checksum`	If `True`, compute and store a SHA-256 checksum for each binary file to enable integrity verification on load. Default is `False`. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ValueError`	If root is not set or no modules have been added.
`RuntimeError`	If the target folder is not a safe openhdemg folder.

`asksave(update_filename=True, compresslevel=None, add_checksum=False)` ¶

Save the entire collection to disk using an UI to select the target directory.

Deletes any pre-existing content in the target directory if it is recognised as a valid openhdemg folder (checked via marker file).

PARAMETER	DESCRIPTION
`update_filename`	If True, override the existing `emgfile["FILENAME"]` for all modules to match module name. TYPE: `bool` DEFAULT: `True`
`compresslevel`	Compression level (0-9). If `None`, saves as raw binary files without compression. Saving the file without compression will allow for random access in the future (not yet implemented). Consider saving always uncompressed binary if you are working with large files. If you prefer working with compressed files to save space, we suggest using a `compresslevel=1`` for the best compression/performance balance. TYPE: `(None, int)` DEFAULT: `None`
`add_checksum`	If `True`, compute and store a SHA-256 checksum for each binary file to enable integrity verification on load. Default is `False`. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ValueError`	If root is not set or no modules have been added.
`RuntimeError`	If the target folder is not a safe openhdemg folder.

`load_manifest()` ¶

Load the manifest file (manifest.json) and update internal metadata.

RETURNS	DESCRIPTION
`dict`	Retrieve a deep copy of the loaded manifest dictionary.

RAISES	DESCRIPTION
`ValueError`	If `manifest_path` is not set (e.g. `set_root()` not called).
`FileNotFoundError`	If the manifest file path is set but the file does not exist.

`load_module(module_name, verify_checksum=False, return_metadata=False)` ¶

Load a specific module from disk and add it to the collection.

PARAMETER	DESCRIPTION
`module_name`	Name of the module folder to load. The module folder is the one containing the module's `manifest.json` file and associated binary files. TYPE: `str`
`verify_checksum`	If `True`, verify SHA-256 checksums of all data files when present in the manifest. TYPE: `bool` DEFAULT: `False`
`return_metadata`	Whether to return the module metadata. If true, an additional object is returned. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`dict or (dict, dict)`	The loaded module dictionary, or a tuple `(module, metadata)` if `return_metadata=True`.

RAISES	DESCRIPTION
`ValueError`	If the root is not set, if the manifest does not contain modules, if the specified module name is not listed in the manifest or if checksum verification fails.
`FileNotFoundError`	If the module file cannot be found at the expected path.

`load_shared_dataframe(verify_checksum=False)` ¶

Load the shared DataFrame from disk and add it to the collection.

PARAMETER	DESCRIPTION
`verify_checksum`	If `True`, verify SHA-256 checksums of all data files when present in the manifest. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`DataFrame`	A deep copy of the loaded shared DataFrame or None if not present.

RAISES	DESCRIPTION
`ValueError`	If the root is not set, if the manifest does not contain a `shared_dataframe` entry, or if checksum verification fails.
`FileNotFoundError`	If the binary file corresponding to the shared DataFrame cannot be found at the expected path.

`load(verify_checksum=False)` ¶

Load the entire openhdemg collection from disk.

This method loads the manifest and reconstructs all modules and the shared DataFrame into memory. Use load_module or load_shared_dataframe instead for selective loading.

PARAMETER	DESCRIPTION
`verify_checksum`	If `True`, verifies the integrity of all binary files against the checksums stored in the manifest. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ValueError`	If the root is not set or if the target folder is not recognised as a valid openhdemg collection (missing or invalid marker file).
`FileNotFoundError`	If the root directory or manifest file does not exist.

`askload(verify_checksum=False)` ¶

Load the entire openhdemg collection from disk using an UI to select the directory.

This method loads the manifest and reconstructs all modules and the shared DataFrame into memory. Use load_module or load_shared_dataframe instead for selective loading.

PARAMETER	DESCRIPTION
`verify_checksum`	If `True`, verifies the integrity of all binary files against the checksums stored in the manifest. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ValueError`	If the root is not set or if the target folder is not recognised as a valid openhdemg collection (missing or invalid marker file).
`FileNotFoundError`	If the root directory or manifest file does not exist.

`emg_from_samplefile()` ¶

Load the sample file. This file has been decomposed with the OTBiolab+ software and contains some reference MUs together with the force/reference signal.

This file contains only few MUs for storage reasons.

RETURNS	DESCRIPTION
`emgfile`	The dictionary containing the emgfile. TYPE: `dict`

`emg_from_otb(filepath, ext_factor=8, refsig=[True, 'fullsampled'], version='1.5.9.3', extras=None, ignore_negative_ipts=False)` ¶

Import the .mat file exportable from OTBiolab+.

This function is used to import the .mat file exportable by the OTBiolab+ software as a dictionary of Python objects (mainly pandas dataframes).

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`ext_factor`	The extension factor used for the decomposition in OTbiolab+. TYPE: `int` DEFAULT: `8`
`refsig`	Whether to seacrh also for the REF_SIGNAL and whether to load the full or sub-sampled one. The list is composed as [bool, str]. str can be "fullsampled" or "subsampled". Please read notes section. TYPE: `list` DEFAULT: `[True, "fullsampled"]`
`version`	Version of the OTBiolab+ software used (4 points). Tested versions are: "1.5.3.0", "1.5.4.0", "1.5.5.0", "1.5.6.0", "1.5.7.2", "1.5.7.3", "1.5.8.0", "1.5.9.3", If your specific version is not available in the tested versions, trying with the closer one usually works. TYPE: `str` DEFAULT: `"1.5.9.3"`
`extras`	Extras is used to store additional custom values. These information will be stored in a pd.DataFrame with columns named as in the .mat file. If not None, pass a regex pattern unequivocally identifying the variable in the .mat file to load as extras. TYPE: `None or str` DEFAULT: `None`
`ignore_negative_ipts`	This parameter determines the silhouette score estimation. If True, only positive ipts values are used during peak and noise clustering. This is particularly important for compensating sources with large negative components. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`emgfile`	A dictionary containing all the useful variables. TYPE: `dict`

See also

refsig_from_otb : import REF_SIGNAL in the .mat file exportable from OTBiolab+.
emg_from_demuse : import the .mat file used in DEMUSE.
emg_from_customcsv : Import custom data from a .csv file.
askopenfile : Select and open files with a GUI.

RAISES	DESCRIPTION
`ValueError`	When a wrong value is passed to version=.

Notes

The returned file is called emgfile for convention.

The input .mat file exported from the OTBiolab+ software must have a specific content:

The reference signal is optional but, if present, there should be the fullsampled or the subsampled version (in OTBioLab+ the "performed path" refers to the subsampled signal, the "acquired data" to the fullsampled signal), REF_SIGNAL is expected to be expressed as % of the MVC (but not compulsory).
Both the IPTS ('Source for decomposition...' in OTBioLab+) and the BINARY_MUS_FIRING ('Decomposition of...' in OTBioLab+) must be present.
The raw EMG signal must be present (it has no specific name in OTBioLab+) with all the channels. Don't exclude unwanted channels before exporting the .mat file.
NO OTHER ELEMENTS SHOULD BE PRESENT, unless an appropriate regex pattern is passed to 'extras='!

Structure of the returned emgfile:

emgfile = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "RAW_SIGNAL": RAW_SIGNAL,
    "REF_SIGNAL": REF_SIGNAL,
    "ACCURACY": SIL,
    "IPTS": IPTS,
    "MUPULSES": MUPULSES,
    "FSAMP": FSAMP,
    "IED": IED,
    "EMG_LENGTH": EMG_LENGTH,
    "NUMBER_OF_MUS": NUMBER_OF_MUS,
    "BINARY_MUS_FIRING": BINARY_MUS_FIRING,
    "EXTRAS": EXTRAS,
}

For OTBiolab+ files, the accuracy is estimated with the silhouette (SIL) score.

Examples:

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg.emg_from_otb(filepath="path/filename.mat")
>>> info = emg.info()
>>> info.data(emgfile)

`emg_from_demuse(filepath, ignore_negative_ipts=False)` ¶

Import the .mat file decomposed in DEMUSE.

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`ignore_negative_ipts`	This parameter determines the silhouette score estimation. If True, only positive ipts values are used during peak and noise clustering. This is particularly important for compensating sources with large negative components. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`emgfile`	A dictionary containing all the useful variables. TYPE: `dict`

See also

emg_from_otb : import the decomposed .mat file exportable by OTBiolab+.
refsig_from_otb : import REF_SIGNAL in the .mat file exportable by OTBiolab+.
emg_from_customcsv : Import custom data from a .csv file.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emgfile for convention.

The demuse file contains 65 raw EMG channels (1 empty) instead of 64 (as for OTB matrix standards) in the case of a 64 electrodes matrix.

Structure of the emgfile:

emgfile = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "RAW_SIGNAL": RAW_SIGNAL,
    "REF_SIGNAL": REF_SIGNAL,
    "ACCURACY": SIL
    "IPTS": IPTS,
    "MUPULSES": MUPULSES,
    "FSAMP": FSAMP,
    "IED": IED,
    "EMG_LENGTH": EMG_LENGTH,
    "NUMBER_OF_MUS": NUMBER_OF_MUS,
    "BINARY_MUS_FIRING": BINARY_MUS_FIRING,
    "EXTRAS": EXTRAS,
}

For DEMUSE files, the accuracy is estimated with the silhouette (SIL) score.

Examples:

For an extended explanation of the imported emgfile:

>>> import openhdemg.library as emg
>>> emgfile = emg.emg_from_demuse(filepath="path/filename.mat")
>>> info = emg.info()
>>> info.data(emgfile)

`emg_from_delsys(rawemg_filepath, mus_directory, emg_sensor_name='Galileo sensor', refsig_sensor_name='Trigno Load Cell', filename_from='mus_directory')` ¶

Import the .mat and .txt files exportable from Delsys softwares.

This function is used to load .mat files from the Delsys Neuromap software (containing the RAW EMG signal and the reference signal) and .txt files from the Delsys Neuromap Explorer software (containing the decomposition outcome, accuracy measure and MUAPs).

We currenlty support only recordings performed with the "Galileo sensor" (4-pin). Support for the 5-pin sensor will be provided in the next releases.

PARAMETER	DESCRIPTION
`rawemg_filepath`	The directory and the name of the file containing the raw EMG data to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`mus_directory`	The directory (path to the folder) containing .txt files with firing times, MUAPs, and accuracy data. This can be a simple string, the use of Path is not necessary. The .txt files should all be contained in the same folder and should follow the standard Deslys naming convention (e.g., the file containing accuracy data will have the string "Stats" in its name). TYPE: `str or Path`
`emg_sensor_name`	The name of the EMG sensor used to collect the data. We currently support only the "Galileo sensor" (4-pin). TYPE: `str` DEFAULT: `"Galileo sensor"`
`refsig_sensor_name`	The name of the sensor used to record the reference signal. This is by default "Trigno Load Cell". However, since this can have any name (and can also be renamed by the user), here you should pass the effective name (or regex pattern) by which you identify the sensor. Ignore if no reference signal was recorded. TYPE: `str` DEFAULT: `"Trigno Load Cell"`
`filename_from`	The source by which the imported file will be named. This can either be the same name of the file containing the raw EMG signal or of the folder containing the decomposition outcome. TYPE: `str {"rawemg_file", "mus_directory"}` DEFAULT: `"mus_directory"`

RETURNS	DESCRIPTION
`emgfile`	A dictionary containing all the useful variables. TYPE: `dict`

See also

refsig_from_delsys : Import the reference signal exportable from Delsys.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emgfile for convention.

Structure of the returned emgfile:

emgfile = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "RAW_SIGNAL": RAW_SIGNAL,
    "REF_SIGNAL": REF_SIGNAL,
    "ACCURACY": PROPRIETARY ACCURACY MEASURE,
    "IPTS": IPTS,
    "MUPULSES": MUPULSES,
    "FSAMP": FSAMP,
    "IED": IED,
    "EMG_LENGTH": EMG_LENGTH,
    "NUMBER_OF_MUS": NUMBER_OF_MUS,
    "BINARY_MUS_FIRING": BINARY_MUS_FIRING,
    "EXTRAS": EXTRAS,
}

For Delsys files, the accuracy is the one provided after the decomposition and it is not computed internally, being this a proprietary measure.

We collect the raw EMG and the reference signal from the .mat file because the .csv doesn't contain the information about sampling frequency. Similarly, we collect the firing times, MUAPs and accuracy from the .txt files because in the .mat file, the accuracy is contained in a table, which is not compatible with Python.

Examples:

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg.emg_from_delsys(
...     rawemg_filepath="path/filename.mat",
...     mus_directory="/directory",
... )
>>> info = emg.info()
>>> info.data(emgfile)

`emg_from_customcsv(filepath, ref_signal='REF_SIGNAL', raw_signal='RAW_SIGNAL', ipts='IPTS', mupulses='MUPULSES', binary_mus_firing='BINARY_MUS_FIRING', accuracy='ACCURACY', extras='EXTRAS', fsamp=2048, ied=8)` ¶

Import the emgfile from a custom .csv file.

The variables of interest should be contained in columns. The name of the columns containing each variable can be specified by the user if different from the default values.

This function detects the content of the .csv by parsing the .csv columns. For parsing, column labels should be provided. A label is a term common to all the columns containing the same information. For example, if the raw signal is contained in the columns 'RAW_SIGNAL_1', 'RAW_SIGNAL_2', ... , 'RAW_SIGNAL_n', the label of the columns should be 'RAW_SIGNAL'. If the parameters in input are not present in the .csv file, the user should leave the original inputs.

The .csv file must contain at least the raw_signal and one of 'mupulses' or 'binary_mus_firing'. If 'mupulses' is absent, it will be calculated from 'binary_mus_firing' and viceversa.

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`ref_signal`	Label of the column containing the reference signal. TYPE: `str` DEFAULT: `'REF_SIGNAL'`
`raw_signal`	Label of the column(s) containing the raw emg signal. TYPE: `str` DEFAULT: `'RAW_SIGNAL'`
`ipts`	Label of the column(s) containing the pulse train (decomposed source). TYPE: `str` DEFAULT: `'IPTS'`
`mupulses`	Label of the column(s) containing the times of firing. TYPE: `str` DEFAULT: `'MUPULSES'`
`binary_mus_firing`	Label of the column(s) containing the binary representation of the MUs firings. TYPE: `str` DEFAULT: `'BINARY_MUS_FIRING'`
`accuracy`	Label of the column(s) containing the accuracy score of the MUs firings. TYPE: `str` DEFAULT: `'ACCURACY'`
`extras`	Label of the column(s) containing custom values. This information will be stored in a pd.DataFrame with columns named as in the .csv file. TYPE: `str` DEFAULT: `'EXTRAS'`
`fsamp`	Tha sampling frequency. TYPE: `int or float` DEFAULT: `2048`
`ied`	The inter-electrode distance in mm. TYPE: `int or float` DEFAULT: `8`

RETURNS	DESCRIPTION
`emgfile`	A dictionary containing all the useful variables. TYPE: `dict`

See also

emg_from_demuse : import the .mat file used in DEMUSE.
emg_from_otb : import the .mat file exportable by OTBiolab+.
refsig_from_otb : import reference signal in the .mat file exportable by OTBiolab+.
refsig_from_customcsv : Import the reference signal from a custom .csv.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emgfile for convention.

Structure of the emgfile:

emgfile = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "RAW_SIGNAL": RAW_SIGNAL,
    "REF_SIGNAL": REF_SIGNAL,
    "ACCURACY": ACCURACY,
    "IPTS": IPTS,
    "MUPULSES": MUPULSES,
    "FSAMP": FSAMP,
    "IED": IED,
    "EMG_LENGTH": EMG_LENGTH,
    "NUMBER_OF_MUS": NUMBER_OF_MUS,
    "BINARY_MUS_FIRING": BINARY_MUS_FIRING,
    "EXTRAS": EXTRAS,
}

Examples:

An example of the .csv file to load:

>>>
REF_SIGNAL  RAW_SIGNAL (1)  RAW_SIGNAL (2)  RAW_SIGNAL (3)  RAW_SIGNAL (4)  ...  MUPULSES (2)  BINARY_MUS_FIRING (1)  BINARY_MUS_FIRING (2)  ACCURACY (1)  ACCURACY (2)
         1        0.100000        0.100000        0.100000        0.100000  ...           1.0                      0                      0          0.89          0.95
         2        2.000000        2.000000        2.000000        2.000000  ...           2.0                      0                      0                                  
         3        0.500000        0.500000        0.500000        0.500000  ...           9.0                      0                      0                                  
         4        0.150000        0.150000        0.150000        0.150000  ...          15.0                      0                      1                                  
         5        0.350000        0.350000        0.350000        0.350000  ...          18.0                      1                      1                                  
         6        0.215000        0.215000        0.215000        0.215000  ...          22.0                      1                      0

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg_from_customcsv(filepath = "mypath/file.csv")
>>> info = emg.info()
>>> info.data(emgfile)

`refsig_from_otb(filepath, refsig='fullsampled', version='1.5.9.3', extras=None)` ¶

Import the reference signal in the .mat file exportable by OTBiolab+.

This function is used to import the .mat file exportable by the OTBiolab+ software as a dictionary of Python objects (mainly pandas dataframes). Compared to the function emg_from_otb, this function only imports the REF_SIGNAL and, therefore, it can be used for special cases where only the REF_SIGNAL is necessary. This will allow for a faster execution of the script and to avoid exceptions for missing data.

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`refsig`	Whether to load the full or sub-sampled one. Please read notes section. TYPE: `str {"fullsampled", "subsampled"}` DEFAULT: `"fullsampled"`
`version`	Version of the OTBiolab+ software used (4 points). Tested versions are: "1.5.3.0", "1.5.4.0", "1.5.5.0", "1.5.6.0", "1.5.7.2", "1.5.7.3", "1.5.8.0", "1.5.9.3", If your specific version is not available in the tested versions, trying with the closer one usually works, but please double check the results. TYPE: `str` DEFAULT: `"1.5.9.3"`
`extras`	Extras is used to store additional custom values. These information will be stored in a pd.DataFrame with columns named as in the .mat file. If not None, pass a regex pattern unequivocally identifying the variable in the .mat file to load as extras. TYPE: `None or str` DEFAULT: `None`

RETURNS	DESCRIPTION
`emg_refsig`	A dictionary containing all the useful variables. TYPE: `dict`

See also

emg_from_otb : import the .mat file exportable by OTBiolab+.
emg_from_demuse : import the .mat file used in DEMUSE.
emg_from_customcsv : Import custom data from a .csv file.
refsig_from_customcsv : Import the reference signal from a custom .csv.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emg_refsig for convention.

The input .mat file exported from the OTBiolab+ software must contain:

Reference signal: there must be the fullsampled or the subsampled version (in OTBioLab+ the "performed path" refers to the subsampled signal, the "acquired data" to the fullsampled signal), REF_SIGNAL is expected to be expressed as % of the MVC (but not compulsory).
NO OTHER ELEMENTS SHOULD BE PRESENT, unless an appropriate regex pattern is passed to 'extras='!

Structure of the returned emg_refsig:

emg_refsig = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "FSAMP": FSAMP,
    "REF_SIGNAL": REF_SIGNAL,
    "EXTRAS": EXTRAS,
}

Examples:

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg.refsig_from_otb(filepath="path/filename.mat")
>>> info = emg.info()
>>> info.data(emgfile)

`refsig_from_delsys(filepath, refsig_sensor_name='Trigno Load Cell')` ¶

Import the reference signal in the .mat file exportable by Delsys Neuromap.

This function is used to import the .mat file exportable by the Delsys Neuromap software as a dictionary of Python objects (mainly pandas dataframes). Compared to the function emg_from_delsys, this function only imports the REF_SIGNAL and, therefore, it can be used for special cases where only the REF_SIGNAL is necessary. This will allow for a faster execution of the script and to avoid exceptions for missing data.

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`refsig_sensor_name`	The name of the sensor used to record the reference signal. This is by default "Trigno Load Cell". However, since this can have any name (and can also be renamed by the user), here you should pass the effective name (or regex pattern) by which you identify the sensor. TYPE: `str` DEFAULT: `"Trigno Load Cell"`

RETURNS	DESCRIPTION
`emg_refsig`	A dictionary containing all the useful variables. TYPE: `dict`

See also

emg_from_delsys : Import the Delsys decomposition outcome.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emg_refsig for convention.

Structure of the returned emg_refsig:

emg_refsig = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "FSAMP": FSAMP,
    "REF_SIGNAL": REF_SIGNAL,
    "EXTRAS": EXTRAS,
}

Examples:

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg.refsig_from_delsys(filepath="path/filename.mat")
>>> info = emg.info()
>>> info.data(emgfile)

`refsig_from_customcsv(filepath, ref_signal='REF_SIGNAL', extras='EXTRAS', fsamp=2048)` ¶

Import the reference signal from a custom .csv file.

Compared to the function emg_from_customcsv, this function only imports the REF_SIGNAL and, therefore, it can be used for special cases where only the REF_SIGNAL is necessary. This will allow for a faster execution of the script and to avoid exceptions for missing data.

This function detects the content of the .csv by parsing the .csv columns. For parsing, column labels should be provided. A label is a term common to all the columns containing the same information. For example, if the ref signal is contained in the column 'REF_SIGNAL', the label of the columns should be 'REF_SIGNAL' or a part of it (e.g., 'REF'). If the parameters in input are not present in the .csv file (e.g., 'EXTRAS'), the user should leave the original inputs.

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .mat). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`
`ref_signal`	Label of the column containing the reference signal. TYPE: `str` DEFAULT: `'REF_SIGNAL'`
`extras`	Label of the column(s) containing custom values. These information will be stored in a pd.DataFrame with columns named as in the .csv file. TYPE: `str` DEFAULT: `'EXTRAS'`
`fsamp`	Tha sampling frequency. TYPE: `int or float` DEFAULT: `2048`

RETURNS	DESCRIPTION
`emg_refsig`	A dictionary containing all the useful variables. TYPE: `dict`

See also

emg_from_customcsv : Import the emgfile from a custom .csv file.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emg_refsig for convention.

Structure of the returned emg_refsig:

emg_refsig = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "FSAMP": FSAMP,
    "REF_SIGNAL": REF_SIGNAL,
    "EXTRAS": EXTRAS,
}

Examples:

An example of the .csv file to load:

>>>
REF_SIGNAL  EXTRAS (1)  EXTRAS (2)
         1         0.1           0
         2         0.2           0
         3         0.3           0
         4         0.4           0
         5         0.5           1
         6         0.6           1

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = refsig_from_customcsv(filepath = "mypath/file.csv")
>>> info = emg.info()
>>> info.data(emgfile)

`save_json_emgfile(emgfile, filepath, compresslevel=4)` ¶

Save the emgfile or emg_refsig as a JSON file.

Since version 0.2.0

The recommended workflow for saving and loading openhdemg data now relies on the following high-level functions and classes for binary files:

save_openhdemg_module
asksavemodule
load_openhdemg_module
askloadmodule
openhdemg_Collection

PARAMETER	DESCRIPTION
`emgfile`	The dictionary containing the emgfile. TYPE: `dict`
`filepath`	The directory and the name of the file to save (including file extension .json). This can be a simple string; The use of Path is not necessary. TYPE: `str or Path`
`compresslevel`	An int from 0 to 9, where 0 is no compression and nine maximum compression. Compressed files will take less space, but will require more computation. The relationship between compression level and time required for the compression is not linear. For optimised performance, we suggest values between 2 and 6, with 4 providing the best balance. TYPE: `int` DEFAULT: `4`

`emg_from_json(filepath)` ¶

Load the emgfile or emg_refsig stored in json format.

PARAMETER	DESCRIPTION
`filepath`	The directory and the name of the file to load (including file extension .json). This can be a simple string, the use of Path is not necessary. TYPE: `str or Path`

RETURNS	DESCRIPTION
`emgfile`	The dictionary containing the emgfile. TYPE: `dict`

See also

save_json_emgfile : Save the emgfile or emg_refsig as a JSON file.
askopenfile : Select and open files with a GUI.

Notes

The returned file is called emgfile for convention (or emg_refsig if SOURCE in ["OTB_REFSIG", "CUSTOMCSV_REFSIG", "DELSYS_REFSIG"]).

Examples:

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg.emg_from_json(filepath="path/filename.json")
>>> info = emg.info()
>>> info.data(emgfile)

`askopenfile(filesource='OPENHDEMG', **kwargs)` ¶

Select and open files with a GUI.

Since version 0.2.0

The recommended workflow for saving and loading openhdemg data now relies on the following high-level functions and classes for binary files:

save_openhdemg_module
asksavemodule
load_openhdemg_module
askloadmodule
openhdemg_Collection

PARAMETER	DESCRIPTION
`filesource`	The source of the file. See notes for how files should be exported from other softwares or platforms. `OPENHDEMG` File saved from openhdemg (.json). `DEMUSE` File saved from DEMUSE (.mat). `OTB` File exported from OTB with decomposition and EMG signal. (.mat). `DELSYS` Files exported from Delsys Neuromap and Neuromap explorer with decomposition and EMG signal (.mat + .txt). `CUSTOMCSV` Custom file format (.csv) with decomposition and EMG signal. `OTB_REFSIG` File exported from OTB with only the reference signal (.mat). `DELSYS_REFSIG` File exported from DELSYS Neuromap with the reference signal (.mat). `CUSTOMCSV_REFSIG` Custom file format (.csv) containing only the reference signal. TYPE: `str {"OPENHDEMG", "DEMUSE", "OTB", "DELSYS", "CUSTOMCSV", "OTB_REFSIG", "DELSYS_REFSIG", CUSTOMCSV_REFSIG}` DEFAULT: `"OPENHDEMG"`
`ignore_negative_ipts`	This parameter determines the silhouette score estimation. If True, only positive ipts values are used during peak and noise clustering. This is particularly important for compensating sources with large negative components. Currently, this parameter is used when loading files decomposed in DEMUSE or OTB. TYPE: `bool` DEFAULT: `False`
`otb_ext_factor`	The extension factor used for the decomposition in the OTbiolab+ software. Ignore if loading other files. TYPE: `int` DEFAULT: `8`
`otb_refsig_type`	Whether to seacrh also for the REF_SIGNAL and whether to load the full or sub-sampled one. The list is composed as [bool, str]. str can be "fullsampled" or "subsampled". Ignore if loading other files. TYPE: `list` DEFAULT: `[True, "fullsampled"]`
`otb_version`	Version of the OTBiolab+ software used (4 points). Tested versions are: "1.5.3.0", "1.5.4.0", "1.5.5.0", "1.5.6.0", "1.5.7.2", "1.5.7.3", "1.5.8.0", "1.5.9.3", If your specific version is not available in the tested versions, trying with the closer one usually works, but please double check the results. Ignore if loading other files. TYPE: `str` DEFAULT: `"1.5.9.3"`
`otb_extras`	Extras is used to store additional custom values. These information will be stored in a pd.DataFrame with columns named as in the .mat file. If not None, pass a regex pattern unequivocally identifying the variable in the .mat file to load as extras. TYPE: `None or str` DEFAULT: `None`
`delsys_emg_sensor_name`	The name of the EMG sensor used to collect the data. We currently support only the "Galileo sensor". Ignore if loading other files or only the reference signal. TYPE: `str` DEFAULT: `"Galileo sensor"`
`delsys_refsig_sensor_name`	The name of the sensor used to record the reference signal. This is by default "Trigno Load Cell". However, since this can have any name (and can also be renamed by the user), here you should pass the effective name (or regex pattern) by which you identify the sensor. Ignore if loading other files or if no reference signal was recorded. TYPE: `str` DEFAULT: `"Trigno Load Cell"`
`delsys_filename_from`	The source by which the imported file will be named. This can either be the same name of the file containing the raw EMG signal or of the folder containing the decomposition outcome. Ignore if loading other files or only the reference signal. TYPE: `str {"rawemg_file", "mus_directory"}` DEFAULT: `"mus_directory"`
`custom_ref_signal`	Label of the column(s) containing the reference signal of the custom file. This and the following arguments are needed only for custom files. Ignore if loading other files. TYPE: `str` DEFAULT: `'REF_SIGNAL'`
`custom_raw_signal`	Label of the column(s) containing the raw emg signal of the custom file. Ignore if loading other files. TYPE: `str` DEFAULT: `'RAW_SIGNAL'`
`custom_ipts`	Label of the column(s) containing the pulse train of the custom file. Ignore if loading other files. TYPE: `str` DEFAULT: `'IPTS'`
`custom_mupulses`	Label of the column(s) containing the times of firing of the custom file. Ignore if loading other files. TYPE: `str` DEFAULT: `'MUPULSES'`
`custom_binary_mus_firing`	Label of the column(s) containing the binary representation of the MUs firings of the custom file. Ignore if loading other files. TYPE: `str` DEFAULT: `'BINARY_MUS_FIRING'`
`custom_accuracy`	Label of the column(s) containing the accuracy score of the decomposed MUs in the custom file. Ignore if loading other files. TYPE: `str` DEFAULT: `'ACCURACY'`
`custom_extras`	Label of the column(s) containing custom values in the custom file. This information will be stored in a pd.DataFrame with columns named as in the .csv file. Ignore if loading other files. TYPE: `str` DEFAULT: `'EXTRAS'`
`custom_fsamp`	Tha sampling frequency of the custom file. Ignore if loading other files. TYPE: `int` DEFAULT: `2048`
`custom_ied`	The inter-electrode distance in mm of the custom file. Ignore if loading other files. TYPE: `int` DEFAULT: `8`

RETURNS	DESCRIPTION
`emgfile`	The dictionary containing the emgfile. If the selection process was cancelled, it returns None. TYPE: `dict or None`

See also

asksavefile : select where to save files with a GUI.

Notes

The returned file is called emgfile for convention (or emg_refsig if SOURCE in ["OTB_REFSIG", "CUSTOMCSV_REFSIG", "DELSYS_REFSIG"]).

The input .mat file exported from the OTBiolab+ software should have a specific content:

refsig signal is optional but, if present, there should be both the fullsampled and the subsampled version (in OTBioLab+ the "performed path" refers to the subsampled signal, the "acquired data" to the fullsampled signal), REF_SIGNAL is expected to be expressed as % of the MViF (but not compulsory).
Both the IPTS ('Source for decomposition...' in OTBioLab+) and the BINARY_MUS_FIRING ('Decomposition of...' in OTBioLab+) should be present.
The raw EMG signal should be present (it has no specific name in OTBioLab+) with all the channels. Don't exclude unwanted channels before exporting the .mat file.
NO OTHER ELEMENTS SHOULD BE PRESENT! unless an appropriate regex pattern is passed to 'extras='!

For Delsys files: We collect the raw EMG and the reference signal from the .mat file exported from the Delsys Neuromap software because the .csv doesn't contain the information about sampling frequency. Similarly, we collect the firing times, MUAPs and accuracy from the .txt files exported from the Delsys Neuromap Explorer software because in the .mat file, the accuracy is contained in a table, which is not compatible with Python.

For custom .csv files: The variables of interest should be contained in columns. The name of the columns containing each variable can be specified by the user if different from the default values. This function detects the content of the .csv by parsing the .csv columns. For parsing, column labels should be provided. A label is a term common to all the columns containing the same information. For example, if the raw signal is contained in the columns 'RAW_SIGNAL_1', 'RAW_SIGNAL_2', ... , 'RAW_SIGNAL_n', the label of the columns should be 'RAW_SIGNAL'. If the parameters in input are not present in the .csv file, the user can simply leave the original inputs. Please see the documentation of the function emg_from_customcsv for additional informations. The .csv file must contain all the variables. The only admitted exceptions are 'ref_signal' and 'ipts'.

Structure of the returned emgfile:

emgfile = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "RAW_SIGNAL": RAW_SIGNAL,
    "REF_SIGNAL": REF_SIGNAL,
    "ACCURACY": accuracy score (depending on source file type),
    "IPTS": IPTS (depending on source file type),
    "MUPULSES": MUPULSES,
    "FSAMP": FSAMP,
    "IED": IED,
    "EMG_LENGTH": EMG_LENGTH,
    "NUMBER_OF_MUS": NUMBER_OF_MUS,
    "BINARY_MUS_FIRING": BINARY_MUS_FIRING,
    "EXTRAS": EXTRAS,
}

Structure of the returned emg_refsig:

emg_refsig = {
    "SOURCE": SOURCE,
    "FILENAME": FILENAME,
    "FSAMP": FSAMP,
    "REF_SIGNAL": REF_SIGNAL,
    "EXTRAS": EXTRAS,
}

Examples:

For an extended explanation of the imported emgfile use:

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OPENHDEMG")
>>> info = emg.info()
>>> info.data(emgfile)

`asksavefile(emgfile, compresslevel=4)` ¶

Select where to save files with a GUI.

Since version 0.2.0

The recommended workflow for saving and loading openhdemg data now relies on the following high-level functions and classes for binary files:

save_openhdemg_module
asksavemodule
load_openhdemg_module
askloadmodule
openhdemg_Collection

PARAMETER	DESCRIPTION
`emgfile`	The dictionary containing the emgfile to save. TYPE: `dict`
`compresslevel`	An int from 0 to 9, where 0 is no compression and nine maximum compression. Compressed files will take less space, but will require more computation. The relationship between compression level and time required for the compression is not linear. For optimised performance, we suggest values between 2 and 6, with 4 providing the best balance. TYPE: `int` DEFAULT: `4`

See also

askopenfile : select and open files with a GUI.

`is_safe_openhdemg_folder(path, marker_name='.openhdemg_module')` ¶

Check if a given folder is safe to overwrite as an openhdemg directory.

This function verifies that the target folder:

Exists and is a directory.
Is not a dangerous system directory (like '/', 'C:\', etc.).
Contains the expected marker file (e.g., '.openhdemg_module' or '.openhdemg_collection') indicating it was previously created by openhdemg.

PARAMETER	DESCRIPTION
`path`	The path to check. TYPE: `Path or str`
`marker_name`	The name of the marker file that identifies a valid openhdemg directory. TYPE: `str` DEFAULT: `'.openhdemg_module'`

RETURNS	DESCRIPTION
`bool`	True if the folder is safe to remove or overwrite, False otherwise.

Notes

An empty folder is considered a safe folder.

`sha256_file(path, chunk_size=8192)` ¶

Compute the SHA-256 checksum of a file.

Reads the file at the given path in binary mode and computes a SHA-256 hash over its contents in chunks to avoid excessive memory usage.

PARAMETER	DESCRIPTION
`path`	Path to the file for which the checksum should be computed. TYPE: `Path`
`chunk_size`	Number of bytes read per iteration. TYPE: `int` DEFAULT: `8192`

RETURNS	DESCRIPTION
`str`	The SHA-256 hex digest of the file, prefixed with `"sha256:"`.

Examples:

>>> from pathlib import Path
>>> sha256_file(Path("data.bin"))
'sha256:9f2c2e6d14efc02e3f6b4f41a93d85e1b3...'

openfiles

Description¶

save_openhdemg_module(emgfile, path, module_name, filename=None, compresslevel=None, add_checksum=False) ¶

asksavemodule(emgfile, filename=None, compresslevel=None, add_checksum=False) ¶

load_openhdemg_module(path, module_name, verify_checksum=False, return_metadata=False) ¶

askloadmodule(verify_checksum=False, return_metadata=False, return_path=False) ¶

openhdemg_Collection ¶

set_root(root) ¶

get_root() ¶

reset_root() ¶

set_shared_dataframe(df) ¶

get_shared_dataframe() ¶

reset_shared_dataframe() ¶

set_participant_info(info) ¶

get_participant_info() ¶

reset_participant_info() ¶

add_module(module, module_name, replace=True) ¶

get_module(module_name) ¶

remove_module(module_name) ¶

save_module(module_name, filename=None, compresslevel=None, add_checksum=False, save_updated_manifest=True) ¶

save_shared_dataframe(compresslevel=None, add_checksum=False, save_updated_manifest=True) ¶

save_manifest() ¶

save(update_filename=True, compresslevel=None, add_checksum=False) ¶

asksave(update_filename=True, compresslevel=None, add_checksum=False) ¶

load_manifest() ¶

load_module(module_name, verify_checksum=False, return_metadata=False) ¶

load_shared_dataframe(verify_checksum=False) ¶

load(verify_checksum=False) ¶

askload(verify_checksum=False) ¶

emg_from_samplefile() ¶

emg_from_otb(filepath, ext_factor=8, refsig=[True, 'fullsampled'], version='1.5.9.3', extras=None, ignore_negative_ipts=False) ¶

emg_from_demuse(filepath, ignore_negative_ipts=False) ¶

emg_from_delsys(rawemg_filepath, mus_directory, emg_sensor_name='Galileo sensor', refsig_sensor_name='Trigno Load Cell', filename_from='mus_directory') ¶

emg_from_customcsv(filepath, ref_signal='REF_SIGNAL', raw_signal='RAW_SIGNAL', ipts='IPTS', mupulses='MUPULSES', binary_mus_firing='BINARY_MUS_FIRING', accuracy='ACCURACY', extras='EXTRAS', fsamp=2048, ied=8) ¶

refsig_from_otb(filepath, refsig='fullsampled', version='1.5.9.3', extras=None) ¶

refsig_from_delsys(filepath, refsig_sensor_name='Trigno Load Cell') ¶

refsig_from_customcsv(filepath, ref_signal='REF_SIGNAL', extras='EXTRAS', fsamp=2048) ¶

save_json_emgfile(emgfile, filepath, compresslevel=4) ¶

emg_from_json(filepath) ¶

askopenfile(filesource='OPENHDEMG', **kwargs) ¶

asksavefile(emgfile, compresslevel=4) ¶

is_safe_openhdemg_folder(path, marker_name='.openhdemg_module') ¶

sha256_file(path, chunk_size=8192) ¶

`save_openhdemg_module(emgfile, path, module_name, filename=None, compresslevel=None, add_checksum=False)` ¶

`asksavemodule(emgfile, filename=None, compresslevel=None, add_checksum=False)` ¶

`load_openhdemg_module(path, module_name, verify_checksum=False, return_metadata=False)` ¶

`askloadmodule(verify_checksum=False, return_metadata=False, return_path=False)` ¶

`openhdemg_Collection` ¶

`set_root(root)` ¶

`get_root()` ¶

`reset_root()` ¶

`set_shared_dataframe(df)` ¶

`get_shared_dataframe()` ¶

`reset_shared_dataframe()` ¶

`set_participant_info(info)` ¶

`get_participant_info()` ¶

`reset_participant_info()` ¶

`add_module(module, module_name, replace=True)` ¶

`get_module(module_name)` ¶

`remove_module(module_name)` ¶

`save_module(module_name, filename=None, compresslevel=None, add_checksum=False, save_updated_manifest=True)` ¶

`save_shared_dataframe(compresslevel=None, add_checksum=False, save_updated_manifest=True)` ¶

`save_manifest()` ¶

`save(update_filename=True, compresslevel=None, add_checksum=False)` ¶

`asksave(update_filename=True, compresslevel=None, add_checksum=False)` ¶

`load_manifest()` ¶

`load_module(module_name, verify_checksum=False, return_metadata=False)` ¶

`load_shared_dataframe(verify_checksum=False)` ¶

`load(verify_checksum=False)` ¶

`askload(verify_checksum=False)` ¶

`emg_from_samplefile()` ¶

`emg_from_otb(filepath, ext_factor=8, refsig=[True, 'fullsampled'], version='1.5.9.3', extras=None, ignore_negative_ipts=False)` ¶

`emg_from_demuse(filepath, ignore_negative_ipts=False)` ¶

`emg_from_delsys(rawemg_filepath, mus_directory, emg_sensor_name='Galileo sensor', refsig_sensor_name='Trigno Load Cell', filename_from='mus_directory')` ¶

`emg_from_customcsv(filepath, ref_signal='REF_SIGNAL', raw_signal='RAW_SIGNAL', ipts='IPTS', mupulses='MUPULSES', binary_mus_firing='BINARY_MUS_FIRING', accuracy='ACCURACY', extras='EXTRAS', fsamp=2048, ied=8)` ¶

`refsig_from_otb(filepath, refsig='fullsampled', version='1.5.9.3', extras=None)` ¶

`refsig_from_delsys(filepath, refsig_sensor_name='Trigno Load Cell')` ¶

`refsig_from_customcsv(filepath, ref_signal='REF_SIGNAL', extras='EXTRAS', fsamp=2048)` ¶

`save_json_emgfile(emgfile, filepath, compresslevel=4)` ¶

`emg_from_json(filepath)` ¶

`askopenfile(filesource='OPENHDEMG', **kwargs)` ¶

`asksavefile(emgfile, compresslevel=4)` ¶

`is_safe_openhdemg_folder(path, marker_name='.openhdemg_module')` ¶

`sha256_file(path, chunk_size=8192)` ¶