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

pynibs/congruence/congruence.py

@@ -1,7 +1,7 @@
 import os
 import h5py
-import numpy as np
 import yaml
+import numpy as np
 import pynibs
 
 
@@ -15,15 +15,14 @@ def cf_curveshift_workhorse_stretch_correction(elm_idx_list, mep, mep_params, e,
     Parameters
     ----------
     elm_idx_list : np.ndarray
-        (chunksize) List of element indices, the congruence factor is computed for
+        (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.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,
@@ -31,7 +30,7 @@ def cf_curveshift_workhorse_stretch_correction(elm_idx_list, mep, mep_params, e,
         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])``)
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0]``)
 
     n_samples : int, default=100
         Number of data points to generate discrete mep and e curves.
@@ -41,7 +40,6 @@ def cf_curveshift_workhorse_stretch_correction(elm_idx_list, mep, mep_params, e,
     congruence_factor : np.ndarray of float
         (n_roi, n_datasets) Congruence factor in each element specified in elm_idx_list and for each input dataset.
     """
-
     stepsize = 1e-1
     n_datasets = len(e[0])
     n_elm = len(elm_idx_list)
@@ -94,7 +92,7 @@ def cf_curveshift_workhorse_stretch_correction(elm_idx_list, mep, mep_params, e,
             # find median mep cond
             e_mean = np.mean((e_max + e_min) / 2)
 
-            # return NaN if xmax-xmin is smaller than stepsize
+            # return nan if xmax-xmin is smaller than stepsize
             if np.any(e_max - e_min <= stepsize):
                 congruence_factor[elm_idx, i_datasets] = np.nan
 
@@ -161,9 +159,9 @@ def cf_curveshift_workhorse_stretch_correction(elm_idx_list, mep, mep_params, e,
 
                         # length of shifted curve as a function of position (gets longer while shifting)
                         len_mep_idx_shift = np.round(np.linspace(
-                                len_e_mep_start,
-                                len_e_mep_end,
-                                len_e_mep_start + len_e_ref + 2 * stepsize_local_shift[reference_idx]))
+                            len_e_mep_start,
+                            len_e_mep_end,
+                            len_e_mep_start + len_e_ref + 2 * stepsize_local_shift[reference_idx]))
 
                         # construct shift array (there are less 0 at the beginning and more at the end because the mep
                         # curve is stretched during shifting)
@@ -184,7 +182,7 @@ def cf_curveshift_workhorse_stretch_correction(elm_idx_list, mep, mep_params, e,
                         slice_indices = np.outer(len_mep_idx_shift[:, np.newaxis],
                                                  np.linspace(0, 1, len_e_mep_start)[np.newaxis, :])
                         slice_indices = np.round(
-                                np.add(slice_indices, np.arange(slice_indices.shape[0])[:, np.newaxis])).astype(int)
+                            np.add(slice_indices, np.arange(slice_indices.shape[0])[:, np.newaxis])).astype(int)
 
                         # the error is y-difference between mep[idx] and mep[reference].zero_padded
                         err = np.sqrt(np.sum((shift_array[slice_indices] - mep_shift) ** 2, axis=1))
@@ -266,8 +264,8 @@ def cf_curveshift_workhorse_stretch_correction_new(mep, mep_params, e, n_samples
         mep_c_shift = mep[idx].eval(i_c_shift, mep_params_c[i])
         # generate index shift list to compare curves
         slice_indices = np.outer(
-                np.round(np.linspace(n_c_before[i], n_c_after[i], n_c_before[i] + n_samples))[:, np.newaxis],
-                np.linspace(0, 1, n_c_before[i])[np.newaxis, :])
+            np.round(np.linspace(n_c_before[i], n_c_after[i], n_c_before[i] + n_samples))[:, np.newaxis],
+            np.linspace(0, 1, n_c_before[i])[np.newaxis, :])
         slice_indices = np.round(slice_indices + np.arange(slice_indices.shape[0])[:, np.newaxis])
         slice_indices = (slice_indices + (np.max(n_c_before) - n_c_before[i])).astype(int)
         # the error is y-difference between mep[idx] and mep[reference].zero_padded
@@ -301,7 +299,7 @@ def cf_curveshift_workhorse_stretch_correction_sign_new(mep, mep_params, e, n_sa
     Worker function for congruence factor computation - call from :py:class:`multiprocessing.Pool`.
     Calculates congruence factor 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``).
-    ``n_sample``s are taken from fitted_mep, within the range of the :py:class:`~pynibs.expio.Mep`.
+    ``n_sample`` are taken from fitted_mep, within the range of the :py:class:`~pynibs.expio.Mep`.
 
     Parameters
     ----------
@@ -379,8 +377,8 @@ def cf_curveshift_workhorse_stretch_correction_sign_new(mep, mep_params, e, n_sa
             mep_c_shift = mep[idx].eval(i_c_shift, mep_params_c[i])
             # generate index shift list to compare curves
             slice_indices = np.outer(
-                    np.round(np.linspace(n_c_before[i], n_c_after[i], n_c_before[i] + n_samples))[:, np.newaxis],
-                    np.linspace(0, 1, n_c_before[i])[np.newaxis, :])
+                np.round(np.linspace(n_c_before[i], n_c_after[i], n_c_before[i] + n_samples))[:, np.newaxis],
+                np.linspace(0, 1, n_c_before[i])[np.newaxis, :])
             slice_indices = np.round(slice_indices + np.arange(slice_indices.shape[0])[:, np.newaxis])
             slice_indices = (slice_indices + (np.max(n_c_before) - n_c_before[i])).astype(int)
             # the error is y-difference between mep[idx] and mep[reference].zero_padded
@@ -472,7 +470,6 @@ def cf_curveshift_workhorse_stretch_correction_variance(elm_idx_list, mep, mep_p
     congruence_factor : np.ndarray of float [n_roi, n_datasets]
         Congruence factor in each element specified in elm_idx_list and for each input dataset
     """
-
     stepsize = 1e-1
     n_datasets = len(e[0])
     n_elm = len(elm_idx_list)
@@ -527,7 +524,7 @@ def cf_curveshift_workhorse_stretch_correction_variance(elm_idx_list, mep, mep_p
             # find median mep cond
             e_mean = np.mean((e_max + e_min) / 2)
 
-            # return NaN if xmax-xmin is smaller than stepsize
+            # return nan if xmax-xmin is smaller than stepsize
             if np.any(e_max - e_min <= stepsize):
                 congruence_factor[elm_idx, i_datasets] = np.nan
 
@@ -591,9 +588,9 @@ def cf_curveshift_workhorse_stretch_correction_variance(elm_idx_list, mep, mep_p
 
                         # length of shifted curve as a function of position (gets longer while shifting)
                         len_mep_idx_shift = np.round(np.linspace(
-                                len_e_mep_start,
-                                len_e_mep_end,
-                                len_e_mep_start + len_e_ref + 2 * stepsize_local_shift[reference_idx]))
+                            len_e_mep_start,
+                            len_e_mep_end,
+                            len_e_mep_start + len_e_ref + 2 * stepsize_local_shift[reference_idx]))
 
                         # construct shift array (there are less 0 at the beginning and more at the end because the mep
                         # curve is stretched during shifting)
@@ -614,7 +611,7 @@ def cf_curveshift_workhorse_stretch_correction_variance(elm_idx_list, mep, mep_p
                         slice_indices = np.outer(len_mep_idx_shift[:, np.newaxis],
                                                  np.linspace(0, 1, len_e_mep_start)[np.newaxis, :])
                         slice_indices = np.round(
-                                np.add(slice_indices, np.arange(slice_indices.shape[0])[:, np.newaxis])).astype(int)
+                            np.add(slice_indices, np.arange(slice_indices.shape[0])[:, np.newaxis])).astype(int)
 
                         # the error is y-difference between mep[idx] and mep[reference].zero_padded
                         err = np.sqrt(np.sum((shift_array[slice_indices] - mep_shift) ** 2, axis=1))
@@ -642,10 +639,9 @@ def cf_variance_workhorse(elm_idx_list, mep, mep_params, e, old_style=True):
     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 used to calculate the MEP, accumulated into one array).
