Welcome to DiMEP’s documentation!

DiMEP stands for Detection of ipsilateral Motor Evoked Potentials and was developed by Robert Guggenberger at the Institute of Neuromodulation and Neurotechnology of the University Hospital Tübingen.

Installation

Stable

pip install dimep

Development

pip install git+https://github.com/translationalneurosurgery/tool-dimep.git

Example

# mock a single-channel EMG signal
from numpy import random
random.seed(0)
trace = random.randn(1000)
print(trace.shape)
# >>> (1000,)

# and apply the template approach on this trace
# where the trace is the single-channel EMG recording
# tms_sampleidx marks the onset of the TMS pulse
# and fs is the sampling rate.
from dimep.api import guggenberger
guggenberger(trace=trace, tms_sampleidx= 500, fs = 1000)
# >>> 0.11904591308664515

Documentation

More Examples

List available algorithms

from dimep.api import available
available()

Mock a trace

# mock a single-channel EMG signal
from numpy import random
random.seed(0)
trace = random.randn(1000)
print(trace.shape)
# >>> (1000,)

and subsequently call one (or all) of the algorithms on this mock trace, where the trace is the single-channel EMG recording, tms_sampleidx marks the onset of the TMS pulse and fs is the sampling rate.

Call all implemented algorithms at once

from dimep.api import all
all(trace, tms_sampleidx=500)
# >>> {'chen': 0.0,
#       'bawa': 5.805498168821509,
#       'bradnam': 0.0,
#       'guggenberger': 0.11904591308664515,
#       'lewis': 0.0,
#       'loyda': 0.0,
#       'odergren': 0.0,
#       'rotenberg': 26.662225635355707,
#       'summers': 0.349919002236347,
#       'wassermann': 0.7782071535040253,
#       'zewdie': 0.0,
#       'ziemann': 0.0}

Access a specific algorithm

from dimep.api import <algorithm>

Call a specific algorithm

For example, the threshold based approach by Lewis (2007)

from dimep.api import lewis
lewis(trace=trace, tms_sampleidx= 500, fs = 1000)
# >>> 0.0

or the template based approach by Guggenberger (2021):

from dimep.api import guggenberger
guggenberger(trace=trace, tms_sampleidx= 500, fs = 1000)
# >>> 0.11904591308664515

Algorithms

Organisation of iMEP Algorithms

Sorted in alphabetical order according to last name of first author.

Suitable algorithms were deteced based on a literature research on pubmed using ipsilateral motor evoked potentials as keyword. This search was performed on 5th October 2020. Articles were selected based on title and abstract, and the subselected manuscripts were read for sufficient description of an automated algorithms for estimation of iMEP amplitude (or area, or similar). All algorithms have been implemented to the best of our understanding, based on the description of methods in the respective paper.

In the description of some algorithms, minor details were missing, e.g., the duration of the post TMS search window. In these cases, sensible defaults were used, and documented to inform the user. Decisions and quotes from the respective papers can be found in the source code of the respective functions for reference

Chen 2003

chen(trace, tms_sampleidx, fs=1000)[source]

Estimate the area of a an iMEP based on Chen 2003

The iMEP area is calculated from the rectified EMG, if at least 5ms are 1SD above the mean of the baseline.

Parameters

  • trace (ndarray) – the EMG signal

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

Returns

amplitude – the iMEP Area based on the rectified EMG

Return type

float

Reference

Chen, R.; Yung, D. & Li, J.-Y.Organization of Ipsilateral Excitatory and Inhibitory Pathways in the Human Motor Cortex Journal of Neurophysiology, American Physiological Society, 2003, 89, 1256-1264

See also

bradnam() is based on chen() but normalizes the iMEP amplitude by baseline EMG activity

Bawa 2004

bawa(trace, tms_sampleidx, fs=1000, mep_window_in_ms=(0, inf))[source]

Estimate the peak-to-peak amplitude of an iMEP based on Bawa 2004

Calculates the PtP-Amplitude of the unrectified EMG from

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • mep_window_in_ms (Tuple[float, float]) – the search window after TMS to look for an iMEP. The manuscript did not specify a restricted search window, and by default we search the whole trace, starting from the TMS to the end of the supplied samples.

Returns

