pyNIBS 0.2024.8__py3-none-any.whl

pynibs/congruence/ext_metrics.py

@@ -0,0 +1,257 @@
+import time
+import warnings
+import numpy as np
+from sklearn.neighbors import KernelDensity
+
+import pynibs
+
+
+def rsd_inverse_workhorse(elm_idx_list, mep, e):
+    """
+    Worker function for RSD inverse computation after Bungert et al. (2017) [1]_, call from
+    :py:class:`multiprocessing.Pool`.
+    Calculates the RSD inverse for ``e = (E_mag, E_norm and/or E_tan)`` for given zaps and elements.
+    The computations are parallelized in terms of element indices (``elm_idx_list``).
+
+    Parameters
+    ----------
+    elm_idx_list : np.ndarray
+         (chunksize) List of element indices, the congruence factor is computed for
+    mep: list of :py:class:`~pynibs.expio.Mep`
+        (n_cond) List of fitted Mep object instances for all conditions.
+    e: list of list of np.ndarray of float
+        [n_cond][n_datasets][n_elm] Tuple of ``n_datasets`` of the electric field to compute the congruence factor for,
+        e.g. ``(e_mag, e_norm, e_tan)``.
+        Each dataset is a list over all conditions containing the electric field component of interest
+
+        * ``len(e) = n_cond``
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0])``)
+
+    Returns
+    -------
+    rsd_inv : np.ndarray of float
+        (n_roi, n_datasets) RSD inverse in each element specified in ``elm_idx_list`` and for each input dataset.
+
+    Notes
+    -----
+    .. [1] Bungert, A., Antunes, A., Espenhahn, S., & Thielscher, A. (2016).
+       Where does TMS stimulate the motor cortex? Combining electrophysiological measurements and realistic field
+       estimates to reveal the affected cortex position. Cerebral Cortex, 27(11), 5083-5094.
+    """
+
+    n_datasets = len(e[0])
+    n_elm = len(elm_idx_list)
+    n_conditions = len(mep)
+
+    rsd_inv = np.empty((n_elm, n_datasets))
+    mt_vec = np.empty((1, n_conditions))
+
+    for i_cond in range(n_conditions):
+        mt_vec[0, i_cond] = mep[i_cond].mt
+
+    e_arr = np.array(e)
+
+    for i_dataset in range(n_datasets):
+        e_mat = np.array(e_arr[:, i_dataset, np.array(elm_idx_list).astype(int)]).transpose()
+        std_vec = np.std(e_mat * mt_vec, axis=1)
+        mean_vec = np.mean(e_mat * mt_vec, axis=1)
+        rsd_inv[:, i_dataset] = 1 - (std_vec / mean_vec)
+
+    return rsd_inv
+
+
+def dvs_likelihood(params, x, y, verbose=True, normalize=False, bounds=[(1, 2), (1, 2)]):
+    start = time.time()
+
+    # extract parameters
+    p = np.zeros(len(params) - 2)
+
+    for i, p_ in enumerate(params):
+        if i == 0:
+            sigma_x = p_
+        elif i == 1:
+            sigma_y = p_
+        else:
+            p[i - 2] = p_
+
+    # denormalize parameters from [0, 1] to bounds
+    if normalize:
+        sigma_x = sigma_x * (bounds[0][1] - bounds[0][0]) + bounds[0][0]
+        sigma_y = sigma_y * (bounds[1][1] - bounds[1][0]) + bounds[1][0]
+
+        for i, p_ in enumerate(p):
+            p[i] = p[i] * (bounds[i + 2][1] - bounds[i + 2][0]) + bounds[i + 2][0]
+
+    if sigma_x < 0:
+        sigma_x = 0
+
+    if sigma_y < 0:
+        sigma_y = 0
+
+    # determine posterior of DVS model with test data
+    x_pre = np.linspace(np.min(x), np.max(x), 200000)
+    x_post = x_pre + np.random.normal(loc=0., scale=sigma_x, size=len(x_pre))
+    y_post = pynibs.expio.fit_funs.sigmoid(x_post, p=p) + np.random.normal(loc=0., scale=sigma_y, size=len(x_pre))
+
+    # bin data
+    n_bins = 50
+    dx_bins = (np.max(x_pre) - np.min(x_pre)) / n_bins
+    x_bins_loc = np.linspace(np.min(x_pre) + dx_bins / 2, np.max(x_pre) - dx_bins / 2, n_bins)
+
+    # determine probabilities of observations
+    kde = KernelDensity(bandwidth=0.01, kernel='gaussian')
+
+    l = []
+
+    for i in range(n_bins):
+        mask = np.logical_and(x_pre >= (x_bins_loc[i] - dx_bins / 2), x_pre < (x_bins_loc[i] + dx_bins / 2))
+        mask_data = np.logical_and(x >= (x_bins_loc[i] - dx_bins / 2), x < (x_bins_loc[i] + dx_bins / 2))
+
+        if np.sum(mask_data) == 0:
+            continue
+
+        # determine kernel density estimate
+        try:
+            kde_bins = kde.fit(y_post[mask][:, np.newaxis])
+        except ValueError:
+            warnings.warn("kde.fit(y_post[mask][:, np.newaxis]) yield NaN ... skipping bin")
+            continue
+
+        # get probability densities at data
+        kde_y_post_bins = np.exp(kde_bins.score_samples(y[mask_data][:, np.newaxis]))
+
+        l.append(kde_y_post_bins)
+
+    l = np.concatenate(l)
+
+    # mask out zero probabilities
+    l[l == 0] = 1e-100
+
+    # determine log likelihood
+    l = np.sum(np.log10(l))
+
+    stop = time.time()
+
+    if verbose:
+        parameter_str = [f"p[{i_p}]={p_:.5f}" for i_p, p_ in enumerate(p)]
+        print(f"Likelihood: {l:.1f} / sigma_x={sigma_x:.2f}, sigma_y={sigma_y:.2f}  " +
+              ", ".join(parameter_str) + f"({stop - start:.2f} sec)")
+
+    return -l
+
+
+def e_focal_workhorse(elm_idx_list, e):
+    """
+    Worker function to determine the site of stimulation after Aonuma et al. (2018) [1]_,
+    call from :py:class:`multiprocessing.Pool`.
+    Calculates the site of stimulation for ``e = (E_mag, E_norm and/or E_tan)`` for given zaps and elements by
+    multiplying the electric fields with each other.
+    The computations are parallelized in terms of element indices (``elm_idx_list``).
+
+    Parameters
+    ----------
+    elm_idx_list : np.ndarray
+        (chunksize) List of element indices, the congruence factor is computed for
+    e: list of list of np.ndarray of float
+        [n_cond][n_datasets][n_elm] Tuple of ``n_datasets`` of the electric field to compute the congruence factor for,
+        e.g. ``(e_mag, e_norm, e_tan)``.
+        Each dataset is a list over all conditions containing the electric field component of interest
+
+        * ``len(e) = n_cond``
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0])``)
+
+    Returns
+    -------
+    e_focal : np.ndarray of float
+        (n_roi, n_datasets) Focal electric field in each element specified in ``elm_idx_list`` and for each input.
+
+    Notes
+    -----
+    .. [1] Aonuma, S., Gomez-Tames, J., Laakso, I., Hirata, A., Takakura, T., Tamura, M., & Muragaki, Y. (2018).
+       A high-resolution computational localization method for transcranial magnetic stimulation mapping.
+       NeuroImage, 172, 85-93.
+    """
+
+    n_datasets = len(e[0])
+    n_elm = len(elm_idx_list)
+    n_conditions = len(e)
+
+    e_focal = np.ones((n_elm, n_datasets))
+
+    for i_dataset in range(n_datasets):
+        for i_cond in range(n_conditions):
+            e_focal[:, i_dataset] *= e[i_cond][i_dataset][elm_idx_list]
+
+    return e_focal
+
+
+def e_cog_workhorse(elm_idx_list, mep, mep_params, e):
+    """
+    Worker function for electric field center of gravity (e_cog) computation after Opitz et al. (2013) [1]_
+    - call from :py:class:`multiprocessing.Pool`. Calculates the e_cog for ``e = (E_mag, E_norm and/or E_tan)`` for given zaps
+    and elements. The electric field is weighted by the mean MEP amplitude (turning point of the sigmoid) and summed up.
+    The computations are parallelized in terms of element indices (``elm_idx_list``).
+
+    Parameters
+    ----------
+    elm_idx_list : np.ndarray
+        (chunksize) List of element indices, the congruence factor is computed for.
+    mep : list of :py:class:`~pynibs.expio.Mep`
+        (n_cond) List of fitted Mep object instances for all conditions.
+    mep_params : np.ndarray of float
+        (n_mep_params_total) List of all mep parameters of curve fits used to calculate the MEP, accumulated into
+        one array.
+
+        * e.g. [``mep_#1_para_#1``, ``mep_#1_para_#2``, ``mep_#1_para_#3``, ``mep_#2_para_#1``,
+        ``mep_#2_para_#1``, ...]
+
+    e : list of list of np.ndarray of float
+        [n_cond][n_datasets][n_elm] Tuple of n_datasets of the electric field to compute the congruence factor for,
+        e.g. ``(e_mag, e_norm, e_tan)``.
+        Each dataset is a list over all conditions containing the electric field component of interest
+
+        * e.g.: ``len(e) = n_cond``
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0])``)
+
+    Returns
+    -------
+    e_cog : np.ndarray of float
+     (n_roi, n_datasets) RSD inverse in each element specified in ``elm_idx_list`` and for each input dataset.
+
+    Notes
+    -----
+    .. [1] Opitz, A., Legon, W., Rowlands, A., Bickel, W. K., Paulus, W., & Tyler, W. J. (2013).
+       Physiological observations validate finite element models for estimating subject-specific electric field
+       distributions induced by transcranial magnetic stimulation of the human motor cortex. Neuroimage, 81, 253-264.
+    """
+
+    n_datasets = len(e[0])
+    n_elm = len(elm_idx_list)
+    n_conditions = len(mep)
+
+    mep_params = np.array(mep_params).flatten()
+    mep_params_cond = []
+    start_idx = 0
+    e_cog = np.empty((n_elm, n_datasets))
+    mep_mean_vec = np.empty((1, n_conditions))
+    intensity_mep_mean_vec = np.empty((1, n_conditions))
+
+    # extract parameters
+    for i_cond in range(n_conditions):
+        mep_params_cond.append(mep_params[start_idx:(start_idx + mep[i_cond].popt.size)])
+        start_idx = start_idx + mep[i_cond].popt.size
+
+        # stimulator intensity in [A/us] for mean MEP amplitude, i.e. turning point of pynibs.sigmoid (1st para of
+        # sigmoid)
+        intensity_mep_mean_vec[0, i_cond] = mep[i_cond].popt[0]
+
+        # mean MEP amplitude (function value at 1st parameter of pynibs.sigmoid)
+        mep_mean_vec[0, i_cond] = mep[i_cond].eval(mep_params_cond[-1][0], mep_params_cond[-1])
+
+    e_arr = np.array(e)
+
+    for i_dataset in range(n_datasets):
+        e_mat = np.array(e_arr[:, i_dataset, np.array(elm_idx_list).astype(int)]).transpose()
+        e_cog[:, i_dataset] = np.sum(e_mat * (intensity_mep_mean_vec * mep_mean_vec), axis=1)
+
+    return e_cog