+        (n_mep_params_total) List of all mep parameters 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.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,
@@ -653,7 +649,7 @@ def cf_variance_workhorse(elm_idx_list, mep, mep_params, e, old_style=True):
         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])``)
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0]``)
 
     old_style: bool, default: True
         True:  Weight ``var(x_0_prime(r))`` with ``mean(e(r) * mean(Stimulator Intensity)``, taken from ``mep``
@@ -662,7 +658,7 @@ def cf_variance_workhorse(elm_idx_list, mep, mep_params, e, old_style=True):
     Returns
     -------
     congruence_factor: np.ndarray of float
-        (n_roi, n_datasets) Congruence factor in each element specified in elm_idx_list and for each input dataset
+        (n_roi, n_datasets) Congruence factor in each element specified in elm_idx_list and for each input dataset.
     """
     n_datasets = len(e[0])
     n_elm = len(elm_idx_list)
@@ -805,8 +801,7 @@ def cf_curveshift_workhorse(elm_idx_list, mep, mep_params, e, n_samples=100):
         (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.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,
@@ -823,7 +818,6 @@ def cf_curveshift_workhorse(elm_idx_list, mep, mep_params, e, n_samples=100):
     -------
     congruence_factor: np.ndarray of float
         (n_roi, n_datasets) Congruence factor in each element specified in elm_idx_list and for each input dataset.
-
     """
     n_datasets = len(e[0])
     n_elm = len(elm_idx_list)
@@ -895,7 +889,6 @@ def cf_curveshift_kernel(e_curve, mep_curve):
     congruence_factor: float
         Congruence factor for the n_cond electric field and MEP curves.
     """
-
     stepsize = 1e-1
     n_condition = len(mep_curve)
     e_min = np.min(e_curve, axis=1)  # minima of electric field for every condition
@@ -904,7 +897,7 @@ def cf_curveshift_kernel(e_curve, mep_curve):
     e_max = np.max(e_curve, axis=1)  # maxima of electric field for every condition
     e_max = np.floor(e_max / stepsize) * stepsize
 
-    # return NaN if xmax-xmin is smaller than stepsize
+    # return nan if xmax-xmin is smaller than stepsize
     if np.any(e_max - e_min <= stepsize):
         return np.nan
 
@@ -997,26 +990,25 @@ def extract_condition_combination(fn_config_cfg, fn_results_hdf5, conds, fn_out_
     Parameters
     ----------
     fn_config_cfg : str
-        Filename of .cfg file the permutation study was cinducted with
+        Filename of .cfg file the permutation study was conducted with.
     fn_results_hdf5 : str
         Filename of ``.hdf5`` results file generated by ``00_run_c_standard_compute_all_permutations.py``
         containing congruence factors and condition combinations.
     conds : list of str
         (n_cond) List containing condition combinations to extract and plot,
-        e.g. ``['P_0', 'I_225', 'M1_0', 'I_675', 'P_225']``).
+        e.g. ``['P_0', 'I_225', 'M1_0', 'I_675', 'P_225']``.
     fn_out_prefix : str
-        Prefix of output filenames of *_data.xdmf, *_data.hdf5 and *_geo.hdf5.
+        Prefix of output filenames of \*_data.xdmf, \*_data.hdf5 and \*_geo.hdf5.
 
     Returns
     -------
     <fn_out_prefix_data.xdmf> : .xdmf file
-        Output file linking *_data.hdf5 and *_geo.hdf5 file to plot in paraview.
+        Output file linking \*_data.hdf5 and \*_geo.hdf5 file to plot in paraview.
     <fn_out_prefix_data.hdf5> : .hdf5 file
         Output .hdf5 file containing the data.
     <fn_out_prefix_geo.xdmf> : .hdf5 file
         Output .hdf5 file containing the geometry information.
     """
-
     # Read config file
     with open(fn_config_cfg, 'r') as f:
         config = yaml.load(f)
@@ -1069,14 +1061,14 @@ def extract_condition_combination(fn_config_cfg, fn_results_hdf5, conds, fn_out_
 
     # recreate complete midlayer surface to write in .hdf5 geo file
     points_midlayer, con_midlayer = pynibs.make_GM_WM_surface(
-            gm_surf_fname=os.path.join(mesh_folder, subject.mesh[mesh_idx]['fn_lh_gm']),
-            wm_surf_fname=os.path.join(mesh_folder, subject.mesh[mesh_idx]['fn_lh_wm']),
-            delta=subject.roi[mesh_idx][roi_idx]['delta'],
-            x_roi=None,
-            y_roi=None,
-            z_roi=None,
-            layer=1,
-            fn_mask=None)
+        gm_surf_fname=os.path.join(mesh_folder, subject.mesh[mesh_idx]['fn_lh_gm']),
+        wm_surf_fname=os.path.join(mesh_folder, subject.mesh[mesh_idx]['fn_lh_wm']),
+        delta=subject.roi[mesh_idx][roi_idx]['delta'],
+        x_roi=None,
+        y_roi=None,
+        z_roi=None,
+        layer=1,
+        fn_mask=None)
 
     # write output files
     # save .hdf5 _geo file

pynibs/congruence/ext_metrics.py

@@ -16,7 +16,7 @@ def rsd_inverse_workhorse(elm_idx_list, mep, e):
     Parameters
     ----------
     elm_idx_list : np.ndarray
-         (chunksize) List of element indices, the congruence factor is computed for
+        (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
@@ -38,7 +38,6 @@ def rsd_inverse_workhorse(elm_idx_list, mep, e):
        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)
@@ -61,6 +60,38 @@ def rsd_inverse_workhorse(elm_idx_list, mep, e):
 
 
 def dvs_likelihood(params, x, y, verbose=True, normalize=False, bounds=[(1, 2), (1, 2)]):
+    """
+    Calculate the log likelihood of the DVS model with test data.
+
+    Parameters
+    ----------
+    params : list of float
+        List of parameters for the DVS model. The first two parameters are `sigma_x` and `sigma_y`,
+        and the remaining parameters are model-specific.
+    x : np.ndarray
+        Array of input data for the DVS model.
+    y : np.ndarray
+        Array of observed data corresponding to `x`.
+    verbose : bool, optional
+        If True, print detailed information about the likelihood calculation. Default is True.
+    normalize : bool, optional
+        If True, normalize the parameters to the specified bounds. Default is False.
+    bounds : list of tuple of float, optional
+        List of bounds for the parameters. Default is [(1, 2), (1, 2)].
+
+    Returns
+    -------
+    float
+        Negative log likelihood of the DVS model.
+
+    Notes
+    -----
+    The function calculates the posterior of the DVS model with test data by generating a posterior
+    distribution and binning the data. It then determines the log likelihood based on the kernel
+    density estimate of the binned data.
+
+    The function prints the likelihood and parameter values if `verbose` is True.
+    """
     start = time.time()
 
     # extract parameters
@@ -114,7 +145,7 @@ def dvs_likelihood(params, x, y, verbose=True, normalize=False, bounds=[(1, 2),
         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")
+            warnings.warn("kde.fit(y_post[mask][:, np.newaxis]) yield nan ... skipping bin")
             continue
 
         # get probability densities at data
@@ -151,14 +182,14 @@ def e_focal_workhorse(elm_idx_list, e):
     Parameters
     ----------
     elm_idx_list : np.ndarray
-        (chunksize) List of element indices, the congruence factor is computed for
+        (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
+        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])``)
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0]``)
 
     Returns
     -------
@@ -171,7 +202,6 @@ def e_focal_workhorse(elm_idx_list, e):
        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)
@@ -202,8 +232,8 @@ def e_cog_workhorse(elm_idx_list, mep, mep_params, e):
         (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.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,
@@ -211,7 +241,7 @@ def e_cog_workhorse(elm_idx_list, mep, mep_params, e):
         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])``)
+        * ``len(e[0]) = n_comp`` (e.g: ``e_mag = e[0]``)
 
     Returns
     -------
@@ -224,7 +254,6 @@ def e_cog_workhorse(elm_idx_list, mep, mep_params, e):
        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)

pynibs/congruence/stimulation_threshold.py

@@ -1,5 +1,4 @@
 import numpy as np
-
 import pynibs
 
 
@@ -248,7 +247,7 @@ def sigmoid_thresh(elm_idx, mep_curve, intensities, e, mep_threshold):
             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 = pynibs.expio.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,