pyNIBS 0.2024.8__py3-none-any.whl → 0.2026.1__py3-none-any.whl

pynibs/neuron/neuron_regression.py

@@ -1,5 +1,7 @@
 import os
 import copy
+import h5py
+import pygpc
 import pynibs
 import numpy as np
 import _pickle as pickle
@@ -206,7 +208,7 @@ def calc_e_threshold(layerid, theta, gradient=None, mep=None, neuronmodel="sensi
         params[:, 2] = np.repeat(mep_norm, theta.shape[1])
 
         idx = np.arange(params.shape[0])
-        idx_chunked = pynibs.compute_chunks(list(idx), multiprocessing.cpu_count())
+        idx_chunked = pynibs.util.utils.compute_chunks(list(idx), multiprocessing.cpu_count())
 
         pool = multiprocessing.Pool(multiprocessing.cpu_count())
         workhorse_partial = partial(workhorse_interp, interp=interp, params=params)
@@ -215,6 +217,7 @@ def calc_e_threshold(layerid, theta, gradient=None, mep=None, neuronmodel="sensi
         pool.close()
         pool.join()
 
+
     else:
         raise NotImplementedError
 
@@ -247,6 +250,7 @@ def calc_e_effective(e, layerid, theta, gradient=None, neuronmodel="sensitivity_
         - "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'
@@ -254,6 +258,7 @@ def calc_e_effective(e, layerid, theta, gradient=None, neuronmodel="sensitivity_
 
         - "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
@@ -263,14 +268,22 @@ def calc_e_effective(e, layerid, theta, gradient=None, neuronmodel="sensitivity_
     e_eff : np.ndarray
         Effective electric field (matrix) [N_stim x N_ele] the regression analysis can be performed with.
     """
+    e_thres = None
+    q = None
     # determine sensitivity map
-    e_thres = calc_e_threshold(layerid=layerid,
-                               theta=theta,
-                               gradient=gradient,
-                               neuronmodel=neuronmodel,
-                               mep=mep,
-                               waveform=waveform,
-                               e_thresh_subject=e_thresh_subject)
+    if neuronmodel in ["threshold_subtract", "threshold_binary", "sensitivity_weighting", "cosine", "IOcurve"]:
+        e_thres = calc_e_threshold(layerid=layerid,
+                                   theta=theta,
+                                   gradient=gradient,
+                                   neuronmodel=neuronmodel,
+                                   mep=mep,
+                                   waveform=waveform,
+                                   e_thresh_subject=e_thresh_subject)
+    elif neuronmodel == "neuron_coupling":
+        q = calc_q_coupling_model(e_mag=e,
+                                  theta=theta,
+                                  gradient=gradient,
+                                  waveform=waveform)
 
     if neuronmodel == "threshold_subtract":
         e_eff = e - e_thres
@@ -278,7 +291,84 @@ def calc_e_effective(e, layerid, theta, gradient=None, neuronmodel="sensitivity_
         e_eff = e > e_thres
     elif neuronmodel in ["sensitivity_weighting", "cosine"]:
         e_eff = e / e_thres
+    elif neuronmodel == "neuron_coupling":
+        e_eff = q * e
     else:
         e_eff = np.zeros(e.shape)
 
     return e_eff
+
+def 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 : np.ndarray
+            electric charges (matrix) [N_stim x N_ele] that can be used as scaling factors for the regression analysis.
+        """
+
+    if waveform != 'biphasic':
+        raise NotImplementedError('only biphasic stimulation is implemented for the neuron-coupling model yet!')
+
+    # scaling factor for current (gpc was done in normalized current space)
+    i_scale = 5.148136e-9
+    t = np.linspace(0, 99.81, 500)
+
+    # read gpc session
+    fn_session = '/data/u_emueller_software/git/pynibs/pynibs/neuron/neuron_coupling_model.pkl'
+    session = pygpc.read_session(fname=fn_session)
+
+    with h5py.File(os.path.splitext(fn_session)[0] + ".hdf5", "r") as f:
+        coeffs = f["coeffs"][:]
+
+    # create grid object to transform from real to normalized coordinates [-1, 1]
+    #default values
+    # theta = 0  # angle of e-field [0, 180]°
+    # gradient = 0  # relative gradient of e-field [-20, 20] %/mm
+    # intensity = 250  # intensity of e-field [100, 400] V/m
+    fraction_nmda = 0.5  # fraction of nmda synapses [0.25, 0.75]
+    fraction_gaba_a = 0.95  # fraction of gaba_a synapses [0.9, 1.0]
+    fraction_ex = 0.6  # fraction of exc/ihn synapses [0.2, 0.8]
+
+    T_new = 30
+    dt_new = 0.01
+    t_new = np.arange(0, T_new, dt_new)
+
+    m, n = e_mag.shape
+    l = t_new.shape[0]
+    interp_current = np.zeros((m, n, l))
+    for i in range(n):
+        for j in range(m):
+            coords = np.array([[theta[i, j], gradient[i, j], e_mag[i, j], fraction_nmda, fraction_gaba_a, fraction_ex]])
+            grid = pygpc.RandomGrid(parameters_random=session.parameters_random, coords=coords)
+
+            # use gpc approximation to compute current
+            current = session.gpc[0].get_approximation(coeffs, grid.coords_norm) * i_scale
+            current = current.flatten()
+            t_new = np.arange(0, T_new, dt_new)
+            interp_current[i, j, :] = np.interp(t_new, t, current)
+
+    charges = interp_current.sum(axis=2) # integrate (sum) over time with assumption i(t=0) = 0
+    return charges

pynibs/optimization/__init__.py

@@ -1,5 +1,15 @@
-"""Routines to compute optimal sets of electric fields. """
+"""
+Routines to compute optimal sets of electric fields, either by optimizing
+ - single-channel TMS coil placements, or
+ - input currents for multichannel TMS coil arrays.
+
+ Used in [1]_
+
+ .. [1] Numssen, O., Martin, C. W., Worbs, T., Thielscher, A., Weise, K., & Knösche, T. R. (2025).
+    Optimizing and assessing multichannel TMS focality. Cold Spring Harbor Laboratory.
+    `10.1101/2025.09.19.677136 <https://doi.org/10.1101/2025.09.19.677136>`_
+ """
 from .opt_mep import *
-from .optimization import *
+from .coil_opt import *
 from .workhorses import *
 from .multichannel import *