amplitude – the peak-to-peak iMEP amplitude of the unrectified EMG after TMS

Return type

float

Reference

Bawa, P., J.D. Hamm, P. Dhillon, and P.A. Gross. “Bilateral Responses of Upper Limb Muscles to Transcranial Magnetic Stimulation in Human Subjects.” Experimental Brain Research 158, no. 3 (October 2004). https://doi.org/10.1007/s00221-004-2031-x.

See also

odergreen() and lewis() also return the PtP amplitude, but only if they are formally discernible

Bradnam 2010

bradnam(trace, tms_sampleidx, fs=1000, unit=1.0)[source]

Estimate the normalized area of an iMEP based on Bradnam 2010

Similar to chen(), the iMEP area is calculated from the rectified EMG, if at least 5ms are 1SD above the mean of the baseline. In addition, the window looking for an iMEP is limited to 10 to 30ms after the TMS (see lewis()) and the value for an area of identical duration during the baseline period immediatly before the TMS is subtracted and multiplied by 1000:

iMEP = (iMEPAREA - EMGAREA) x 1,000

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • unit (float=1) –

    te units of the data relative to microvolts, e.g.

    • if the unit is mV -> 1000

    • if the unit is µV -> 1

Returns

amplitude – the normalized iMEP Area based on the rectified EMG

Return type

float

Reference

Bradnam, L. V.; Stinear, C. M.; Lewis, G. N. & Byblow, W. D.Task-Dependent Modulation of Inputs to Proximal Upper Limb Following Transcranial Direct Current Stimulation of Primary Motor Cortex Journal of Neurophysiology, American Physiological Society, 2010, 103, 2382-2389

See also

chen() does not normalize the iMEP amplitude by baseline EMG activity and has an undefined search window lewis() measures the PtP amplitude of an iMEP in the window 10 to 30 ms after TMS if it passes specific criterions.

Guggenberger

guggenberger(trace, tms_sampleidx, fs=1000)[source]

Estimate amplitude of an iMEP based on Guggenberger (in preparation)

Based on the maximal cross-correlation of the signal with the template iMEP based on the first component of around 2500 trials

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal with units in µV

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

Returns

iMEP – the maximal cross-correlation score of the iMEP

Return type

float

Reference

Guggenberger et al. (in preparation)

Lewis 2007

lewis(trace, tms_sampleidx, fs=1000, discernible_only=False)[source]

Estimate peak-to-peak amplitude of an iMEP based on Lewis 2007

Returns the Peak-to-Peak amplitude of the iMEP within 10 to 30ms after stimulus, if it is ‘discernable’ i.e. at least 100µV in amplitude and exceeds 3 SD of the background EMG (the 30 ms prior to stimulus).

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal with units in µV

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • discernible_only (bool) – whether to report only discernible MEPS (i.e. onset within 10-30ms after TMS and amplitude >= 100 µV). defaults to False

Returns

iMEP – the peak-to-peak amplitude of the iMEP

Return type

float

Reference

Lewis, G. N. & Perreault, E. J. Side of lesion influences bilateral activation in chronic, post-stroke hemiparesis. Clinical neurophysiology 2007, 118, 2050-2062

See also

bradnam(), which inherited the window of 10 to 30ms, or zewdie(), which also calculated PtP, but uses a window from 15 to 80ms and a lower threshold of 50µV.

Loyda 2017

loyda(trace, tms_sampleidx, fs=1000, sham_trace=None)[source]

Estimate the normalized density of an iMEP based on Loyda 2017

The iMEP area is calculated from the rectified EMG, if at least 10ms are 1SD above the mean of the baseline of the 200ms before TMS, and additionally normalized by the area of an identical period from a nonstimulation trial.

Parameters

  • trace (ndarray) – the EMG signal

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • sham_trace (Union[ndarray, None]) – if not supplied, the function will take a period from before the TMS period to calculate a shamArea for normalization. Otherwise, support a non-stimulation trial for strict estimation following Loyda 2017

Return type

float

Returns

  • amplitude (float) – the iMEP Area based on the rectified EMG

  • .. admonition:: Reference – Loyda, J.-C.; Nepveu, J.-F.; Deffeyes, J. E.; Elgbeili, G.; Dancause, N. & Barthélemy, D. Interhemispheric interactions between trunk muscle representations of the primary motor cortex. Journal of neurophysiology, 2017, 118, 1488-1500

