Skip to content

⚠️ You are viewing an outdated version of the documentation. For the most recent release, please refer to the latest version.

analysis

Description

This module contains all the functions used to analyse the MUs properties apart from those involving:

  • The MUs action potential shape => Available in the muap module
  • DeltaF / PICs estimation => available in the pic module


compute_thresholds(emgfile, event_='rt_dert', type_='abs_rel', n_firings=1, mvc=0)

Calculates recruitment/derecruitment thresholds.

Values are calculated both in absolute and relative terms.

PARAMETER DESCRIPTION
emgfile

The dictionary containing the emgfile.

TYPE: dict

event_

When to calculate the thresholds.

rt_dert Both recruitment and derecruitment tresholds will be calculated.

rt Only recruitment tresholds will be calculated.

dert Only derecruitment tresholds will be calculated.

TYPE: str {"rt_dert", "rt", "dert"} DEFAULT: "rt_dert"

type_

The tipe of value to calculate.

abs_rel Both absolute and relative tresholds will be calculated.

rel Only relative tresholds will be calculated.

abs Only absolute tresholds will be calculated.

TYPE: str {"abs_rel", "rel", "abs"} DEFAULT: "abs_rel"

n_firings

The number of firings used to calculate recruitment/derecruitment thresholds. If n_firings = 1, the threshold is the value of the reference signal at the instant in which the firing happens. If n_firings > 1, the threshold is the average value of the reference signal at the instants in which the n consecutive firings happen.

TYPE: int DEFAULT: 1

mvc

The maximum voluntary contraction (MVC). if mvc is 0, the user is asked to input MVC; otherwise, the value passed is used.

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
mus_thresholds

A DataFrame containing the requested thresholds.

TYPE: DataFrame

See also
  • compute_dr : calculate the discharge rate.
  • basic_mus_properties : calculate basic MUs properties on a trapezoidal contraction.
  • compute_covisi : calculate the coefficient of variation of interspike interval.
  • compute_drvariability : calculate the DR variability.

Examples:

Load the EMG file and compute the thresholds.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> mus_thresholds = emg.compute_thresholds(
...     emgfile=emgfile,
...     event_="rt_dert",
... )
>>> mus_thresholds
       abs_RT    abs_DERT     rel_RT   rel_DERT
0  160.148294  137.682351  18.665302  16.046894
1   39.138554   49.860936   4.561603   5.811298
2   88.155160   95.133218  10.274494  11.087788
3   37.776982   41.010716   4.402912   4.779804

Type of output can be adjusted, e.g., to have only absolute values at recruitment.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> mus_thresholds = emg.compute_thresholds(
...     emgfile=emgfile,
...     event_="rt",
...     type_="abs",
... )
>>> mus_thresholds
       abs_RT
0  160.148294
1   39.138554
2   88.155160
3   37.776982


compute_dr(emgfile, n_firings_RecDerec=4, n_firings_steady=10, start_steady=-1, end_steady=-1, event_='rec_derec_steady', idr_range=None)

Calculate the discharge rate (DR).

PARAMETER DESCRIPTION
emgfile

The dictionary containing the emgfile.

TYPE: dict

n_firings_RecDerec

The number of firings at recruitment and derecruitment to consider for the calculation of the DR.

TYPE: int DEFAULT: 4

n_firings_steady

The number of firings to consider for the calculation of the DR at the start and at the end of the steady-state phase.

TYPE: int DEFAULT: 10

start_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

end_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

event_

When to calculate the DR.

rec_derec_steady DR is calculated at recruitment, derecruitment and during the steady-state phase.

rec DR is calculated at recruitment.

derec DR is calculated at derecruitment.

rec_derec DR is calculated at recruitment and derecruitment.

steady DR is calculated during the steady-state phase.

TYPE: str {"rec_derec_steady", "rec", "derec", "rec_derec", "steady"} DEFAULT: "rec_derec_steady"

idr_range

If idr_range is a list [lower_limit, upper_limit], only firings with an instantaneous discharge rate (IDR) within the limits are used for DR calculation. lower_limit and upper_limit should be in pulses per second. See examples section. If idr_range is None, all the firings are used for DR calculation.

TYPE: None or list DEFAULT: None

RETURNS DESCRIPTION
mus_dr

A pd.DataFrame containing the requested DR.

TYPE: DataFrame

WARNS DESCRIPTION
warning

When calculation of DR at rec/derec fails due to not enough firings.
See also
  • compute_thresholds : calculates recruitment/derecruitment thresholds.
  • basic_mus_properties : calculate basic MUs properties on a trapezoidal contraction.
  • compute_covisi : calculate the coefficient of variation of interspike interval.
  • compute_drvariability : calculate the DR variability.
Notes

