SciPy

pynibs.neuron package

Functions to compute directional-sensitivity-informed [1] neuronal activation thresholds [2].

[1]

Jing, Y., Numssen, O., Hartwigsen, G., Knösche, T. R., & Weise, K. (2024). Effects of Electric Field Direction on TMS-based Motor Cortex Mapping. bioRxiv 10.1101/2024.12.10.627753

[2]

Weise, K., Makaroff, S. N., Numssen, O., Bikson, M., & Knösche, T. R. (2025). Statistical method accounts for microscopic electric field distortions around neurons when simulating activation thresholds. *Brain Stimulation, 18*(2), 280–286. 10.1016/j.brs.2025.02.007

Submodules

pynibs.neuron.neuron_regression module

pynibs.neuron.neuron_regression.calc_e_effective(e, layerid, theta, gradient=None, neuronmodel='sensitivity_weighting', mep=None, waveform='biphasic', e_thresh_subject=None)

Determines the effective electric field using a neuron mean field model. The electric field magnitude is ‘subtracted’ by the threshold map (in V/m), yielding the effective electric field (e_eff).

Parameters:

  • e (np.ndarray) – (N_stim, N_ele) Electric field (matrix).

  • layerid (str) – Choose from the neocortical layers (e.g. “L1”, “L23”, “L4”, “L5”, “L6”).

  • theta (np.ndarray) – (N_stim, N_ele) Theta angle (matrix) of electric field with respect to surface normal.

  • gradient (np.ndarray, optional) – (N_stim, N_ele) Electric field gradient (matrix) between layer 1 and layer 6. Optional, the neuron mean field model is more accurate when provided.

  • neuronmodel (str, default: 'threshold') –

    Select neuron model to modify the electric field values

    • ”sensitivity_weighting”: normalize threshold map and divide raw e-field by it.

    • ”threshold_subtract”: subtract mean threshold from electric field.

    • ”threshold_binary”: assign e-field a binary value to predict MEPs (False -> below threshold, True, above threshold).

    • ”IOcurve”: subtract value read from precomputed neuron IO curve from electric field.

  • mep (np.ndarray of float [N_stim], optional) – MEP data (required in case of “IOcurve” approach (neuronmodel)).

  • waveform (str, default: 'biphasic') –

    Waveform of TMS pulse:

    • ”monophasic”

    • ”biphasic”

  • e_thresh_subject (float, optional) – Subject specific stimulation threshold in V/m. Typically, between 60 … 80 V/m. This is not used for sensitivity_weighting and

Returns:

e_eff – Effective electric field (matrix) [N_stim x N_ele] the regression analysis can be performed with.

Return type:

np.ndarray

pynibs.neuron.neuron_regression.calc_e_threshold(layerid, theta, gradient=None, mep=None, neuronmodel='sensitivity_weighting', waveform='biphasic', e_thresh_subject=None)

Determine sensitivity map of electric field.

Parameters:

  • layerid (str) – Choose from the neocortical layers (e.g. “L1”, “L23”, “L4”, “L5”, “L6”) to load data for.

  • theta (np.ndarray) – (N_stim, N_ele) Theta angle (matrix) of electric field with respect to surface normal. In degrees [0 .. 180].

  • gradient (np.ndarray, optional) – (N_stim, N_ele) Electric field gradient (matrix) between layer 1 and layer 6. Optional, the neuron mean field model is more accurate when provided. Percent [-100 .. 100].

  • mep (np.ndarray of float, optional) – (N_stim, ) MEP data (required in case of “IOcurve” approach (neuronmodel)

  • neuronmodel (str, default: 'sensitivity_weighting') –

    Select neuron model to modify the electric field values

    • ”sensitivity_weighting”: normalize threshold map and divide raw e-field by it.

    • ”threshold_subtract”: subtract mean threshold from electric field.

    • ”threshold_binary”: assign e-field a binary value to predict MEPs

      (False -> below threshold, True, above threshold).

    • ”IOcurve”: subtract value read from precomputed neuron IO curve from electric field.

    • ”cosine” : # TODO: document

  • waveform (str, default: 'biphasic') –

    Waveform of TMS pulse:

    • ”monophasic”

    • ”biphasic”

  • e_thresh_subject (float, optional) – Subject specific stimulation threshold in V/m. Typically between 60 … 80 V/m. Only used for ‘threshold_subtract’ and ‘“threshold_binary”,’

Returns:

e_sens – (N_stim, N_ele) Electric field sensitivity maps.

Return type:

np.ndarray

pynibs.neuron.neuron_regression.calc_q_coupling_model(e_mag, theta, gradient, waveform='monophasic')
Calculates the average dendritic current based of the neuron coupling model [1]. This current can the be

integrated over time, to yield a charge factor that is multiplied with the electric field to calculate an effective electric field (e_eff).

[1] Miller, A., Knösche, T. R., & Weise, K. (2025). A coupling model of transcranial magnetic stimulation

activation of cortical cell populations. Brain Stimulation: Basic, Translational, and Clinical Research in Neuromodulation, 18(1), 528-529.

Parameters:

  • e (np.ndarray) – (N_stim, N_ele) Electric field (matrix).

  • theta (np.ndarray) – (N_stim, N_ele) Theta angle (matrix) of electric field with respect to surface normal.

  • gradient (np.ndarray, optional) – (N_stim, N_ele) Electric field gradient (matrix) between layer 1 and layer 6. Optional, the neuron mean field model is more accurate when provided.

  • waveform (str, default: 'biphasic') –

    Waveform of TMS pulse:

    • ”monophasic”

    • ”biphasic”

Returns:

charges – electric charges (matrix) [N_stim x N_ele] that can be used as scaling factors for the regression analysis.

Return type:

np.ndarray

pynibs.neuron.neuron_regression.load_cell_model(fn_csv)

Load interpolation points of the mean field model from the specified CSV file.

Parameters:

fn_csv (str) – Fully qualified path to the CSV containing the interpolation points of the mean field model.

Returns:

  • scipy.interpolate.LinearNDInterpolator

  • interpolation points ‘theta’

  • interpolation points ‘gradient’

pynibs.neuron.neuron_regression.workhorse_interp(idx_list, interp, params)

Single core workhorse to interpolate data.

Parameters:

  • idx_list (np.nfarray or list of float) – (n_interpolations) Indices in params array where the interpolation has to be performed (subset of all indices in params array).

  • interp (instance of scipy.interpolate) – Interpolator instance.

  • params (np.ndarray of float) – (N_interpolations, N_params) Array containing the parameters the function is evaluated (total array with all parameters).

Returns:

res – (n_interpolations) Interpolation results (subset params[idx_list, :]).

Return type:

np.ndarray of float

pynibs.neuron.util module

pynibs.neuron.util.DI_wave(t, intensity, t0=5, dt=1.4, width=0.25)

Determines cortical DI waves from TMS

Parameters:

  • t (np.ndarray of float) – (n_t) Time axis in ms.

  • intensity (float) – Stimulator intensity w.r.t resting motor threshold (typical range: [0 … 2]).

  • t0 (float) – Offset time.

  • dt (float) – Spacing of waves in ms.

  • width (float) – Width of waves.

Returns:

y – (n_t) DI waves.

Return type:

np.ndarray of float

Previous topic

pynibs.models package

This Page

Edit page
  • © Copyright 2026, Konstantin Weise, Ole Numssen.
  • Created using Sphinx 6.2.1.