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

pynibs/optimization/{optimization.py → coil_opt.py}

@@ -1,5 +1,5 @@
 """
-The `optimizhat.py` module provides functions for optimizing coil placements in Transcranial Magnetic Stimulation
+The `coil_opt.py` module provides functions for optimizing coil placements in Transcranial Magnetic Stimulation
 (TMS) based on given electric field matrices and fMRI statistics. It includes functions for identifying optimal coil
 placement regions, calculating the gain map between a reference and an optimized sequence of electric fields,
 and performing virtual online optimization to determine the congruence factor.
@@ -7,19 +7,15 @@ and performing virtual online optimization to determine the congruence factor.
 The module includes the following functions:
 
 - `rowvec_diff()`: This function returns the coil configuration out of all available configurations exhibiting the
-highest minimum difference to the already selected configurations.
-
+  highest minimum difference to the already selected configurations.
 - `get_optimal_coil_positions()`: This function determines a set of optimal coil positions for TMS regression analysis.
-
 - `online_optimization()`: This function performs virtual online optimization to determine the congruence factor.
-After an initial set of coil positions, the algorithm iteratively optimizes the next coil position based on the
-virtually measured MEP data.
-
+  After an initial set of coil positions, the algorithm iteratively optimizes the next coil position based on the
+  virtually measured MEP data.
 - `calc_opt_gain_map()`: This function calculates the gain map between a reference e_matrix (e.g. from random
-sampling) and an optimized sequence of electric fields for mapping.
-
+  sampling) and an optimized sequence of electric fields for mapping.
 - `optimal_coilplacement_region()`: This function identifies the optimal coil placement regions based on given
-electric field (E-field) matrices and fMRI statistics.
+  electric field (E-field) matrices and fMRI statistics.
 
 Each function in this module is documented with docstrings providing more detailed information about its purpose,
 parameters, and return values.
@@ -31,8 +27,6 @@ import h5py
 import numpy as np
 import multiprocessing
 from functools import partial
-from matplotlib import pyplot as plt
-
 import pynibs
 
 
@@ -42,11 +36,13 @@ def rowvec_diff(candidate_coil_idcs, selected_coil_idcs, efields_diff_mat):
     returns the coil configuration out of all available configurations exhibiting the
     highest minimum difference to the already selected configurations.
 
-    :param candidate_coil_idcs: np.ndarry[int]
+    Parameters
+    ----------
+    candidate_coil_idcs : np.ndarry[int]
         List of indices of coil configurations that are still available to pick for the optiized sequence.
-    :param selected_coil_idcs: np.ndarray[int]
+    selected_coil_idcs : np.ndarray[int]
         List of indices of coil configurations that have already been selected for the optimized sequence.
-    :param efields_diff_mat: np.ndarray[float], [n_coil,n_coil]
+    efields_diff_mat : np.ndarray[float], [n_coil,n_coil]
         Difference matrix, where each cell denotes the magnitude of the difference vector between
         two coil configurations (determined by row_idx,col_idx).
 
@@ -55,7 +51,6 @@ def rowvec_diff(candidate_coil_idcs, selected_coil_idcs, efields_diff_mat):
     coil_idx: int
         index of coil configuration with maximal minimal difference to the set of already selected coil configurations.
     """
-
     # min_diff_selected_to_all_coil_pos = matrix with:
     #   rows -> set of selected coil configurations (selected_coil_idcs)
     #   columns -> available coil configuration for optimization (candidate_coil_idcs)