DR for all the contraction is automatically calculated and returned.

Examples:

Load the EMG file and compute the DR.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> mus_dr = emg.compute_dr(emgfile=emgfile)
>>> mus_dr
     DR_rec  DR_derec  DR_start_steady  DR_end_steady  DR_all_steady     DR_all
0  5.701081  4.662196         7.321255       6.420720       6.907559   6.814342
1  7.051127  6.752467        14.919066      10.245462      11.938671  11.683134
2  6.101529  4.789000         7.948740       6.133345       7.695189   8.055731
3  6.345692  5.333535        11.121785       9.265212      11.544140  11.109796

Type of output can be adjusted, e.g., to have only the DR at recruitment.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> mus_dr = emg.compute_dr(emgfile=emgfile, event_="rec")
>>> mus_dr
     DR_rec     DR_all
0  5.701081   6.814342
1  7.051127  11.683134
2  6.101529   8.055731
3  6.345692  11.109796

The manual selection of the steady state phase can be bypassed if previously calculated with an automated method.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> mus_dr = emg.compute_dr(
...     emgfile=emgfile,
...     start_steady=20000,
...     end_steady=50000,
...     event_="steady",
... )
>>> mus_dr
   DR_start_steady  DR_end_steady  DR_all_steady     DR_all
0         7.476697       6.271750       6.794170   6.814342
1        14.440561      10.019572      11.822081  11.683134
2         7.293547       5.846093       7.589531   8.055731
3        13.289651       9.694317      11.613640  11.109796

The firings used for DR calculation can be filtered to avoid too closed firings (e.g., doublets) or intervals of inactivity.

>>> emgfile = emg.emg_from_samplefile()
>>> idr = emg.compute_dr(
...     emgfile, start_steady=15000, end_steady=51000, idr_range=[1, 50],
... )
>>> idr
     DR_rec  DR_derec ... DR_end_steady  DR_all_steady     DR_all
0  3.341579  4.606835 ...      8.506270       7.895837   7.657269
1  5.701081  4.662196 ...      6.271989       6.916566   6.814687
2  5.699017  3.691367 ...      7.221309       8.183408   7.949294
3  7.548770  5.449581 ...     10.399834      11.164994  10.693076
4  8.344515  5.333535 ...      9.694317      10.750855  10.543011


basic_mus_properties(emgfile, n_firings_rt_dert=1, n_firings_RecDerec=4, n_firings_steady=10, start_steady=-1, end_steady=-1, idr_range=None, accuracy='default', ignore_negative_ipts=False, constrain_pulses=[True, 3], mvc=0)

Calculate basic MUs properties on a trapezoidal contraction.

The function is meant to be used on trapezoidal contractions and calculates: the absolute/relative recruitment/derecruitment thresholds, the discharge rate at recruitment, derecruitment, during the steady-state phase and during the entire contraction, the coefficient of variation of interspike interval, the coefficient of variation of force signal.

Accuracy measures, MVC and steadiness are also returned.

PARAMETER DESCRIPTION
emgfile

The dictionary containing the emgfile.

TYPE: dict

n_firings_rt_dert

The number of firings used to calculate recruitment/derecruitment thresholds. If n_firings_rt_dert = 1, the threshold is the value of the reference signal at the instant in which the firing happens. If n_firings_rt_dert > 1, the threshold is the average value of the reference signal at the instants in which the n consecutive firings happen.

TYPE: int DEFAULT: 1

n_firings_RecDerec

The number of firings at recruitment and derecruitment to consider for the calculation of the DR.

TYPE: int DEFAULT: 4

n_firings_steady

The number of firings to consider for the calculation of the DR at the start and at the end of the steady-state phase.

TYPE: int DEFAULT: 10

start_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

end_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

idr_range

If idr_range is a list [lower_limit, upper_limit], only firings with an instantaneous discharge rate (IDR) within the limits are used for DR and coefficient of variation of interspike interval (COVisi) calculation. lower_limit and upper_limit should be in pulses per second. See compute_dr() examples section. If idr_range is None, all the firings are used for DR calculation.

TYPE: None or list DEFAULT: None

accuracy

The accuracy measure to return.

default The original accuracy measure already contained in the emgfile is returned without any computation.

SIL The Silhouette score is computed.

PNR The pulse to noise ratio is computed.

SIL_PNR Both the Silhouette score and the pulse to noise ratio are computed.

TYPE: str {"default", "SIL", "PNR", "SIL_PNR"} DEFAULT: "default"

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. This parameter is considered only when accuracy=="SIL" or accuracy=="SIL_PNR".

TYPE: bool DEFAULT: False

constrain_pulses

