Quantify delta F via paired motor unit analysis.
Conducts a paired motor unit analysis, quantifying delta F between the
supplied collection of motor units. Origional framework for deltaF provided
in Gorassini et. al., 2002:
https://journals.physiology.org/doi/full/10.1152/jn.00024.2001
Since version 0.2.0b3
DeltaF estimates obtained with average_method="test_unit_average"
may differ from earlier releases following the indexing correction in
PR #105.
Author: James (Drew) Beauchamp
| PARAMETER |
DESCRIPTION |
emgfile
|
The dictionary containing the emgfile.
TYPE:
dict
|
smoothfits
|
Smoothed discharge rate estimates.
Each array: motor unit discharge rate x samples aligned in time;
instances of non-firing = NaN
Your choice of smoothing. See compute_svr gen_svr for example.
TYPE:
list of arrays
|
average_method
|
The method for test MU deltaF value. More to be added.
test_unit_average
The average across all possible control units.
all
This returns all possible MU pairs
TYPE:
str {"test_unit_average", "all"}
DEFAULT:
"test_unit_average"
|
normalisation
|
TYPE:
str {"False", "ctrl_max_desc"}
DEFAULT:
"False"
|
recruitment_difference_cutoff
|
An exlusion criteria corresponding to the necessary difference between
control and test MU recruitement in seconds.
TYPE:
float
DEFAULT:
1
|
corr_cutoff
|
An exclusion criteria corresponding to the correlation between control
and test unit discharge rate.
TYPE:
float (0 to 1)
DEFAULT:
0.7
|
controlunitmodulation_cutoff
|
An exclusion criteria corresponding to the necessary modulation of
control unit discharge rate during test unit firing in Hz.
TYPE:
float
DEFAULT:
0.5
|
clean
|
To remove values that do not meet inclusion criteria. Pairs with fewer
than two firings in either MU or insufficient overlap remain invalid
even if False.
TYPE:
bool
DEFAULT:
True
|
exclude_early_reporter_derecruitment
|
Whether to exclude pairs whose reporter derecruits before the test MU.
If False, preserve the original approach: use the reporter's last
firing as the endpoint for deltaF and the control-unit modulation
window when it stops before the test MU. If True, return NaN for
these pairs. This option applies independently of clean.
TYPE:
bool
DEFAULT:
False
|
correlation_metric
|
Use Pearson r or its square when applying corr_cutoff. Both modes
require positive correlation. Only applied when clean=True.
TYPE:
str {"r", "r_squared"}
DEFAULT:
"r"
|
| RETURNS |
DESCRIPTION |
delta_f
|
A pd.DataFrame containing deltaF values and corresponding MU number.
The resulting df will be different depending on average_method.
In particular, if average_method="all", delta_f[MU][row] will
contain a tuple representing the indices of the two motor units
for each given pair (reporter, test) and their corresponding
deltaF value.
Invalid pairs have NaN deltaF. With fewer than two MUs, "all" returns
an empty DataFrame; "test_unit_average" returns one NaN per MU.
TYPE:
DataFrame
|
See also
- compute_svr : fit MU discharge rates with Support Vector Regression,
nonlinear regression.
Examples:
Quantify delta F using svr fits.
>>> import openhdemg.library as emg
>>> emgfile = emg.emg_from_samplefile()
>>> emgfile = emg.sort_mus(emgfile=emgfile)
>>> svrfits = emg.compute_svr(emgfile)
>>> delta_f = emg.compute_deltaf(
... emgfile=emgfile, smoothfits=svrfits["gensvr"],
... )
delta_f
MU dF
0 0 NaN
1 1 NaN
2 2 NaN
3 3 1.838382
4 4 2.709522
For all possible combinations, not test unit average, MU in this case is
pairs (reporter, test).
>>> delta_f_2 = emg.compute_deltaf(
... emgfile=emgfile,
... smoothfits=svrfits["gensvr"],
... average_method='all',
... )
delta_f_2
MU dF
0 (0, 1) NaN
1 (0, 2) NaN
2 (0, 3) 2.127461
3 (0, 4) NaN
4 (1, 2) NaN
5 (1, 3) 1.549303
6 (1, 4) NaN
7 (2, 3) NaN
8 (2, 4) NaN
9 (3, 4) 2.709522