pynibs/congruence/stimulation_threshold.py

@@ -0,0 +1,318 @@
+import numpy as np
+
+import pynibs
+
+
+def stimulation_threshold(elm_idx_list, mep, mep_params, n_samples, e, c_factor_percentile=95, mep_threshold=0.5,
+                          c_factor=None, c_function=None, t_function=None):
+    """
+    Computes the stimulation threshold in terms of the electric field in [V/m]. The threshold is defined as the
+    electric field value where the mep exceeds mep_threshold. The average value is taken over all mep curves in each
+    condition and over an area where the congruence factor exceeds ``c_factor_percentile``.
+
+    Parameters
+    ----------
+    elm_idx_list : np.ndarray
+        (chunksize) List of element indices, the congruence factor is computed for.
+    mep : list of Mep object instances
+        (n_cond) List of fitted :py:class:`~pynibs.expio.Mep` object instances for all conditions.
+    mep_params : np.ndarray of float [n_mep_params_total]
+        List of all mep parameters of curve fits used to calculate the MEP (accumulated into one array)
+
+        * e.g. [``mep_#1_para_#1``, ``mep_#1_para_#2``, ``mep_#1_para_#3``, ``mep_#2_para_#1``, ``mep_#2_para_#1``, ...]
+
+    n_samples : int
+        Number of data points to generate discrete mep and e curves.
+    e : list of list of np.ndarray of float
+        [n_cond][n_datasets][n_elm] Tuple of ``n_datasets`` of the electric field to compute the congruence factor for,
+        e.g. ``(e_mag, e_norm, e_tan)``.
+        Each dataset is a list over all conditions containing the electric field component of interest
+
+        * e.g.: ``len(e) = n_cond``
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0])``)
+    c_factor_percentile : float
+        Percentile of the c_factor taken into account for the threshold evaluation. Only c_factors are considered
+        exceeding this.
+    mep_threshold : float
+        MEP value in [mV], which has to be exceeded for threshold definition.
+    c_factor : np.ndarray of float
+    (n_roi, n_datasets) Congruence factor in each element specified in elm_idx_list and for each input dataset.
+    c_function : function
+        Defines the function to use during c_gpc to calculate the congruence factor.
+
+        * congruence_factor_curveshift_workhorse: determines the average curve shift
+        * congruence_factor_curveshift_workhorse_stretch_correction: determines the average curve shift
+        * congruence_factor_curveshift_workhorse_stretch_correction_variance: determines the average curve shift
+        * congruence_factor_variance_workhorse: evaluates the variance of the shifting and stretching parameters
+
+    t_function : function
+        Defines the function to determine the stimulation_threshold.
+
+        * stimulation_threshold_mean_mep_threshold: uses mep_threshold to determine the corresponding e_threshold over
+          all conditions and takes the average values as the stimulation threshold
+        * stimulation_threshold_pynibs.sigmoid: Fits a new pynibs.sigmoid using all datapoints in the mep-vs-E space and
+          evaluates the threshold from the turning point or the intersection of the derivative in the crossing point
+          with the e-axis
+
+    Returns
+    -------
+    stim_threshold_avg: float
+        Average stimulation threshold in [V/m] where c_factor is greater than ``c_factor_percentile``.
+    """
+
+    n_datasets = len(e[0])
+    n_conditions = len(mep)
+    mep_params = np.array(mep_params).flatten()
+
+    # rearrange mep parameters to individual conditions
+    mep_params_cond = []
+    start_idx = 0
+
+    for i_cond in range(n_conditions):
+        mep_params_cond.append(mep_params[start_idx:(start_idx + mep[i_cond].popt.size)])
+        start_idx = start_idx + mep[i_cond].popt.size
+
+    # calculate mep curves per condition
+    mep_curve = []
+    intensities = []
+
+    for i_cond in range(n_conditions):
+        intensities.append(np.linspace(mep[i_cond].x_limits[0], mep[i_cond].x_limits[1], n_samples))
+        mep_curve.append(mep[i_cond].eval(intensities[-1], mep_params_cond[i_cond]))
+
+    # determine congruence factor, if not provided
+    if not c_factor.any():
+        if c_function == pynibs.congruence.cf_curveshift_workhorse or \
+                c_function == pynibs.congruence.cf_curveshift_workhorse_stretch_correction or \
+                c_function == pynibs.congruence.cf_curveshift_workhorse_stretch_correction_variance:
+            c_factor = c_function(elm_idx_list,
+                                  mep=mep,
+                                  mep_params=mep_params,
+                                  n_samples=n_samples,
+                                  e=e)
+
+        elif c_function == pynibs.congruence.cf_variance_workhorse:
+            c_factor = c_function(elm_idx_list,
+                                  mep=mep,
+                                  mep_params=mep_params,
+                                  e=e)
+
+    # determine elements where the congruence factor exceeds c_factor_percentile
+    elm_idx = []
+    c_factor_percentile_value = []
+
+    for i_data in range(n_datasets):
+        c_factor_percentile_value.append(np.percentile(c_factor[np.logical_not(np.isnan(c_factor[:, i_data])), i_data],
+                                                       c_factor_percentile))
+        elm_idx.append(np.where(c_factor[:, i_data] > c_factor_percentile_value[i_data])[0])
+
+    if t_function == mean_mep_threshold:
+        stim_threshold_avg, stim_threshold_std = \
+            mean_mep_threshold(elm_idx=elm_idx,
+                               mep_curve=mep_curve,
+                               intensities=intensities,
+                               e=e,
+                               mep_threshold=mep_threshold)
+
+    elif t_function == sigmoid_thresh:
+        stim_threshold_avg, stim_threshold_std = \
+            sigmoid_thresh(elm_idx=elm_idx,
+                           mep_curve=mep_curve,
+                           intensities=intensities,
+                           e=e,
+                           mep_threshold=mep_threshold)
+
+    elif t_function == intensity_thresh:
+        stim_threshold_avg = \
+            intensity_thresh(mep_curve=mep_curve,
+                             intensities=intensities,
+                             mep_threshold=mep_threshold)
+        stim_threshold_std = np.nan
+
+    else:
+        raise NotImplementedError('Provided t_function not implemented yet!')
+
+    return stim_threshold_avg, stim_threshold_std
+
+
+def mean_mep_threshold(elm_idx, mep_curve, intensities, e, mep_threshold):
+    """
+    Determines the stimulation threshold by calculating the average electric field over all conditions, where the
+    mep curves exceed the value of mep_threshold (in [mV]).
+
+    Parameters
+    ----------
+    elm_idx : list of np.ndarray of int
+        [n_datasets](n_elements) Element indices where the congruence factor exceeds a certain percentile,
+        defined during the call of :py:meth:`stimulation_threshold`.
+    mep_curve : list  of np.ndarray of float
+        [n_conditions](n_samples) MEP curve values for every condition.
+    intensities : list  of np.ndarray of float
+        [n_conditions](n_samples) To the MEP values corresponding stimulator intensities in [A/us].
+    e : list of list of np.ndarray of float
+        [n_cond][n_datasets][n_elm] Tuple of n_datasets of the electric field to compute the congruence factor for,
+        e.g. ``(e_mag, e_norm, e_tan)``.
+        Each dataset is a list over all conditions containing the electric field component of interest
+
+        * e.g.: ``len(e) = n_cond``
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0])``)
+
+    mep_threshold : float
+        MEP value in [mV], which has to be exceeded for threshold definition.
+
+    Returns
+    -------
+    stim_threshold_avg : float
+        Average stimulation threshold in [V/m] where c_factor is greater than c_factor_percentile
+    """
+
+    n_conditions = len(mep_curve)
+    n_datasets = len(e[0])
+
+    # determine electric field values exceeding mep_threshold in this elements
+    stim_threshold_cond = [np.zeros((elm_idx[i_data].size, n_conditions)) * np.nan for i_data in range(n_datasets)]
+    stim_threshold_avg = [np.nan for _ in range(n_datasets)]
+    stim_threshold_std = [np.nan for _ in range(n_datasets)]
+
+    for i_cond in range(n_conditions):
+        e_threshold_idx = np.where(mep_curve[i_cond] > mep_threshold)[0]
+
+        if e_threshold_idx.any():
+            for i_data in range(n_datasets):
+                stim_threshold_cond[i_data][:, i_cond] = e[i_cond][i_data][elm_idx[i_data]] * \
+                                                         intensities[i_cond][e_threshold_idx[0]]
+
+    for i_data in range(n_datasets):
+        stim_threshold_avg[i_data] = np.mean(
+                stim_threshold_cond[i_data][np.logical_not(np.isnan(stim_threshold_cond[i_data]))])
+        stim_threshold_std[i_data] = np.std(
+                stim_threshold_cond[i_data][np.logical_not(np.isnan(stim_threshold_cond[i_data]))])
+
+    return stim_threshold_avg, stim_threshold_std
+
+
+def sigmoid_thresh(elm_idx, mep_curve, intensities, e, mep_threshold):
+    """
+    Determines the stimulation threshold by calculating an equivalent :py:class:`pynibs.expio.Mep.sigmoid`
+    over all conditions. The stimulation threshold is the electric field value where the mep curves exceed the value of
+    mep_threshold (in [mV]).
+
+    Parameters
+    ----------
+    elm_idx : list of np.ndarray of int
+        [n_datasets](n_elements) Element indices where the congruence factor exceeds a certain percentile,
+        defined during the call of :py:meth:`stimulation_threshold`.
+    mep_curve : list  of np.ndarray of float
+        [n_conditions](n_samples) MEP curve values for every condition.
+    intensities : list  of np.ndarray of float
+        [n_conditions](n_samples) To the MEP values corresponding stimulator intensities in [A/us].
+    e : list of list of np.ndarray of float
+        [n_cond][n_datasets][n_elm] Tuple of n_datasets of the electric field to compute the congruence factor for,
+        e.g. ``(e_mag, e_norm, e_tan)``.
+        Each dataset is a list over all conditions containing the electric field component of interest
+
+        * e.g.: ``len(e) = n_cond``
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0])``)
+
+    mep_threshold : float
+        MEP value in [mV], which has to be exceeded for threshold definition
+
+    Returns
+    -------
+    stim_threshold_avg : float
+        Average stimulation threshold in [V/m] where c_factor is greater than c_factor_percentile
+    """
+
+    n_conditions = len(mep_curve)
+    n_datasets = len(e[0])
+    stim_threshold_elm = [[] for _ in range(n_datasets)]
+    stim_threshold_avg = [[] for _ in range(n_datasets)]
+    stim_threshold_std = [[] for _ in range(n_datasets)]
+
+    # accumulate all data values in one array
+    mep_curve_all = np.hstack(mep_curve)
+
+    for i_data in range(n_datasets):
+        print(('Evaluating stimulation threshold for dataset {}/{}'.format(i_data + 1, n_datasets)))
+        n_elms = len(elm_idx[i_data])
+        stim_threshold_elm[i_data] = np.zeros(n_elms) * np.nan
+
+        for i_elm, elm in enumerate(elm_idx[i_data]):
+            print((' > Element {}/{}'.format(i_elm, n_elms)))
+
+            # accumulate all data values in one array
+            e_all = []
+
+            for i_cond in range(n_conditions):
+                e_all.append(e[i_cond][i_data][elm] * intensities[i_cond])
+            e_all = np.hstack(e_all)
+
+            # fit data to function
+            mep = pynibs.Mep(intensities=e_all, mep=mep_curve_all, intensity_min_threshold=0, mep_min_threshold=0)
+            mep.fit = mep.run_fit_multistart(pynibs.expio.fit_funs.sigmoid,
+                                             x=e_all,
+                                             y=mep_curve_all,
+                                             p0=[70, 0.6, 2],
+                                             constraints=None,
+                                             verbose=False,
+                                             n_multistart=20)
+
+            # read out optimal function parameters from best fit
+            try:
+                for p in ['x0', 'r', 'amp']:
+                    mep.popt.append(mep.fit.best_values[p])
+
+                mep.popt = np.asarray(mep.popt)
+                mep.cvar = np.asarray(mep.fit.covar)
+                mep.pstd = np.sqrt(np.diag(mep.cvar))
+                mep.fun = pynibs.expio.fit_funs.sigmoid
+
+                # determine stimulation threshold
+                e_fit = np.linspace(np.min(e_all), np.max(e_all), 200)
+                mep_fit = mep.eval_opt(e_fit)
+                e_threshold_idx = np.where(mep_fit > mep_threshold)[0]
+
+                if e_threshold_idx.any():
+                    stim_threshold_elm[i_data][i_elm] = e_fit[e_threshold_idx[0]]
+
+            except (AttributeError, ValueError):
+                print(' > Warning: pynibs.sigmoid in element could not be fitted!')
+                stim_threshold_elm[i_data][i_elm] = np.nan
+
+        # determine mean threshold over all elements
+        stim_threshold_avg[i_data] = np.mean(stim_threshold_elm[i_data]
+                                             [np.logical_not(np.isnan(stim_threshold_elm[i_data]))])
+        stim_threshold_std[i_data] = np.std(stim_threshold_elm[i_data]
+                                            [np.logical_not(np.isnan(stim_threshold_elm[i_data]))])
+
+    return stim_threshold_avg, stim_threshold_std
+
+
+def intensity_thresh(mep_curve, intensities, mep_threshold):
+    """
+    Determines the stimulation threshold of one particular condition (usually the most sensitive e.g. M1-45). The
+    stimulation threshold is the stimulator intensity value in [A/us] where the mep curves exceed the value of
+    mep_threshold (in [mV]).
+
+    Parameters
+    ----------
+    mep_curve: list [1] of np.ndarray of float [n_samples]
+        MEP curve values for every conditions
+    intensities: list [1] of np.ndarray of float [n_samples]
+        To the MEP values corresponding stimulator intensities in [A/us]
+    mep_threshold: float
+        MEP value in [mV], which has to be exceeded for threshold definition
+
+    Returns
+    -------
+    stim_threshold_avg: float
+        Average stimulation threshold in [V/m] where c_factor is greater than c_factor_percentile
+    """
+
+    stim_threshold = np.nan
+    i_threshold_idx = np.where(mep_curve[0] > mep_threshold)[0]
+
+    if i_threshold_idx.any():
+        stim_threshold = intensities[0][i_threshold_idx[0]]
+
+    return stim_threshold