This parameter determines the PNR estimation. If constrain_pulses[0]==True, the times of firing are considered those in mupulses +- the number of samples specified in constrain_pulses[1]. If constrain_pulses[0]==False, the times of firing are estimated via a heuristic penalty funtion (see Notes in compute_pnr()). constrain_pulses[1] must be an integer (see Notes in compute_pnr() for instructions on how to set the appropriate value).

TYPE: list DEFAULT: [True, 3]

mvc

The maximum voluntary contraction (MVC). It is suggest to report MVC in Newton (N). If 0 (default), the user will be asked to imput it manually. Otherwise, the passed value will be used.

TYPE: float DEFAULT: 0

RETURNS DESCRIPTION
exportable_df

A pd.DataFrame containing the results of the analysis.

TYPE: DataFrame

See also
  • compute_thresholds : calculates recruitment/derecruitment thresholds.
  • compute_dr : calculate the discharge rate.
  • compute_covisi : calculate the coefficient of variation of interspike interval.
  • compute_drvariability : calculate the DR variability.

Examples:

Get full summary of all the MUs properties.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.basic_mus_properties(emgfile=emgfile)
>>> df
     MVC  MU_number      abs_RT    abs_DERT     rel_RT   rel_DERT    DR_rec  DR_derec  DR_start_steady  DR_end_steady  DR_all_steady     DR_all  COVisi_steady  COVisi_all  COV_steady
0  786.0          1  146.709276  126.128587  18.665302  16.046894  5.701081  4.662196         7.467810       6.242360       6.902616   6.814342      11.296316   16.309681    1.423286
1    NaN          2   35.854200   45.676801   4.561603   5.811298  7.051127  6.752467        11.798908       9.977337      11.784061  11.683134      15.871254   21.233615         NaN
2    NaN          3   80.757524   87.150011  10.274494  11.087788  6.101529  4.789000         7.940926       5.846093       7.671361   8.055731      35.755090   35.308650         NaN
3    NaN          4   34.606886   37.569257   4.402912   4.779804  6.345692  5.333535        11.484875       9.636914      11.594712  11.109796      24.611246   29.372524         NaN

We can bypass manual prompting the MVC by pre-specifying it and/or bypass the manual selection of the steady state phase if previously calculated with an automated method.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.basic_mus_properties(
...     emgfile=emgfile,
...     start_steady=20000,
...     end_steady=50000,
...     mvc=786,
... )
>>> df
     MVC  MU_number      abs_RT    abs_DERT     rel_RT   rel_DERT    DR_rec  DR_derec  DR_start_steady  DR_end_steady  DR_all_steady     DR_all  COVisi_steady  COVisi_all  COV_steady
0  786.0          1  146.709276  126.128587  18.665302  16.046894  5.701081  4.662196         7.476697       6.271750       6.794170   6.814342      11.066966   16.309681    1.431752
1    NaN          2   35.854200   45.676801   4.561603   5.811298  7.051127  6.752467        14.440561      10.019572      11.822081  11.683134      15.076819   21.233615         NaN
2    NaN          3   80.757524   87.150011  10.274494  11.087788  6.101529  4.789000         7.293547       5.846093       7.589531   8.055731      36.996894   35.308650         NaN
3    NaN          4   34.606886   37.569257   4.402912   4.779804  6.345692  5.333535        13.289651       9.694317      11.613640  11.109796      26.028689   29.372524         NaN


compute_covisi(emgfile, n_firings_RecDerec=4, start_steady=-1, end_steady=-1, event_='rec_derec_steady', idr_range=None, single_mu_number=-1)

Calculate the COVisi.

This function calculates the coefficient of variation of interspike interval (COVisi).

PARAMETER DESCRIPTION
emgfile

The dictionary containing the emgfile.

TYPE: dict

n_firings_RecDerec

The number of firings at recruitment and derecruitment to consider for the calculation of the COVisi.

TYPE: int DEFAULT: 4

start_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

end_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

event_

When to calculate the COVisi.

rec_derec_steady covisi is calculated at recruitment, derecruitment and during the steady-state phase.

rec covisi is calculated at recruitment.

derec covisi is calculated at derecruitment.

rec_derec covisi is calculated at recruitment and derecruitment.

steady covisi is calculated during the steady-state phase.

TYPE: str {"rec_derec_steady", "rec", "derec", "rec_derec", "steady"} DEFAULT: "rec_derec_steady"

idr_range

If idr_range is a list [lower_limit, upper_limit], only firings with an instantaneous discharge rate (IDR) within the limits are used for COVisi calculation. lower_limit and upper_limit should be in pulses per second. See compute_dr() examples section. If idr_range is None, all the firings are used for DR calculation.

TYPE: None or list DEFAULT: None

single_mu_number

Number of the specific MU to compute the COVisi. If single_mu_number >= 0, only the COVisi of the entire contraction will be returned. If -1 (default), COVisi will be calculated for all the MUs.

