pyNIBS 0.2024.8__py3-none-any.whl

pynibs/neuron/neuron_regression.py

@@ -0,0 +1,284 @@
+import os
+import copy
+import pynibs
+import numpy as np
+import _pickle as pickle
+import multiprocessing.pool
+from _functools import partial
+from scipy.interpolate import LinearNDInterpolator
+
+
+def 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 : np.ndarray of float
+        (n_interpolations) Interpolation results (subset params[idx_list, :]).
+    """
+    return interp(params[idx_list, 0], params[idx_list, 1], params[idx_list, 2]) / 2.2  # 2.2
+
+
+def 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'
+    """
+    cell_simulation_data = [np.genfromtxt(fn_csv, delimiter=',')]
+
+    thresholds = cell_simulation_data[-1][:, 2]
+    theta = cell_simulation_data[-1][:, 1]
+    rel_grad = cell_simulation_data[-1][:, 0]
+
+    return LinearNDInterpolator(list(zip(theta, rel_grad)), thresholds), theta, rel_grad
+
+
+# TODO: implement the creation of a response interpolator
+def _create_model_response_interpolator(fn_model_csv):
+    return LinearNDInterpolator([(0, 0), (0, 1), (1, 0), (1, 1)], [1, 1, 1, 1], fill_value=1)
+
+
+def 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 : np.ndarray
+        (N_stim, N_ele) Electric field sensitivity maps.
+    """
+    # load neuron models
+    ####################################################################################################################
+    models_folder = os.path.join(pynibs.__datadir__, "neuron", "models")
+    interp_folder = os.path.join(pynibs.__datadir__, "neuron", "interpolators")
+    scaling_factor = None
+
+    if waveform == "monophasic":
+        models = {
+            "L23": os.path.join(models_folder, "L23_PC_cADpyr_monophasic_v1.csv"),
+            "L4SBC": os.path.join(models_folder, "L4_SBC_monophasic_v1.csv"),
+            "L4NBC": os.path.join(models_folder, "L4_NBC_monophasic_v1.csv"),
+            "L4LBC": os.path.join(models_folder, "L4_LBC_monophasic_v1.csv"),
+            "L5": os.path.join(models_folder, "L5_TTPC2_cADpyr_monophasic_v1.csv")
+        }
+
+        models_io = {
+            "L23": os.path.join(interp_folder, "L23_biphasic_recruitment_rate_interpolator_inverse.pkl"),
+            "L5": os.path.join(interp_folder, "L5_biphasic_recruitment_rate_interpolator_inverse.pkl")
+        }
+    elif waveform == "biphasic":
+        models = {
+            "L23": os.path.join(models_folder, "L23_PC_cADpyr_biphasic_v1.csv"),
+            "L4SBC": os.path.join(models_folder, "L4_SBC_biphasic_v1.csv"),
+            "L4NBC": os.path.join(models_folder, "L4_NBC_biphasic_v1.csv"),
+            "L4LBC": os.path.join(models_folder, "L4_LBC_biphasic_v1.csv"),
+            "L5": os.path.join(models_folder, "L5_TTPC2_cADpyr_biphasic_v1.csv")
+        }
+
+        models_io = {
+            "L23": os.path.join(interp_folder, "L23_biphasic_recruitment_rate_interpolator_inverse.pkl"),
+            "L5": os.path.join(interp_folder, "L5_biphasic_recruitment_rate_interpolator_inverse.pkl")
+        }
+    else:
+        raise NotImplementedError(f"Specified waveform {waveform} not implemented.")
+
+    if neuronmodel in ["threshold_subtract", "threshold_binary", "sensitivity_weighting", "cosine"]:
+        interp, thetas, rel_gradients = load_cell_model(models[layerid])
+
+        if neuronmodel in ["sensitivity_weighting", "cosine"]:
+            scaling_factor = interp(0, 0)
+            if e_thresh_subject is not None:
+                print(f"e_thresh_subject={e_thresh_subject} is not used for neuronmodel={neuronmodel}")
+
+        elif e_thresh_subject is not None:
+            scaling_factor = np.mean(interp(np.linspace(0, 180, 181),
+                                            np.zeros(181))) / e_thresh_subject
+
+        else:
+            # Scaling factor between electric field thresholds of model and subject specific e-field thresholds.
+            # scaling_factor = e_threshold_model / e_threshold_subject
+            # Model thresholds are higher than subject specific thresholds (typically in a range between 2..3)
+            # average thresholds between 0 and 180° at E_grad = 0
+            scaling_factor = 1
+
+    elif neuronmodel == "IOcurve":
+        _, thetas, rel_gradients = load_cell_model(models[layerid])
+
+        # TODO: not implemented yet
+        if not os.path.exists(models_io[layerid]):
+            raise NotImplementedError("[neuron_regression] Pickl files containing the response interpolators "
+                                      f"do not exist (path checked: {models_io[layerid]}) and their creation "
+                                      "is not implemented yet.")
+            # interp = _create_model_response_interpolator(models[layerid])
+            # with open(models_io[layerid], 'wb') as f:
+            #    pickle.dump(interp, f)
+        else:
+            with open(models_io[layerid], 'rb') as f:
+                interp = pickle.load(f)
+
+    else:
+        raise NotImplementedError(f"Specified neuronmodel {neuronmodel} not implemented.")
+
+    # bound observed values to min/max values available in the model
+    ####################################################################################################################
+    theta_bound = theta
+    theta_bound[np.where(theta > np.max(thetas))] = np.max(thetas)
+    theta_bound[np.where(theta < np.min(thetas))] = np.min(thetas)
+
+    if gradient is None:
+        gradient_bound = np.zeros(theta.shape)
+    else:
+        gradient_bound = gradient
+        gradient_bound[np.where(gradient > np.max(rel_gradients))] = np.max(rel_gradients)
+        gradient_bound[np.where(gradient < np.min(rel_gradients))] = np.min(rel_gradients)
+
+    # Determine approach specific effective electric field
+    ####################################################################################################################
+    if neuronmodel in ["threshold_subtract", "threshold_binary", "sensitivity_weighting"]:
+        e_thres = interp(theta_bound, gradient_bound) / scaling_factor
+
+    elif neuronmodel == "cosine":
+        e_thres = scaling_factor * 1 / np.abs(np.cos(theta_bound / np.pi))
+
+    elif neuronmodel == "IOcurve":
+        # normalize MEPs between [0, 0.999]
+        mep_threshold = 2
+        mep_cropped = copy.deepcopy(mep)
+        mep_cropped[mep > mep_threshold] = mep_threshold
+        mep_norm = mep_cropped / (mep_threshold * 1.05)
+
+        # calculate expected electric field at observed MEP
+        params = np.zeros((theta.shape[0] * theta.shape[1], 3))
+        params[:, 0] = gradient_bound.flatten()
+        params[:, 1] = theta_bound.flatten()
+        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())
+
+        pool = multiprocessing.Pool(multiprocessing.cpu_count())
+        workhorse_partial = partial(workhorse_interp, interp=interp, params=params)
+        res = np.hstack(pool.map(workhorse_partial, idx_chunked))
+        e_thres = np.reshape(res, theta.shape)
+        pool.close()
+        pool.join()
+
+    else:
+        raise NotImplementedError
+
+    return e_thres
+
+
+def 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 : np.ndarray
+        Effective electric field (matrix) [N_stim x N_ele] the regression analysis can be performed with.
+    """
+    # 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 == "threshold_subtract":
+        e_eff = e - e_thres
+    elif neuronmodel == "threshold_binary":
+        e_eff = e > e_thres
+    elif neuronmodel in ["sensitivity_weighting", "cosine"]:
+        e_eff = e / e_thres
+    else:
+        e_eff = np.zeros(e.shape)
+
+    return e_eff