Odergren 1996

odergren(trace, tms_sampleidx, fs=1000)[source]

Estimate the peak-to-peak amplitude of an iMEP based on Odergren 1996

Returns the PtP-Amplitude of the unrectified EMG if above 0.1mV (100µV)

The manuscript did not specify a restricted search window, and by default we search the whole trace, starting from the TMS to the end of the supplied samples.

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal with units of µV

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

Returns

amplitude – the peak-to-peak iMEP amplitude of the unrectified EMG after TMS

Return type

float

Reference

Odergren, T. & Rimpiläinen, I. Activation and suppression of the sternocleidomastoid muscle induced by transcranial magnetic stimulation Electroencephalography and Clinical Neurophysiology/Electromyography and Motor Control, Elsevier BV, 1996, 101, 175-180

See also

bawa() also takes the PtP amplitude, but does not threshold it

Rotenberg 2010

rotenberg(trace, tms_sampleidx, mep_window_in_ms=(5, 30), fs=1000)[source]

Estimate the area of an iMEP based on Rotenberg 2010

Returns the iMEP Area of the rectified EMG integrated for the search window

Warning

This study was conducted on rats, and therefore the default search window from 5 to 30ms is probably too fast in humans. We therefore implemented the mep_window_in_ms as an argument. Consider adapting it when conducting studies with humans, e.g. to 15 to 50ms.

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal with units of µV

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • mep_window_in_ms (Tuple[float, float]) – the search window after TMS to look for an iMEP.

Returns

amplitude – the iMEP area

Return type

float

Reference

Rotenberg, A.; Muller, P. A.; Vahabzadeh-Hagh, A. M.; Navarro, X.; López-Vales, R.; Pascual-Leone, A. & Jensen, F. Lateralization of forelimb motor evoked potentials by transcranial magnetic stimulation in rats Clinical Neurophysiology, Elsevier BV, 2010, 121, 104-108

Summers 2020

summers(trace, tms_sampleidx, fs=1000)[source]

Estimate the area of an iMEP based on Summers 2020

Normalizes the area by an area of identical duration during baseline, with onset and offset detected by passing a 3SD threshold compared to baseline.

Parameters

  • trace (ndarray) – the EMG signal

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

Returns

amplitude – the iMEPArea based on the rectified EMG normalized by an area of identical duration during baseline

Return type

float

Reference

Summers, R. L.; Chen, M.; MacKinnon, C. D. & Kimberley, T. J. Evidence for normal intracortical inhibitory recruitment properties in cervical dystonia Clinical Neurophysiology, Elsevier BV, 2020, 131, 1272-1279

See also

refers to chen() for using a SD-based threshold amd bradnam() for using a normalization with prestimulus activity. Different to these, a different window for calculation of the baseline mean and SD and a higher threshold is being used. Also, units of the output are differents.

Wassermann 1994

wassermann(trace, tms_sampleidx, mep_window_in_ms=(15, 75), fs=1000, minimum_duration_in_ms=2, threshold=0.01)[source]

Estimate the normalized density of an iMEP based on Wassermann 1994

Uses a statistical test to compare the iMEP versus baseline activity. Only if a block of at least 2ms is significant in a one-sided t-test with p<0.01, the iMEP area average is calculated and normalized to an area of identical duration from the baseline.

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • mep_window_in_ms (Tuple[float, float] = (15, 75),) – the paper describes to have used ‘the 20 ms following the onset of the contralateral MEP evoked at the optimal cMEP position’. The latency should therefore be set to your empirical results, e.g. if the latency of the cMEP was 19, set mep_window_in_ms to (19, 39). As the range of latencies in healthy and stroke can vary a lot, we used a very large default range.

  • fs (float) – the sampling rate of the signal

  • minimum_duration_in_ms (float = 2,) – the papers requires the iMEP to be above threshold for at least 2ms.

  • threshold (float = 0.01) – the paper describes to have thresholded for values above baseline (P < 0.01, 1-tailed t-test). The one-tailed test is hardcoded, but you can be flexible with your p-value threshold.

Returns

amplitude – the iMEPArea based on the rectified EMG normalized by an area of identical duration during baseline

Return type

float

Reference