@@ -114,9 +109,9 @@ def get_optimal_coil_positions(
     n_stim : int
         Maximum number of stimulations.
     ele_idx_1 : np.ndarray of int, optional
-        Element indices the first optimization goal is performed for, If None, all elements are consiered.
+        Element indices the first optimization goal is performed for, If None, all elements are considered.
     ele_idx_2 : np.ndarray of int, optional
-        Element indices the first optimization goal is performed for. If None, all elements are consiered.
+        Element indices the first optimization goal is performed for. If None, all elements are considered.
     n_cpu : int
         Number of threads.
     fn_out_hdf5 : str, optional
@@ -142,7 +137,7 @@ def get_optimal_coil_positions(
     metrics_weights : list of float [2], default: [0.5, 0.5]
         Weights of optimization criteria in case of multiple goal functions (e_all_coil_pos.g. fim_svd).
         Higher weight means higher importance for the respective criteria.
-        By default both optimization criteria are weighted equally [0.5, 0.5].
+        By default, both optimization criteria are weighted equally [0.5, 0.5].
     overwrite : bool, default: True
         Overwrite existing solutions or read existing hdf5 file and continue optimization.
     verbose : bool, default: True
@@ -159,7 +154,7 @@ def get_optimal_coil_positions(
         Not required for any other metric than FIM.
     fim_mso_didt_conversion_factor : float, default: 1.43
         Factor to convert between realized current (dI/dt) and percentage of maximum stimulator output (%MSO).
-        Defaults to 1.43 describing the factor of a Magventure Pro with an MCF-B65 coil.
+        Defaults to 1.43 describing the factor of a MagVenture Pro with an MCF-B65 coil.
         Not required for any other metric than FIM.
     fim_visited_positions_e_mat : np.ndarray[float], (len(zap_idx_opt], n_ele), optional
         The efield matrix computed using the actually approached coil configurations.
@@ -177,7 +172,7 @@ def get_optimal_coil_positions(
         Number of refits used in the mag(E)<>p2p regression during FIM optimization.
         Not required for any other metric than FIM.
     fim_debug_screenshot_dir_fn : str
-        String representation of the fully qualified path to a directory where a 3D rendering of the
+        String representation of the fully qualified path to a directory where a 3D rendering of
         the FIM optimal coil positions, ie coil positions that can reach the FIM optimal e-field strength
         at the current target hotspot given the MSO bounds [fim_rmt_mso, 100], should be saved.
         Not required for any other metric than FIM.
@@ -288,8 +283,9 @@ def get_optimal_coil_positions(
     if criterion == "rowvec_diff":
         # Preparation for the rowvec difference metric is independent of the number of requested stimulation (n_stim):
         #   Compute the difference matrix.
-        workhorse_prepare = partial(pynibs.optimization.workhorses.rowvec_diff_prepare, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
-        coil_idx_list_chunks = pynibs.compute_chunks(list(range(e_all_coil_pos.shape[0])), n_cpu)
+        workhorse_prepare = partial(pynibs.optimization.workhorses.rowvec_diff_prepare, array=e_all_coil_pos,
+                                    ele_idx_1=ele_idx_1)
+        coil_idx_list_chunks = pynibs.util.utils.compute_chunks(list(range(e_all_coil_pos.shape[0])), n_cpu)
         res = pool.map(workhorse_prepare, coil_idx_list_chunks)
 
         # sum all difference matrices up = create upper triangle difference matrix
@@ -329,9 +325,9 @@ def get_optimal_coil_positions(
 
         # preparatory functions of some of the result metrics
         if criterion == "coverage":
-            workhorse_prepare = partial(workhorses.coverage_prepare, array=e_all_coil_pos,
+            workhorse_prepare = partial(pynibs.optimization.workhorses.coverage_prepare, array=e_all_coil_pos,
                                         zap_idx=zap_idx_e_opt[:idx_in_result_list - 1])
-            ele_idx_list_chunks = pynibs.compute_chunks([j for j in range(e_all_coil_pos.shape[1])], n_cpu)
+            ele_idx_list_chunks = pynibs.util.utils.compute_chunks([j for j in range(e_all_coil_pos.shape[1])], n_cpu)
             res = pool.map(workhorse_prepare, ele_idx_list_chunks)
 
             x = np.zeros((1, 1))
@@ -345,7 +341,7 @@ def get_optimal_coil_positions(
                     x = np.hstack((x, res[j][0]))
                     y = np.hstack((y, res[j][1]))
 
-            workhorse_partial = partial(workhorses.coverage, array=e_all_coil_pos, x=x, y=y)
+            workhorse_partial = partial(pynibs.optimization.workhorses.coverage, array=e_all_coil_pos, x=x, y=y)
         # Preprocessing of metrics combined with FIM:
         # - determine the required %MSO for each candidate location via FIM
         # - determine valid candidate locations that can achieve a FIM optimal mag(E) within the valid range of
@@ -368,7 +364,7 @@ def get_optimal_coil_positions(
                 raise ValueError("[Error] get_optimal_coil_positions: requested FIM optimal sampling without"
                                  "specifying a specific resting motor threshold (fim_rmt_mso).")
 
-            if fim_fit_fun == pynibs.sigmoid4 or fim_fit_fun == pynibs.sigmoid4_log:
+            if fim_fit_fun == pynibs.expio.sigmoid4 or fim_fit_fun == pynibs.expio.sigmoid4_log:
                 default_sigmoid_params = {
                     "x0": 0.5,
                     "y0": 1e-10,
@@ -415,7 +411,7 @@ def get_optimal_coil_positions(
                 e_realized_in_hotspot_np = np.zeros((e_realized_in_hotspot.shape[0], 1))
                 e_realized_in_hotspot_np[:, 0] = e_realized_in_hotspot
 
-                _, regression_sigmoid_fitparams = pynibs.regress_data(
+                _, regression_sigmoid_fitparams = pynibs.regression.regress_data(
                         e_matrix=e_realized_in_hotspot_np,
                         mep=fim_p2p_amps,
                         fun=fim_fit_fun,
@@ -517,85 +513,109 @@ def get_optimal_coil_positions(
 
         # prepare the result metrics for the parallel execution
         if criterion == "svd":
-            workhorse_partial = partial(workhorses.svd, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
+            workhorse_partial = partial(pynibs.optimization.workhorses.svd, array=e_all_coil_pos,
+                                        ele_idx_1=ele_idx_1)
 
         elif criterion == "dist":
-            workhorse_partial = partial(workhorses.dist, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
+            workhorse_partial = partial(pynibs.optimization.workhorses.dist, array=e_all_coil_pos,
+                                        ele_idx_1=ele_idx_1)
 
         elif criterion == "mc_cols":
             e_all_coil_pos = e_all_coil_pos - np.mean(e_all_coil_pos[:, ele_idx_1], axis=1)[:, np.newaxis]
-            workhorse_partial = partial(workhorses.mc, array=e_all_coil_pos, ele_idx_1=ele_idx_1, mode="cols")
+            workhorse_partial = partial(pynibs.optimization.workhorses.mc, array=e_all_coil_pos,
+                                        ele_idx_1=ele_idx_1,
+                                        mode="cols")
 
         elif criterion == "mc_rows":
-            workhorse_partial = partial(workhorses.mc, array=e_all_coil_pos, ele_idx_1=ele_idx_1, mode="rows")
+            workhorse_partial = partial(pynibs.optimization.workhorses.mc, array=e_all_coil_pos,
+                                        ele_idx_1=ele_idx_1, mode="rows")
 
         elif criterion == "variability":
-            workhorse_partial = partial(workhorses.variability, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
+            workhorse_partial = partial(pynibs.optimization.workhorses.variability, array=e_all_coil_pos,
+                                        ele_idx_1=ele_idx_1)
 
         elif criterion == "dist_mc_cols":
             if metrics_weights[0] == 0:
-                workhorse_partial = partial(workhorses.mc, array=e_all_coil_pos, ele_idx_1=ele_idx_2, mode="cols")
+                workhorse_partial = partial(pynibs.optimization.workhorses.mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_2, mode="cols")
             elif metrics_weights[1] == 0:
-                workhorse_partial = partial(workhorses.dist, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
+                workhorse_partial = partial(pynibs.optimization.workhorses.dist, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1)
             else:
-                workhorse_partial = partial(workhorses.dist_mc, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.dist_mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             ele_idx_2=ele_idx_2,
                                             mode="cols")
 
         elif criterion == "dist_mc_rows":
             if metrics_weights[0] == 0:
-                workhorse_partial = partial(workhorses.mc, array=e_all_coil_pos, ele_idx_1=ele_idx_2, mode="rows")
+                workhorse_partial = partial(pynibs.optimization.workhorses.mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_2, mode="rows")
             elif metrics_weights[1] == 0:
-                workhorse_partial = partial(workhorses.dist, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
+                workhorse_partial = partial(pynibs.optimization.workhorses.dist, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1)
             else:
-                workhorse_partial = partial(workhorses.dist_mc, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.dist_mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             ele_idx_2=ele_idx_2,
                                             mode="rows")
 
         elif criterion == "dist_svd":
             if metrics_weights[0] == 0:
-                workhorse_partial = partial(workhorses.svd, array=e_all_coil_pos, ele_idx_1=ele_idx_2)
+                workhorse_partial = partial(pynibs.optimization.workhorses.svd, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_2)
             elif metrics_weights[1] == 0:
-                workhorse_partial = partial(workhorses.dist, array=e_all_coil_pos, ele_idx_1=ele_idx_1)
+                workhorse_partial = partial(pynibs.optimization.workhorses.dist, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1)
             else:
-                workhorse_partial = partial(workhorses.dist_svd, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.dist_svd, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             ele_idx_2=ele_idx_2)
 
         elif criterion == "fim":
-            workhorse_partial = partial(workhorses.fim, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+            workhorse_partial = partial(pynibs.optimization.workhorses.fim, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
                                         e_opt=e_opt_real_in_hotspot, c=regression_cmap_normalized)
 
         elif criterion == "fim_svd":
             if metrics_weights[0] == 0:
-                workhorse_partial = partial(workhorses.svd, array=e_all_coil_pos, ele_idx_1=ele_idx_2)
+                workhorse_partial = partial(pynibs.optimization.workhorses.svd, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_2)
             elif metrics_weights[1] == 0:
-                workhorse_partial = partial(workhorses.fim, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.fim, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             e_opt=e_opt_real_in_hotspot, c=regression_cmap_normalized)
             else:
-                workhorse_partial = partial(workhorses.fim_svd, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.fim_svd, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             ele_idx_2=ele_idx_2, e_opt=e_opt_real_in_hotspot,
                                             c=regression_cmap_normalized)
 
         elif criterion == "fim_mc_rows":
             if metrics_weights[0] == 0:
-                workhorse_partial = partial(workhorses.mc, array=e_all_coil_pos, ele_idx_1=ele_idx_2, mode="rows")
+                workhorse_partial = partial(pynibs.optimization.workhorses.mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_2, mode="rows")
             elif metrics_weights[1] == 0:
-                workhorse_partial = partial(workhorses.fim, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.fim, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             e_opt=e_opt_real_in_hotspot, c=regression_cmap_normalized)
             else:
-                workhorse_partial = partial(workhorses.fim_mc, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.fim_mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             ele_idx_2=ele_idx_2, e_opt=e_opt_real_in_hotspot,
                                             c=regression_cmap_normalized,
                                             mode="rows")
 
         elif criterion == "fim_mc_cols":
             if metrics_weights[0] == 0:
-                workhorse_partial = partial(workhorses.mc, array=e_all_coil_pos, ele_idx_1=ele_idx_2, mode="cols")
+                workhorse_partial = partial(pynibs.optimization.workhorses.mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_2, mode="cols")
             elif metrics_weights[1] == 0:
-                workhorse_partial = partial(workhorses.fim, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.fim, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             e_opt=e_opt_real_in_hotspot, c=regression_cmap_normalized)
             else:
-                workhorse_partial = partial(workhorses.fim_mc, array=e_all_coil_pos, ele_idx_1=ele_idx_1,
+                workhorse_partial = partial(pynibs.optimization.workhorses.fim_mc, array=e_all_coil_pos,
+                                            ele_idx_1=ele_idx_1,
                                             ele_idx_2=ele_idx_2, e_opt=e_opt_real_in_hotspot,
                                             c=regression_cmap_normalized,
                                             mode="cols")
@@ -632,7 +652,7 @@ def get_optimal_coil_positions(
 
                 if not fim_use_gpu:
                     workhorse_partial = partial(
-                            workhorses.roi_elmt_wise_corr,
+                            pynibs.optimization.workhorses.roi_elmt_wise_corr,
                             array=e_all_coil_pos_scaled,
                             # hotspot idx must be last element of "ele_idx_1" to decorrelate
                             # only the hotspot idx with all other ROI elements
@@ -658,7 +678,7 @@ def get_optimal_coil_positions(
                     index_lists[:] = cp.asarray(idx_list[:], dtype=cp.int32)
 
                     # execute optimization
-                    res_all = workhorses.roi_elmt_wise_corr(
+                    res_all = pynibs.optimization.workhorses.roi_elmt_wise_corr(
                             idx_list=index_lists,
                             array=e,
                             ele_idx_1=subsampling_idcs,
@@ -697,7 +717,7 @@ def get_optimal_coil_positions(
             for j in range(len(idcs_to_check)):
                 idx_list.append(zap_idx_e_opt[:idx_in_result_list - 1] + [idcs_to_check[j]])
 
-            idx_list_chunks = pynibs.compute_chunks(idx_list, n_cpu)
+            idx_list_chunks = pynibs.util.utils.compute_chunks(idx_list, n_cpu)
             res = pool.map(workhorse_partial, idx_list_chunks)
 
             # extract best solution (multiple objectives)
@@ -754,7 +774,8 @@ def get_optimal_coil_positions(
                     f.create_dataset("criterion", data=crit)
 
                 try:
-                    f.create_dataset(f"zap_index_list/{idx_in_result_list}", data=zap_idx_e_opt[:idx_in_result_list])
+                    f.create_dataset(f"zap_index_list/{idx_in_result_list}",
+                                     data=zap_idx_e_opt[:idx_in_result_list])
                 except (RuntimeError, KeyError):
                     if overwrite:
                         del f[f"zap_index_list/{idx_in_result_list}"]
@@ -829,7 +850,7 @@ def get_optimal_coil_positions(
 def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn_stimsites_hdf5, e_matrix, mep,
                         mesh_idx, roi_idx, n_zaps_init=3, criterion_init="mc_rows", criterion="coverage", n_cpu=4,
                         threshold=0.8, weights=None, eps0=0.01, eps0_dist=1, exponent=5, perc=99,
-                        n_refit=0, fun=pynibs.sigmoid, verbose=True):
+                        n_refit=0, fun=None, verbose=True):
     """
     Performs virtual online optimization to determine the congruence factor. After an initial set of coil positions,
     the algorithm iteratively optimizes the next coil position based on the virtually measured MEP data.
@@ -867,7 +888,7 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
         Weights of optimization criteria in case of multiple goal functions (e.g. fim_svd). Higher weight means higher
         importance for the respective criteria. By default, both optimization criteria are weighted equally [0.5, 0.5].
     eps0 : float, default: 0.01
-        First error threshold to terminate the online optimization. The normalized root mean square deviation is
+        First error threshold to terminate the online optimization. The normalized root-mean-square deviation is
         calculated between the current and the previous solution. If the error is lower than eps0 for 3 times in a row,
         the online optimization terminates and returns the results.
     eps0_dist : float, default: 1
@@ -881,7 +902,7 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
     n_refit : int, default: 0
         Number of refit iterations. No refit is applied if ``n_refit=0``.
     fun : function object, default: pynibs.linear
-        Function to use to determine the congruence factor (e.g. pynibs.linear, pynibs.sigmoid, ...).
+        Function to use to determine the congruence factor (e.g. pynibs.linear, pynibs.expio.sigmoid, ...).
     verbose : bool, default: True
         Plot output messages.
 
@@ -889,8 +910,10 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
     -------
     <file> .hdf5 file
         Results output file containing the coil positions and the congruence factor maps for every iteration.
-
     """
+    from matplotlib import pyplot as plt
+    if fun is None:
+        fun = pynibs.expio.sigmoid
     if weights is None:
         weights = [0.5, 0.5]
     print("Starting online congruence factor optimization:")
@@ -962,32 +985,32 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
     if verbose:
         print(f"Determine optimal coil positions for initial number of {n_zaps_init} samples using {criterion_init}")
 
-    zap_idx_opt = pynibs.get_optimal_coil_positions(e_matrix=e_matrix,
-                                                    ele_idx_1=ele_idx_ss,
-                                                    ele_idx_2=None,
-                                                    criterion=criterion_init,
-                                                    n_stim=n_zaps_init,
-                                                    fn_out_hdf5=None,
-                                                    n_cpu=n_cpu,
-                                                    zap_idx_opt=None,
-                                                    metrics_weights=weights,
-                                                    overwrite=False,
-                                                    verbose=True)
+    zap_idx_opt = get_optimal_coil_positions(e_matrix=e_matrix,
+                                             ele_idx_1=ele_idx_ss,
+                                             ele_idx_2=None,
+                                             criterion=criterion_init,
+                                             n_stim=n_zaps_init,
+                                             fn_out_hdf5=None,
+                                             n_cpu=n_cpu,
+                                             zap_idx_opt=None,
+                                             metrics_weights=weights,
+                                             overwrite=False,
+                                             verbose=True)
 
     # determine initial c-factor map for all N (not existing in real life)
     if verbose:
         print(f"Determine reference c-factor map (N)")
 
-    c_ref_n = pynibs.regress_data(elm_idx_list=np.arange(n_ele),
-                                  e_matrix=e_matrix,
-                                  mep=mep,
-                                  zap_idx=None,
-                                  fun=fun,
-                                  n_refit=n_refit,
-                                  n_cpu=n_cpu,
-                                  con=con,
-                                  return_fits=False,
-                                  refit_discontinuities=True)
+    c_ref_n = pynibs.regression.regress_data(elm_idx_list=np.arange(n_ele),
+                                             e_matrix=e_matrix,
+                                             mep=mep,
+                                             zap_idx=None,
+                                             fun=fun,
+                                             n_refit=n_refit,
+                                             n_cpu=n_cpu,
+                                             con=con,
+                                             return_fits=False,
+                                             refit_discontinuities=True)
 
     ref_n = c_ref_n.flatten() ** exponent
     ref_n = ref_n / np.percentile(ref_n, perc)
@@ -1004,16 +1027,16 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
     if verbose:
         print(f"Determine initial c-factor map")
 
-    c_init, p = pynibs.regress_data(elm_idx_list=np.arange(n_ele),
-                                    e_matrix=e_matrix,
-                                    mep=mep,
-                                    zap_idx=zap_idx_opt,
-                                    fun=fun,
-                                    n_refit=n_refit,
-                                    n_cpu=n_cpu,
-                                    con=con,
-                                    return_fits=True,
-                                    refit_discontinuities=True)
+    c_init, p = pynibs.regression.regress_data(elm_idx_list=np.arange(n_ele),
+                                               e_matrix=e_matrix,
+                                               mep=mep,
+                                               zap_idx=zap_idx_opt,
+                                               fun=fun,
+                                               n_refit=n_refit,
+                                               n_cpu=n_cpu,
+                                               con=con,
+                                               return_fits=True,
+                                               refit_discontinuities=True)
     ref = c_init.flatten() ** exponent
     ref = ref / np.percentile(ref, perc)
 
@@ -1050,20 +1073,20 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
                   f"using {criterion}")
 
         n_zaps.append(n_zaps[-1] + 1)
-        zap_idx_opt = pynibs.get_optimal_coil_positions(e_matrix=e_matrix,
-                                                        ele_idx_1=ele_idx_1,
-                                                        ele_idx_2=ele_idx_2,
-                                                        criterion=criterion,
-                                                        n_stim=n_zaps[-1],
-                                                        fn_out_hdf5=None,
-                                                        n_cpu=n_cpu,
-                                                        zap_idx_opt=zap_idx_opt,
-                                                        fim_fit_fun=fun,
-                                                        regression_fit_parameters=p,
-                                                        regression_cmap=ref,
-                                                        metrics_weights=weights,
-                                                        overwrite=False,
-                                                        verbose=True)
+        zap_idx_opt = get_optimal_coil_positions(e_matrix=e_matrix,
+                                                 ele_idx_1=ele_idx_1,
+                                                 ele_idx_2=ele_idx_2,
+                                                 criterion=criterion,
+                                                 n_stim=n_zaps[-1],
+                                                 fn_out_hdf5=None,
+                                                 n_cpu=n_cpu,
+                                                 zap_idx_opt=zap_idx_opt,
+                                                 fim_fit_fun=fun,
+                                                 regression_fit_parameters=p,
+                                                 regression_cmap=ref,
+                                                 metrics_weights=weights,
+                                                 overwrite=False,
+                                                 verbose=True)
         key = str(len(zap_idx_opt) - 1)
         zap_idx[key] = zap_idx_opt
 
@@ -1077,16 +1100,16 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
         if verbose:
             print(f"Determine c-factor map for {len(zap_idx_opt)} zaps")
 
-        c[key], p = pynibs.regress_data(elm_idx_list=np.arange(n_ele),
-                                        e_matrix=e_matrix,
-                                        mep=mep,
-                                        zap_idx=zap_idx_opt,
-                                        fun=fun,
-                                        n_refit=n_refit,
-                                        n_cpu=n_cpu,
-                                        con=con,
-                                        return_fits=True,
-                                        refit_discontinuities=True)
+        c[key], p = pynibs.regression.regress_data(elm_idx_list=np.arange(n_ele),
+                                                   e_matrix=e_matrix,
+                                                   mep=mep,
+                                                   zap_idx=zap_idx_opt,
+                                                   fun=fun,
+                                                   n_refit=n_refit,
+                                                   n_cpu=n_cpu,
+                                                   con=con,
+                                                   return_fits=True,
+                                                   refit_discontinuities=True)
         arr = c[key].flatten() ** exponent
         arr = arr / np.percentile(arr, perc)
 
@@ -1097,20 +1120,20 @@ def online_optimization(fn_subject_hdf5, fn_roi_ss_indices_hdf5, fn_out_hdf5, fn
         ##########################################################################
 
         # determine NRMSD w.r.t. previous solution
-        eps.append(pynibs.nrmsd(arr, ref))
+        eps.append(pynibs.util.quality_measures.nrmsd(arr, ref))
 
         if verbose:
             print(f"NRMSD to previous solution: {eps[-1]}")
 
         # determine NRMSD w.r.t. global solution (not existing in real life)
-        eps_n.append(pynibs.nrmsd(arr, ref_n))
+        eps_n.append(pynibs.util.quality_measures.nrmsd(arr, ref_n))
 
         if verbose:
             print(f"NRMSD to global solution: {eps_n[-1]}")
 
         # determine geodesic distance w.r.t. previous solution
-        nodes_dist, tris_dist = pynibs.geodesic_dist(nodes=points, tris=con, source=np.argmax(c[key]),
-                                                     source_is_node=False)
+        nodes_dist, tris_dist = pynibs.util.quality_measures.geodesic_dist(nodes=points, tris=con, source=np.argmax(c[key]),
+                                                                           source_is_node=False)
         gdist.append(tris_dist[np.argmax(c[str(len(zap_idx_opt) - 2)])])
 
         if verbose:
@@ -1281,11 +1304,11 @@ def calc_opt_gain_map(e_matrix_ref, e_matrix_opt, points, con, fn_out=None, thre
     """
     assert e_matrix_ref.shape[1] == e_matrix_opt.shape[1], "e_matrix_ref and e_matrix_opt do not have the same number" \
                                                            "columns, i.e. elements."
-    n_ele = e_matrix_ref.shape[1]
-
-    # determine correlation matrices
-    corr_matrix_ref = np.abs(np.corrcoef(e_matrix_ref.T)) ** 2
-    corr_matrix_opt = np.abs(np.corrcoef(e_matrix_opt.T)) ** 2
+    # n_ele = e_matrix_ref.shape[1]
+    #
+    # # determine correlation matrices
+    # corr_matrix_ref = np.abs(np.corrcoef(e_matrix_ref.T)) ** 2
+    # corr_matrix_opt = np.abs(np.corrcoef(e_matrix_opt.T)) ** 2
 
     # determine element areas
     p1_tri = points[con[:, 0], :]
@@ -1360,14 +1383,12 @@ def optimal_coilplacement_region(e, fmri_stats, best_n=1, metric='dot', non_nega
 
     Notes
     -----
-    - The function normalizes the input E-field matrix and fMRI statistics for evaluation.
-    - If `res_folder` is specified, visualizations of the results are saved to the directory.
-    - The function supports saving and writing TMS navigator instrument marker files using `simnibs.localite`.
+    The function normalizes the input E-field matrix and fMRI statistics for evaluation.
+    If `res_folder` is specified, visualizations of the results are saved to the directory.
+    The function supports saving and writing TMS navigator instrument marker files using `simnibs.localite`.
     """
     # Import localite utility to write TMS navigator instrument marker files
-    from simnibs.utils.nnav import localite
-    loc = localite()
-    write_tms_navigator_im = loc.write
+    from matplotlib import pyplot as plt
 
     # Normalize fMRI statistics
     fmri_stats /= fmri_stats.max()
@@ -1427,6 +1448,9 @@ def optimal_coilplacement_region(e, fmri_stats, best_n=1, metric='dot', non_nega
 
     # If position matrices are provided, identify the best and N best positions
     if pos_matrices is not None:
+        from simnibs.utils.nnav import localite
+        loc = localite()
+        write_tms_navigator_im = loc.write
         nth_opt_matsim = pos_matrices[:, :, nth_best_coil_pos]
 
         # Transpose the matrices for proper alignment
@@ -1439,7 +1463,7 @@ def optimal_coilplacement_region(e, fmri_stats, best_n=1, metric='dot', non_nega
         # Write the instrument marker file for the top N positions
         write_tms_navigator_im(nth_opt_matsim, os.path.join(res_folder, f'opt_coil_pos_nth_{metric}.xml'),
                                names=[f'opt_{i:0>2}' for i in range(best_n)], overwrite=True)
-        pynibs.create_stimsite_from_matsimnibs(os.path.join(res_folder, f'opt_coil_pos_nth_{metric}.hdf5'),
-                                               nth_opt_matsim, overwrite=True, data=np.array(range(1, best_n + 1)),
-                                               datanames='Best coil id')
+        pynibs.coil.create_stimsite_from_matsimnibs(os.path.join(res_folder, f'opt_coil_pos_nth_{metric}.hdf5'),
+                                                    nth_opt_matsim, overwrite=True, data=np.array(range(1, best_n + 1)),
+                                                    datanames='Best coil id')
     return nth_best_coil_pos