TYPE: int DEFAULT: -1

RETURNS DESCRIPTION
covisi

A pd.DataFrame containing the requested COVisi.

TYPE: DataFrame

See also
  • compute_thresholds : calculates recruitment/derecruitment thresholds.
  • compute_dr : calculate the discharge rate.
  • basic_mus_properties : calculate basic MUs properties on a trapezoidal contraction.
  • compute_drvariability : calculate the DR variability.
Notes

COVisi for all the contraction is automatically calculated and returned.

Examples:

Compute covisi during the various parts of the trapezoidal contraction.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.compute_covisi(emgfile=emgfile)
>>> df
   COVisi_rec  COVisi_derec  COVisi_steady  COVisi_all
0    8.600651     24.007405      11.230602   16.309681
1   46.874208     19.243432      16.657603   21.233615
2   32.212757     18.642514      35.421124   35.308650
3   62.995864     13.080768      24.966372   29.372524

If the steady-state phase has been pre-identified, the manual selection of the area can be bypassed.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.compute_covisi(
...     emgfile=emgfile,
...     event_="rec_derec",
...     start_steady=20000,
...     end_steady=50000,
... )
>>> df
   COVisi_rec  COVisi_derec  COVisi_all
0    8.600651     24.007405   16.309681
1   46.874208     19.243432   21.233615
2   32.212757     18.642514   35.308650
3   62.995864     13.080768   29.372524

To access the covisi of the entire contraction of a single MU.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.compute_covisi(emgfile=emgfile, single_mu_number=2)
>>> df
   COVisi_all
0    35.30865


compute_drvariability(emgfile, n_firings_RecDerec=4, start_steady=-1, end_steady=-1, event_='rec_derec_steady', idr_range=None)

Calculate the DR variability.

This function calculates the variability (as the coefficient of variation) of the instantaneous discharge rate (DR) at recruitment, derecruitment, during the steady-state phase and during all the contraction.

PARAMETER DESCRIPTION
emgfile

The dictionary containing the emgfile.

TYPE: dict

n_firings_RecDerec

The number of firings at recruitment and derecruitment to consider for the calculation of the DR variability.

TYPE: int DEFAULT: 4

start_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

end_steady

The start and end point (in samples) of the steady-state phase. If < 0 (default), the user will need to manually select the start and end of the steady-state phase.

TYPE: int DEFAULT: -1

event_

When to calculate the DR variability.

rec_derec_steady DR variability is calculated at recruitment, derecruitment and during the steady-state phase.

rec DR variability is calculated at recruitment.

derec DR variability is calculated at derecruitment.

rec_derec DR variability is calculated at recruitment and derecruitment.

steady DR variability is calculated during the steady-state phase.

TYPE: str {"rec_derec_steady", "rec", "derec", "rec_derec", "steady"} DEFAULT: "rec_derec_steady"

idr_range

If idr_range is a list [lower_limit, upper_limit], only firings with an instantaneous discharge rate (IDR) within the limits are used for DR variability calculation. lower_limit and upper_limit should be in pulses per second. See compute_dr() examples section. If idr_range is None, all the firings are used for DR calculation.

TYPE: None or list DEFAULT: None

RETURNS DESCRIPTION
drvariability

A pd.DataFrame containing the requested DR variability.

TYPE: DataFrame

See also
  • compute_thresholds : calculates recruitment/derecruitment thresholds.
  • compute_dr : calculate the discharge rate.
  • basic_mus_properties : calculate basic MUs properties on a trapezoidal contraction.
  • compute_covisi : calculate the coefficient of variation of interspike interval.
Notes

DR variability for all the contraction is automatically calculated and returned.

Examples:

Compute covisi during the various parts of the trapezoidal contraction.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.compute_covisi(emgfile=emgfile)
>>> df
   DRvar_rec  DRvar_derec  DRvar_steady  DRvar_all
0   8.560971    21.662783     11.051780  13.937779
1  36.934213    17.714761     55.968609  52.726356
2  28.943139    17.263000     49.375100  54.420703
3  48.322396    12.873456     54.718482  48.019809

If the steady-state phase has been pre-identified, the manual selection of the area can be bypassed.

>>> import openhdemg.library as emg
>>> emgfile = emg.askopenfile(filesource="OTB", otb_ext_factor=8)
>>> df = emg.compute_covisi(
...     emgfile=emgfile,
...     event_="rec_derec",
...     start_steady=20000,
...     end_steady=50000,
... )
>>> df
   DRvar_rec  DRvar_derec  DRvar_all
0   8.560971    21.662783  13.937779
1  36.934213    17.714761  52.726356
2  28.943139    17.263000  54.420703
3  48.322396    12.873456  48.019809