pynibs/data/configuration_exp0.yaml

@@ -0,0 +1,59 @@
+########################################################################################################################
+# This configuration file can be used to set values in pynibs.Element() that influence the regression.                 #
+########################################################################################################################
+#
+#
+############################################## General regression concept ##############################################
+# While trying to find the best fit, many possible regression functions are calculated and the best one is picked.
+# Usually, that is the one that explains the most noise, meaning that the data points have a minimal distance to the
+# regression function. The function exp0 always looks like the following term, with varying coefficients x_0 and r:
+##     y = e^{r(x-x_0)}
+##     (r : Slope parameter (steepness))
+##     (x0 : Horizontal shift along the abscissa)
+
+# The usual approach is to start with a function described by some initial values (init_vals) for x_0 and r and try out
+# many other values within the value limits (limits), minimizing the distance between regression function and real data.
+# During refitting, different initial vales (calculated within the random_vals_init_range) are used to see whether a
+# better result can be achieved.
+
+############################################### Picking suitable values ################################################
+# Initial values for the regression coefficients
+init_vals:
+  r: 0.1
+  x0: 10
+# Strategy: Pick the values you may expect the result to have, or that are not far-fetched. Picking reasonable initial
+# values can speed up the fitting procedure.
+
+# Values that limit all possible regression coefficients:
+limits:
+  r:
+  - 1.0e-12
+  - 100
+  x0:
+  - 0
+  - 1000
+# Strategy: Rather wide range recommended, since a few points could have very extreme values and therefore be
+# approximated by a function very different from the expected values. E.g. a multiple of the presented data range.
+# (Note: This should not be used to factor out outliers, since an approximation will still be calculated, but with too
+# narrow limits it will just be a very bad one.)
+
+# Value range for the calculation of new initial values for refits:
+random_vals_init_range:
+  r:
+  - 0
+  - 0.2
+  x0:
+  - 0
+  - 10
+# Strategy: During refitting, new initial values are calculated by picking a random number between these lower and upper
+# bounds, so the range should be a lot smaller than 'limits' and somewhat symmetrical around the 'init_vals'.
+
+
+# Example usage:
+##
+##        configfile = configuration_exp0.yaml
+##        with open(configfile, "r") as yamlfile:
+##            config = yaml.load(yamlfile, Loader=yaml.FullLoader)
+##
+##        pynibs.regress_data(...,
+##                           **configfile)