pynibs/neuron/util.py

@@ -0,0 +1,58 @@
+import pynibs
+import numpy as np
+
+
+def 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: np.ndarray of float
+        (n_t) DI waves.
+    """
+    waves = ["D", "I1", "I2", "I3", "I4"]
+
+    x0 = dict()
+    x0["D"] = 1.6952640144480995
+    x0["I1"] = 1.314432218728424
+    x0["I2"] = 1.4421623825084195
+    x0["I3"] = 1.31643163560532
+    x0["I4"] = 1.747079479469914
+
+    amp = dict()
+    amp["D"] = 12.83042571812661 / 35.46534715796085
+    amp["I1"] = 35.46534715796085 / 35.46534715796085
+    amp["I2"] = 26.15109003222628 / 35.46534715796085
+    amp["I3"] = 15.491215097559184 / 35.46534715796085
+    amp["I4"] = 10.461195366965226 / 35.46534715796085
+
+    r = dict()
+    r["D"] = 13.945868670402973
+    r["I1"] = 8.707029476168504
+    r["I2"] = 7.02266347578131
+    r["I3"] = 16.74855628350182
+    r["I4"] = 17.85806255278076
+
+    y = np.zeros(len(t), dtype=np.float128)
+
+    for i, w in enumerate(waves):
+        y_ = np.exp(-(t - t0 - i * dt) ** 2 / (2 * width ** 2))
+        y_ = y_ / np.max(y_)
+        y_ = y_ * pynibs.expio.fit_funs.sigmoid(intensity, amp=amp[w], r=r[w], x0=x0[w])
+        y = y + y_
+
+    return y

pynibs/optimization/__init__.py

@@ -0,0 +1,5 @@
+"""Routines to compute optimal sets of electric fields. """
+from .opt_mep import *
+from .optimization import *
+from .workhorses import *
+from .multichannel import *

pynibs/optimization/multichannel.py

@@ -0,0 +1,278 @@
+"""
+Functions to optimize single coil currents for multichannel TMS arrays.
+"""
+import numpy as np
+from scipy.optimize import minimize
+
+
+def get_score_raw(x, e, n_stim, n_ele, n_channel, x_opt=None, opt_target='elms'):
+    """
+    Compute score for e-efield cross correlations.
+    Non-normalized score is returned, so you need to do sth like
+
+    score = 1 / ((n_ele ** 2 - n_ele) / 2) * get_score()
+
+    Parameters
+    ----------
+    x : np.ndarray of float
+        (n_channel * n_stim_opt, ) Vector to scale channels for each.
+    e : np.ndarray of float
+        (n_ele*3, n_channels) E-field.
+    n_stim : int
+        Number of stimulations to compute score for.
+    n_ele : int
+        Number of elements.
+    n_channel : int
+        Number of channels.
+    x_opt :  np.ndarray of float, optinonal
+        (n_pre_opt,) Previously optimized channel currents.
+    opt_target : str, default: 'elms'
+        Optimization target. 'elms' for optimizing decorrelations of elements, 'stims' for stimulations.
+
+    Returns
+    -------
+    score : float
+        non-normalized score np.nansum(np.abs(np.triu(np.corrcoef(e_mag), k=1)))
+    """
+    if x_opt is None:
+        currents_all_zaps_channels = np.reshape(x, (n_channel, n_stim))
+    else:
+        currents_all_zaps_channels = np.hstack((x_opt, np.reshape(x, (n_channel, n_stim - x_opt.shape[1]))))
+    # currents_all_zaps_channels.shape = (n_chans, n_zaps)
+
+    # determine total electric field (vector form)
+    e_vec = np.matmul(e, currents_all_zaps_channels)  # e_vec.shape = (n_elems*3, n_zaps)
+    # determine magnitude
+    # for e_ in e_vec.T:
+    #     a = np.linalg.norm(np.reshape(e_, (n_ele, 3)), axis=1)
+    #     # e_.shape = (n_ele=3,)
+    #     # np.reshape(e_, (n_ele, 3)).shape = (n_ele,3)
+    #     # a.shape = (n_ele,)
+
+    if e.ndim == 2:
+        e_mag = np.vstack([np.linalg.norm(np.reshape(e_, (n_ele, 3)), axis=1) for e_ in e_vec.T]).T
+    elif e.ndim == 3:
+        e_mag = np.linalg.norm(e_vec, axis=1)
+    else:
+        raise ValueError
+    # e_mag.shape = (n_ele, n_zaps)
+
+    # determine average correlation coefficient
+    # r_avg = 1/((n_ele**2-n_ele)/2) * np.sum(np.abs(np.triu(np.corrcoef(e_mag), k=1)))
+    if opt_target == 'elms':
+        r_sum = np.nansum(np.abs(np.triu(np.corrcoef(e_mag), k=1)))
+    elif opt_target == 'stims':
+        r_sum = np.nansum(np.abs(np.triu(np.corrcoef(e_mag.T), k=1)))
+    else:
+        raise ValueError("opt_target has to be 'elms' or 'stims'")
+
+    return r_sum
+
+
+def get_score_raw_single_channel(x, e, x_opt=None):
+    """
+    Compute score for e-efield cross correlations.
+    Non-normalized score is returned, so you need to do sth like
+
+    score = 1 / ((n_ele ** 2 - n_ele) / 2) * get_score()
+
+    Parameters
+    ----------
+    x : np.ndarray of float
+        (n_placements, ) selection of coil placements.
+    e : np.ndarray of float
+        (n_ele*3, n_channels) E-field.
+    x_opt :  np.ndarray of float, optinonal
+        (n_pre_opt,) Previously optimized channel currents.
+
+    Returns
+    -------
+    score : float
+        non-normalized score np.nansum(np.abs(np.triu(np.corrcoef(e_mag), k=1)))
+    """
+    # x = ((x / x.max()) * e.shape[0]-1).astype(int)
+    if x_opt is not None:
+        x = np.hstack((x_opt, x))
+    x = x.astype(int)
+    e_mag = e[x, :]
+
+    # determine average correlation coefficient
+    # r_avg = 1/((n_ele**2-n_ele)/2) * np.sum(np.abs(np.triu(np.corrcoef(e_mag), k=1)))
+    # a = np.abs(np.triu(np.corrcoef(e_mag.T), k=1))
+
+    r_avg = np.nansum(np.abs(np.triu(np.corrcoef(e_mag.T), k=1)))
+    return r_avg
+
+
+def optimize_currents(e, n_stim, currents_prev=None, seed=None,
+                      maxiter=200, method='SLSQP', opt_target='elms', verbose=False):
+    """
+    Optimize the currents for a multichannel TMS array by minimizing e-fields cross-correlation.
+
+    Parameters
+    ----------
+    e : np.ndarray of float
+        (n_elms * 3, n_channel) or (n_elms, 3, n_channel). E in ROI for currents = 1.
+    n_stim : int
+        Number of stimulations.
+    currents_prev : np.ndarray of float, optional
+        (n_channels, n_stims_prev) Previous currents to append to.
+    seed : int, optional
+        Seed for random number generator.
+    maxiter : int, default=200
+        Max iterations of the optimization.
+    method : str, default: 'SLSQP'
+        Optimization method.
+    verbose : bool, default: False
+        Print additional information.
+    opt_target : str, default: 'elms'
+        Optimization target. 'elms' for optimizing decorrelations of elements, 'stims' for stimulations.
+
+    Returns
+    -------
+    currents : np.ndarray
+        (n_channels, n_stims) The optimized currents to drive the multichannel array.
+    score : float
+        Final score of the solution.
+    """
+    if e.ndim == 2:
+        n_channel = e.shape[1]
+        n_ele = int(e.shape[0] / 3)
+    elif e.ndim == 3:
+        n_channel = e.shape[2]
+        n_ele = int(e.shape[0])
+    else:
+        raise ValueError
+
+    if currents_prev is None:
+        n_stim_opt = n_stim
+    else:
+        n_stim_opt = n_stim - currents_prev.shape[1]
+
+        if n_stim_opt <= 0:
+            raise ValueError("N_stim has to be larger than already optimized optimal values!")
+
+    # initial guess for currents for all channels * stimulations
+    if seed is not None:
+        np.random.seed(seed)
+    x0 = (np.random.rand(n_channel * n_stim_opt) * 2) -1
+    # print(x0[:5])
+    if verbose:
+        print(f"n_ele: {n_ele}, n_channels: {n_channel}, n_stims: {n_stim}")
+
+    # optimization algorithm
+    res = minimize(get_score_raw,
+                   args=(e, n_stim, n_ele, n_channel, currents_prev, opt_target),
+                   x0=x0,
+                   method=method,
+                   options={'disp': False, 'maxiter': maxiter},
+                   bounds=[(-1, 1) for _ in range(len(x0))],
+                   tol=1e-6)
+    # print(res.fun, res.success, res.message)
+
+    if currents_prev is None:
+        currents = np.reshape(res.x, (n_channel, n_stim))
+    else:
+        currents = np.hstack((currents_prev, np.reshape(res.x, (n_channel, n_stim - currents_prev.shape[1]))))
+    if opt_target == 'elms':
+        score = 1 / ((n_ele ** 2 - n_ele) / 2) * res.fun
+    elif opt_target == 'stims':
+        score = 1 / ((n_stim ** 2 - n_stim) / 2) * res.fun
+    else:
+        raise ValueError("opt_target has to be 'elms' or 'stims'")
+
+    return currents, score, res
+
+
+def optimize_currents_single_channel(e, n_stim, currents_prev=None, seed=None,
+                                     maxiter=200, method='SLSQP', verbose=False):
+    """
+    Optimize the coil placement selection for a single channel e-field set minimizing e-fields cross-correlation.
+
+    Parameters
+    ----------
+    e : np.ndarray of float
+        (n_elms3, n_placements).
+    n_stim : int
+        Number of stimulations.
+    currents_prev : np.ndarray of float, optional
+        (n_channels, n_stims_prev) Previous currents to append to.
+    seed : int, optional
+        Seed for random number generator.
+    maxiter : int, default=200
+        Max iterations of the optimization.
+    method : str, default: 'SLSQP'
+        Optimization method.
+    verbose : bool, default: False
+        Print additional information.
+
+    Returns
+    -------
+    currents :  np.ndarray
+        (n_channels, n_stims) The optimized currents to drive the multichannel array.
+    score : float
+        Final score of the solution.
+    """
+    n_placements = e.shape[0]
+    n_ele = e.shape[1]
+
+    if currents_prev is None:
+        n_stim_opt = n_stim
+    else:
+        n_stim_opt = n_stim - currents_prev.shape[0]
+
+        if n_stim_opt <= 0:
+            raise ValueError("N_stim has to be larger than already optimized optimal values!")
+
+    # initial guess for currents for all channels * stimulations
+    if seed is not None:
+        np.random.seed(seed)
+    x0 = np.random.randint(0, n_placements, n_stim_opt)
+    if verbose:
+        print(f"n_ele: {n_ele}, n_placements: {n_placements}, n_stims: {n_stim}")
+
+    # optimization algorithm
+    res = minimize(get_score_raw_single_channel,
+                   args=(e, currents_prev),
+                   x0=x0,
+                   method=method,
+                   options={'disp': False, 'maxiter': maxiter},
+                   bounds=[(0, n_placements) for _ in range(len(x0))])
+
+    # if currents_prev is None:
+    #     currents = np.reshape(res.x, (n_placements, n_stim))
+    # else:
+    #     currents = np.hstack((currents_prev, np.reshape(res.x, (n_placements, n_stim - currents_prev.shape[1]))))
+
+    score = 1 / ((n_ele ** 2 - n_ele) / 2) * res.fun
+    # score = res.fun
+
+    return res.x, score
+
+
+def get_score(x, e, n_stim, n_ele, n_channel, x_opt=None):
+    """
+    Normalize the score by the number of elements.
+
+    Parameters
+    ----------
+    x : np.ndarray of float
+        (n_channel * n_stim_opt, ) Vector to scale channels for each.
+    e : np.ndarray of float
+        (n_ele*3, n_channels) E-field.
+    n_stim : int
+        Number of stimulations to compute score for.
+    n_ele : int
+        Number of elements.
+    n_channel : int
+        Number of channels.
+    x_opt :  np.ndarray of float, optinonal
+        (n_pre_opt,) Previously optimized channel currents.
+
+    Returns
+    -------
+    score : float
+        The normalized score.
+    """
+    score_raw = get_score_raw(x, e, n_stim, n_ele, n_channel, x_opt)
+    return 1 / ((n_ele ** 2 - n_ele) / 2) * score_raw