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:

event_ 
When to calculate the thresholds.
TYPE:

type_ 
The tipe of value to calculate.
TYPE:

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:

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

RETURNS  DESCRIPTION 

mus_thresholds

A DataFrame containing the requested thresholds.
TYPE:

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.
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:

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

n_firings_steady 
The number of firings to consider for the calculation of the DR at the start and at the end of the steadystate phase.
TYPE:

start_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

end_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

event_ 
When to calculate the DR.
TYPE:

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:

RETURNS  DESCRIPTION 

mus_dr

A pd.DataFrame containing the requested DR.
TYPE:

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 steadystate 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:

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:

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

n_firings_steady 
The number of firings to consider for the calculation of the DR at the start and at the end of the steadystate phase.
TYPE:

start_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

end_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

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:

accuracy 
The accuracy measure to return.
TYPE:

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:

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:

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:

RETURNS  DESCRIPTION 

exportable_df

A pd.DataFrame containing the results of the analysis.
TYPE:

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 prespecifying 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:

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

start_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

end_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

event_ 
When to calculate the COVisi.
TYPE:

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:

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:

RETURNS  DESCRIPTION 

covisi

A pd.DataFrame containing the requested COVisi.
TYPE:

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 steadystate phase has been preidentified, 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.
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 steadystate phase and during all the contraction.
PARAMETER  DESCRIPTION 

emgfile 
The dictionary containing the emgfile.
TYPE:

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

start_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

end_steady 
The start and end point (in samples) of the steadystate phase. If < 0 (default), the user will need to manually select the start and end of the steadystate phase.
TYPE:

event_ 
When to calculate the DR variability.
TYPE:

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:

RETURNS  DESCRIPTION 

drvariability

A pd.DataFrame containing the requested DR variability.
TYPE:

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 steadystate phase has been preidentified, 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