Skip to content

openfiles

Description

This module contains all the functions that are necessary to open or save MATLAB (.mat), text (.txt), JSON (.json) or custom (.csv) files. MATLAB files are used to store data from the DEMUSE, OTBiolab+ and Delsys software while JSON files are used to save and load files from this library.
The choice of saving files in the open standard JSON file format was preferred over the MATLAB file format since it has a better integration with Python and has a very high cross-platform compatibility.

Function's scope

  • emg_from_samplefile:
    Used to load the sample file provided with the library.
  • emg_from_otb and emg_from_demuse:
    Used to load .mat files coming from the DEMUSE or the OTBiolab+ software. Demuse has a fixed file structure while the OTB file, in order to be compatible with this library should be exported with a strict structure as described in the function emg_from_otb. In both cases, the input file is a .mat file.
  • emg_from_delsys:
    Used to load a combination of .mat and .txt files exported by the Delsys Neuromap and Neuromap explorer software containing the raw EMG signal and the decomposition outcome.
  • emg_from_customcsv:
    Used to load custom file formats contained in .csv files.
  • refsig_from_otb, refsig_from_delsys and refsig_from_customcsv:
    Used to load files from the OTBiolab+ (.mat) and the Delsys Neuromap software (.mat) or from a custom .csv file that contain only the reference signal.
  • save_json_emgfile, emg_from_json:
    Used to save the working file to a .json file or to load the .json file.
  • askopenfile, asksavefile:
    A quick GUI implementation that allows users to select the file to open or save.

Notes

Once opened, the file is returned as a dictionary with key-value pairs:

"SOURCE" : source of the file (i.e., "CUSTOMCSV", "DEMUSE", "OTB", "DELSYS")
"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 MUs firings
"EXTRAS" : additional custom values

The only exception is 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 informations can be found in the info module and in the function's description.

Furthermore, all the users are encouraged to read the dedicated tutorial Structure of the emgfile.


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.

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(initialdir='/', filesource='OPENHDEMG', **kwargs)

Select and open files with a GUI.

PARAMETER DESCRIPTION
initialdir

The directory of the file to load (excluding file name). This can be a simple string, the use of Path is not necessary.

TYPE: str or Path DEFAULT: "/"

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.

TYPE: dict

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.

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.