Wassermann, Eric M., Alvaro Pascual-Leone, and Mark Hallett. “Cortical Motor Representation of the Ipsilateral Hand and Arm.” Experimental Brain Research 100, no. 1 (July 1994). https://doi.org/10.1007/BF00227284.

Zewdie 2017

zewdie(trace, tms_sampleidx, fs=1000, discernible_only=False)[source]

Estimate the peak-to-peak amplitude of an iMEP based on Zewdie 2017

Returns the Peak-to-Peak amplitude of the iMEP within 15 to 80ms after stimulus, if it is ‘discernable’ i.e. at least 50µV in amplitude and exceeds 3 SD of the background EMG.

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal with units in µV

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • discernible_only (bool) – whether to report only discernible MEPS (i.e. amplitude >= 50 µV). defaults to False

Returns

iMEP – the peak-to-peak amplitude of the iMEP

Return type

float

Reference

Zewdie, E.; Damji, O.; Ciechanski, P.; Seeger, T. & Kirton, A. Contralesional Corticomotor Neurophysiology in Hemiparetic Children With Perinatal Stroke. Neurorehabilitation and neural repair, 2017, 31, 261-271

See also

odergren() also uses a threshold with absolute units, but 100µV instead of 50µV. lewis() is very similar, but uses stricter criterio for discernibility.

Ziemann 1999

ziemann(trace, tms_sampleidx, fs=1000, minimum_duration_in_ms=5)[source]

Estimate the normalized area of of an iMEP based on Ziemann 1999

Returns the normalized area, if it is 1 SD above baseline activity for at least 5ms.

Parameters

  • trace (ndarray) – the one-dimensional (samples,) EMG signal with units in µV

  • tms_sampleidx (int) – the sample at which the TMS pulse was applied

  • fs (float) – the sampling rate of the signal

  • minimum_duration_in_ms (float = 5) – the number of milliseconds the iMEP needs to be above threshold

Returns

area – the normalized area of the iMEP

Return type

float

Reference

Ziemann, Ulf, Kenji Ishii, Alessandra Borgheresi, Zaneb Yaseen, Fortunato Battaglia, Mark Hallett, Massimo Cincotta, and Eric M. Wassermann. “Dissociation of the Pathways Mediating Ipsilateral and Contralateral Motor-Evoked Potentials in Human Hand and Arm Muscles.” The Journal of Physiology 518, no. 3 (August 1999): 895–906. https://doi.org/10.1111/j.1469-7793.1999.0895p.x.

See also

summers() and bradnam() normalize the iMEP area based on baseline EMG activity. summers() uses higher thresholds, while bradnam() uses similar thresholds, a narrow search window, and calculates the normalization to baseline slightly different.

Cite As

We assessed these algorithms by investigating a dataset of 2546 trials from 54 subjects. The dataset can be retrieved from https://doi.org/10.5281/zenodo.5266492. Detailed results of this evaluation can be found in the manuscript

cite

Guggenberger et al. Evaluation of signal analysis algorithms for ipsilateral motor evoked potentials induced by transcranial magnetic stimulation (under review)

Strictness of algorithms

One of our findings showed that very strict threshold-based approaches, such as Bradnam or Loyda, are better able to recover the latent waveform, but that this comes at the cost of low reliability, as many trials cannot be measured and are classified as zero. This assignment of zeros can be interpreted as strictness, and can be estimated by plotting the empirical cumulative distribution function. The further to the right that an algorithm begins to assign values, the stricter it is. The level of strictness determines the number of trials that are discarded.

_images/ecdf_algorithms.png

Number of trials required for decomposition

One alternative to template-based or threshold-based approaches is a direct decomposition, e.g., with a PCA. This opens the question, how many trials are sufficient to trust the results of a PCA?

To answer this question, we run a simulation. We picked at random two subsets with a specific number of trials from our dataset, calculated the two scores with PCA, and calculated Pearson’s correlation coefficient for them. This was performed over a range of sample sizes, and for each sample size, multiple repetitions were performed. See also Decomposition Simulation.

Visual inspection suggests that around 1000 trials would be required until the decomposition reaches saturation. That means we would need around 1000 trials to make sure that two scores are sufficiently similar in shape.

_images/waveform-reproducibility.png

Indices and tables