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

pynibs/roi/{roi.py → roi_utils.py}

@@ -1,13 +1,8 @@
-"""
-Functions that operate on region of interest (ROI) data.
-"""
 import os
 import h5py
-import math
 import tqdm
 import time
 import scipy
-import trimesh
 import nibabel
 import warnings
 import platform
@@ -135,6 +130,33 @@ def load_roi_surface_obj_from_hdf5(fname):
     return read_roi_from_mesh_hdf5(fname)
 
 
+def read_roi_from_geo_fn(geo_fn):
+    """
+    Creates pynibs.RegionOfInterest from geo.hdf5
+
+    Parameters
+    ----------
+    geo_fn : str
+
+    Returns
+    -------
+    roi : pynibs.RegionOfInterest
+    """
+    roi = pynibs.RegionOfInterestSurface()
+    with h5py.File(geo_fn, 'r') as f:
+        roi.n_tris = f['mesh/elm/triangle_number_list'][:].shape[0]
+        roi.n_nodes = f['mesh/nodes/node_coord'][:].shape[0]
+        roi.n_tets = -1
+        roi.node_coord_mid = f['mesh/nodes/node_coord'][:]
+        roi.node_number_list = f['mesh/elm/triangle_number_list'][:]
+        if roi.node_number_list.min() == 1:
+            roi.node_number_list = - 1
+        tri_coords = roi.node_coord_mid[roi.node_number_list]
+        roi.tri_center_coord_mid = np.mean(tri_coords, axis=1)
+
+        return roi
+
+
 def read_roi_from_mesh_hdf5(fname, roi_id=None):
     """
     Loading and initializing RegionOfInterestSurface object/s from .hdf5 mesh file.
@@ -387,6 +409,7 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
 
         * 0 -> WM surface
         * 1 -> GM surface
+
     x_roi : list of float or None
         Region of interest [Xmin, Xmax], whole X range if empty [0,0] or None
         (left - right)
@@ -401,8 +424,9 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
 
         * 1: one layer
         * 3: additionally upper and lower layers are generated around the central midlayer
+
     fn_mask: string or None
-        Filename for freesurfer mask. If given, this is used instead of *_ROIs
+        Filename for freesurfer mask. If given, this is used instead of \\*_ROIs
     refine : bool, optional, default: False
         Refine ROI by splitting elements
 
@@ -424,15 +448,14 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
     connectivity : np.ndarray of int
          (N_tri x 3) Connectivity of triangles (indexation starts at 0!)
 
-    Example
-    -------
-
+    Examples
+    --------
     .. code-block:: python
 
         make_GM_WM_surface(self, gm_surf_fname, wm_surf_fname, delta, X_ROI, Y_ROI, Z_ROI)
         make_GM_WM_surface(self, gm_surf_fname, wm_surf_fname, delta, mask_fn, layer=3)
     """
-
+    import trimesh
     if type(gm_surf_fname) is not list:
         gm_surf_fname = [gm_surf_fname]
 
@@ -460,7 +483,7 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
     for i in range(len(gm_surf_fname)):
         if gm_surf_fname[i] is not None:
             if gm_surf_fname[i].endswith('.gii'):
-                img = nibabel.gifti.giftiio.read(os.path.join(mesh_folder, gm_surf_fname[i]))
+                img = nibabel.load(os.path.join(mesh_folder, gm_surf_fname[i]))
                 points_gm[i] = img.agg_data('pointset')
                 con_gm[i] = img.agg_data('triangle')
             else:
@@ -470,7 +493,7 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
 
         if wm_surf_fname[i] is not None:
             if wm_surf_fname[i].endswith('.gii'):
-                img = nibabel.gifti.giftiio.read(os.path.join(mesh_folder, wm_surf_fname[i]))
+                img = nibabel.load(os.path.join(mesh_folder, wm_surf_fname[i]))
                 points_wm[i] = img.agg_data('pointset')
                 con_wm[i] = img.agg_data('triangle')
             else:
@@ -480,12 +503,12 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
 
         if midlayer_surf_fname[i] is not None:
             if midlayer_surf_fname[i].endswith('.gii'):
-                img = nibabel.gifti.giftiio.read(os.path.join(mesh_folder, midlayer_surf_fname[i]))
+                img = nibabel.load(os.path.join(mesh_folder, midlayer_surf_fname[i]))
                 points_mid[i] = img.agg_data('pointset')
                 con_mid[i] = img.agg_data('triangle')
             else:
                 points_mid[i], con_mid[i] = nib.freesurfer.read_geometry(
-                        os.path.join(mesh_folder, midlayer_surf_fname[i]))
+                    os.path.join(mesh_folder, midlayer_surf_fname[i]))
             con_mid[i] = con_mid[i] + max_idx_mid
             max_idx_mid = max_idx_mid + points_mid[i].shape[0]  # np.max(con_wm[i]) + 2
 
@@ -588,13 +611,13 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
         mesh.export(roi_fn)
 
         roi_refined_fn = os.path.join(mesh_folder, "", "tmp", "roi_refined.stl")
-        pynibs.refine_surface(fn_surf=roi_fn,
-                              fn_surf_refined=roi_refined_fn,
-                              center=[0, 0, 0],
-                              radius=np.inf,
-                              verbose=True,
-                              repair=False,
-                              remesh=False)
+        pynibs.mesh.refine_surface(fn_surf=roi_fn,
+                                   fn_surf_refined=roi_refined_fn,
+                                   center=[0, 0, 0],
+                                   radius=np.inf,
+                                   verbose=True,
+                                   repair=False,
+                                   remesh=False)
 
         roi = trimesh.load(roi_refined_fn)
         con_cropped_reform = roi.faces
@@ -608,12 +631,12 @@ def make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_
                                        faces=con_cropped_reform)
                 mesh.export(roi_fn)
 
-                pynibs.refine_surface(fn_surf=roi_fn,
-                                      fn_surf_refined=roi_refined_fn,
-                                      center=[0, 0, 0],
-                                      radius=np.inf,
-                                      verbose=True,
-                                      repair=False)
+                pynibs.mesh.refine_surface(fn_surf=roi_fn,
+                                           fn_surf_refined=roi_refined_fn,
+                                           center=[0, 0, 0],
+                                           radius=np.inf,
+                                           verbose=True,
+                                           repair=False)
 
                 roi.append(trimesh.load(roi_refined_fn))
 
@@ -776,12 +799,12 @@ def create_refine_spherical_roi(center, radius, final_tissues_nii, out_fn, targe
     """
     # get spherical ROI, masked to all tissues
     roi_img = get_sphere_in_nii(
-            center=center,
-            radius=radius,
-            nii=final_tissues_nii,
-            val_in=target_size,
-            out_fn=out_spher_fn,
-            outside_val=outside_size, outside_radius=radius * outside_factor)
+        center=center,
+        radius=radius,
+        nii=final_tissues_nii,
+        val_in=target_size,
+        out_fn=out_spher_fn,
+        outside_val=outside_size, outside_radius=radius * outside_factor)
 
     # get tissue_types data
     if isinstance(final_tissues_nii, str):

pynibs/subject.py

@@ -28,7 +28,7 @@ class Subject:
     id : str
         Subject id.
     fn_mesh : str
-         .msh or .hdf5 file containing the mesh information.
+        .msh or .hdf5 file containing the mesh information.
 
     **Subject.seg, segmentation information dictionary**
 
@@ -90,7 +90,7 @@ class Subject:
     **Subject.mesh, mesh dictionary**
 
     info : str
-        Information about the mesh (e.g. dicretization, etc.).
+        Information about the mesh (e.g. discretization, etc.).
     fn_mesh_msh : str
         Filename of the .msh file containing the FEM mesh.
     fn_mesh_hdf5 : str
@@ -522,7 +522,7 @@ def save_subject_hdf5(subject_id, subject_folder, fname, mri_dict=None, mesh_dic
             mesh_dict = {i: mesh_dict[i] for i in range(len(mesh_dict))}
 
         for mesh_name, mesh_dict in mesh_dict.items():
-            mesh = pynibs.Mesh(mesh_name=mesh_name, subject_id=subject_id, subject_folder=subject_folder)
+            mesh = pynibs.mesh.Mesh(mesh_name=mesh_name, subject_id=subject_id, subject_folder=subject_folder)
             mesh.fill_defaults(mesh_dict['approach'])
             mesh = fill_from_dict(mesh, mesh_dict)
             mesh.write_to_hdf5(fn_hdf5=fname, check_file_exist=check_file_exist, verbose=verbose)
@@ -530,7 +530,7 @@ def save_subject_hdf5(subject_id, subject_folder, fname, mri_dict=None, mesh_dic
     if roi_dict is not None:
         for mesh_name in roi_dict.keys():
             for roi_name, roi_dict_i in roi_dict[mesh_name].items():
-                roi = pynibs.ROI(subject_id=subject_id, roi_name=roi_name, mesh_name=mesh_name)
+                roi = pynibs.mesh.ROI(subject_id=subject_id, roi_name=roi_name, mesh_name=mesh_name)
                 roi = fill_from_dict(roi, roi_dict_i)
                 roi.write_to_hdf5(fn_hdf5=fname, check_file_exist=check_file_exist, verbose=verbose)
 
@@ -717,7 +717,7 @@ def load_subject_pkl(fname):
         fn_scipt = os.path.join(os.path.split(fname)[0],
                                 "create_subject_" +
                                 os.path.splitext(os.path.split(fname)[1])[0] + ".py")
-        pynibs.bash_call("python {}".format(fn_scipt))
+        pynibs.util.utils.bash_call("python {}".format(fn_scipt))
 
         with open(fname, 'rb') as f:
             return pickle.load(f)
@@ -761,20 +761,21 @@ def create_plot_settings_dict(plotfunction_type):
         * 'volume_plot'
         * 'volume_plot_vtu'
 
+
     Returns
     -------
     ps : dict
         Dictionary containing the plotsettings.
     axes : bool
         Show orientation axes.
-    background_color : nparray
+    background_color : np.ndarray
          (1m 3) Set background color of exported image RGB (0...1).
     calculator : str
         Format string with placeholder of the calculator expression the quantity to plot is modified with,
         e.g.: "{}^5".
-    clip_coords : nparray of float
+    clip_coords : np.ndarray of float
         (N_clips, 3) Coordinates of clip surface origins (x,y,z).
-    clip_normals : nparray of float
+    clip_normals : np.ndarray of float
         (N_clips, 3) Surface normals of clip surfaces pointing in the direction where the volume is kept for
         clip_type = ['clip' ...] (x,y,z).
     clip_type : list of str
@@ -782,16 +783,18 @@ def create_plot_settings_dict(plotfunction_type):
 
         * 'clip':  cut geometry but keep volume behind
         * 'slice': cut geometry and keep only the slice
+
     coil_dipole_scaling : list [1 x 2]
         Specify the scaling type of the dipoles (2 entries):
         ``coil_dipole_scaling[0]``:
 
         * 'uniform': uniform scaling, i.e. all dipoles have the same size
-        + 'scaled': size scaled according to dipole magnitude
+        * 'scaled': size scaled according to dipole magnitude
 
         ``coil_dipole_scaling[1]``:
 
         * scalar scale parameter of dipole size
+
     coil_dipole_color : str or list
         Color of the dipoles; either str to specify colormap (e.g. 'jet') or list of RGB values [1 x 3] (0...1).
     coil_axes : bool, default: True
@@ -814,8 +817,8 @@ def create_plot_settings_dict(plotfunction_type):
         maximum number of colorbar labels.
     colorbar_labelcolor : list of float
         (1, 3) Color of colorbar labels in RGB (0...1).
-    colormap : str or nparray
-        If nparray [1 x 4*N]: custom colormap providing data and corresponding RGB values
+    colormap : str or np.ndarray
+        If np.ndarray [1 x 4*N]: custom colormap providing data and corresponding RGB values
 
         .. math::
             \\begin{bmatrix}
@@ -839,9 +842,10 @@ def create_plot_settings_dict(plotfunction_type):
         * 'Viridis (matplotlib)',
         * 'gray_Matlab',
         * 'Spectral_lowBlue',
-        + 'BuRd'
+        * 'BuRd'
         * 'Rainbow Blended White'
         * 'b2rcw'
+
     colormap_categories : bool
         Use categorized (discrete) colormap.
     datarange : list
@@ -857,6 +861,7 @@ def create_plot_settings_dict(plotfunction_type):
         * 3 -> cerebrospinal fluid (CSF)
         * 4 -> skull
         * 5 -> skin
+
     domain_label : str
         Label of the dataset which contains the domain IDs (default: 'tissue_type').
     edges : BOOL
@@ -868,6 +873,7 @@ def create_plot_settings_dict(plotfunction_type):
         * .hdf5-file(s): filename(s) of .hdf5 file(s) containing the data and the geometry. The data can be provided
           in the first hdf5 file and the geometry can be provided in the second file. However, both can be also
           provided in a single hdf5 file.
+
     fname_png : str
         Name of output .png file (incl. path).
     fname_vtu_volume : str
@@ -893,6 +899,7 @@ def create_plot_settings_dict(plotfunction_type):
             ...      & ...   & ... & ...\\\\
             data_{N} & opac_N & 0.5 & 0  \\\\
            \\end{bmatrix}
+
     plot_function : str
         Function the plot is generated with:
 
@@ -900,6 +907,7 @@ def create_plot_settings_dict(plotfunction_type):
         - 'surface_vector_plot_vtu'
         - 'volume_plot'
         - 'volume_plot_vtu'
+
     png_resolution : float
         Resolution parameter of output image (1...5).
     quantity : str
@@ -924,10 +932,11 @@ def create_plot_settings_dict(plotfunction_type):
         - 'All Points' (not set)
         - 'Every Nth Point' (every Nth vector is shown in the grid)
         - 'Uniform Spatial Distribution' (not set)
+
     view : list
         Camera position and angle in 3D space:
         ``[[3 x CameraPosition], [3 x CameraFocalPoint], [3 x CameraViewUp], 1 x CameraParallelScale]``.
-    viewsize : nparray [1 x 2]
+    viewsize : np.ndarray [1 x 2]
         Set size of exported image in pixel [width x height] will be extra scaled by parameter png_resolution.
     vlabels : list of str
         Labels of vector datasets to plot (other present datasets are ignored).
@@ -937,7 +946,8 @@ def create_plot_settings_dict(plotfunction_type):
         List containing the type of vector scaling:
 
         - 'off': all vectors are normalized
-        - 'vector': vectors are scaled according to their magnitudeeee
+        - 'vector': vectors are scaled according to their magnitudes
+
     """
     if plotfunction_type not in ['surface_vector_plot', 'surface_vector_plot_vtu', 'volume_plot', 'volume_plot_vtu']:
         raise Exception('plotfunction_type not set correctly, specify either [\'surface_vector_plot\', \

pynibs/util/__init__.py

@@ -1,4 +1,20 @@
-from .util import *
-from .quality_measures import *
-from .rotations import *
-from .simnibs import *
+import importlib
+
+
+_lazy_modules = [
+    "simnibs_io",
+    "utils",
+    "quality_measures",
+    "rotations"
+]
+
+
+def __getattr__(name):
+    """
+    Lazy-load selected submodules when accessed as attributes of pynibs.util.
+    """
+    if name in _lazy_modules:
+        mod = importlib.import_module(f".{name}", __name__)
+        globals()[name] = mod  # cache for future accesses
+        return mod
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pynibs/util/dosing.py

@@ -1,5 +1,5 @@
 """
-Functions used in our perspective on e-field based TMS dosing[1]_
+Functions used in our perspective on e-field based TMS dosing [1]_
 
 References
 ----------
@@ -46,7 +46,6 @@ def get_intensity_e(e1, e2, target1, target2, radius1, radius2, headmesh,
     rmt_e_corr : float
         Adjusted stimulation intensity for target2.
     """
-
     with h5py.File(headmesh, 'r') as f:
         tris = f[f'/roi_surface/{roi}/tri_center_coord_mid'][:]
 
@@ -111,14 +110,14 @@ def get_intensity_e_old(mesh1, mesh2, target1, target2, radius1, radius2, rmt=1,
         if os.path.splitext(mesh1)[1] == ".msh":
             mesh1 = read_msh(mesh1)
         elif os.path.splitext(mesh1)[1] == ".hdf5":
-            mesh1 = pynibs.load_mesh_hdf5(mesh1)
+            mesh1 = pynibs.hdf5_io.load_mesh_hdf5(mesh1)
 
     # load mesh2 (target) if filename is provided
     if isinstance(mesh2, str):
         if os.path.splitext(mesh2)[1] == ".msh":
             mesh2 = read_msh(mesh2)
         elif os.path.splitext(mesh2)[1] == ".hdf5":
-            mesh2 = pynibs.load_mesh_hdf5(mesh2)
+            mesh2 = pynibs.hdf5_io.load_mesh_hdf5(mesh2)
 
     # load electric fields in midlayer and average electric field around sphere in targets
     e_avg_target = []
@@ -196,7 +195,7 @@ def get_intensity_stokes(mesh, target1, target2, spat_grad=3, rmt=0, scalp_tag=1
         if os.path.splitext(mesh)[1] == ".msh":
             mesh = read_msh(mesh)
         elif os.path.splitext(mesh)[1] == ".hdf5":
-            mesh = pynibs.load_mesh_hdf5(mesh)
+            mesh = pynibs.hdf5_io.load_mesh_hdf5(mesh)
 
     t1_proj = project_on_scalp(target1, mesh, scalp_tag=scalp_tag)
     t2_proj = project_on_scalp(target2, mesh, scalp_tag=scalp_tag)

pynibs/util/quality_measures.py

@@ -1,8 +1,14 @@
-import numpy as np
+"""
+Functions used in our publication on TMS quality metrics [1]_
+
+References
+----------
+.. [1] Numssen, O., Martin, S., Williams, K., Hartwigsen, G., & Knösche, T. (2024). Quantification of subject motion
+   during TMS via pulsewise coil displacement. Brain Stimulation.
+   DOI: 10.1016/j.brain.2024.07.003 #
+"""
 import gdist
-from matplotlib import pyplot as plt
-from scipy.spatial.transform import Rotation as rot
-
+import numpy as np
 import pynibs
 
 
@@ -11,8 +17,8 @@ def geodesic_dist(nodes, tris, source, source_is_node=True):
     Returns geodesic distance in mm from all nodes to source node (or triangle).
     This is just a wrapper for the gdist package.
 
-    Example
-    -------
+    Examples
+    --------
 
     .. code-block:: python
 
@@ -73,11 +79,11 @@ def geodesic_dist(nodes, tris, source, source_is_node=True):
 
 def euclidean_dist(nodes, tris, source, source_is_node=True):
     """
-    Returns euclidean distance of all nodes to source node (triangle).
+    Returns Euclidean distance of all nodes to source node (triangle).
     This is just a wrapper for the gdist package.
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         with h5py.File(fn,'r') as f:
@@ -146,7 +152,6 @@ def nrmsd(array, array_ref, error_norm="relative", x_axis=False):
     normalized_rms : np.ndarray of float
         ([array.shape[1]]) Normalized root-mean-square deviation between the columns of array and array_ref.
     """
-
     n_points = array.shape[0]
 
     if x_axis:
@@ -209,8 +214,6 @@ def nrmse(array, array_ref, x_axis=False):
     array_ref : np.ndarray
         reference data [ (x_ref), y0_ref, y1_ref, y2_ref ... ].
         if array_ref is 1D, all sizes have to match.
-    error_norm : str, optional, default="relative"
-        Decide if error is determined "relative" or "absolute".
     x_axis : bool, default: False
         If True, the first column of array and array_ref is interpreted as the x-axis, where the data points are
         evaluated. If False, the data points are assumed to be at the same location.
@@ -220,9 +223,6 @@ def nrmse(array, array_ref, x_axis=False):
     nrmse: np.ndarray of float
         ([array.shape[1]]) Normalized root-mean-square deviation between the columns of array and array_ref.
     """
-
-    n_points = array.shape[0]
-
     if x_axis:
         # handle different array lengths
         if len(array_ref.shape) == 1:
@@ -253,9 +253,7 @@ def nrmse(array, array_ref, x_axis=False):
         data = array
 
     # determine normalized rms deviation and return
-    nrmse = np.linalg.norm(data - data_ref, axis=0) / np.linalg.norm(data_ref, axis=0)
-
-    return nrmse
+    return np.linalg.norm(data - data_ref, axis=0) / np.linalg.norm(data_ref, axis=0)
 
 
 def c_map_comparison(c1, c2, t1, t2, nodes, tris):
@@ -305,11 +303,12 @@ def calc_tms_motion_params(coil_positions, reference=None):
     Motion is computed w.r.t. the first ('absolute') and to the previous ('relative') stimulation.
 
     Position shifts are quantified with respect to the subject/nifti-specific RAS coordinate system.
-    Rorational changes are quantified with respect to the coil axes as follows:
+    Rtrational changes are quantified with respect to the coil axes as follows:
+
+    * pitch: rotation around left/right axis of coil
+    * roll: rotation around coil handle axis
+    * yaw: rotation around axis from center of coil towards head
 
-        * pitch: rotation around left/right axis of coil
-        * roll: rotation around coil handle axis
-        * yaw: rotation around axis from center of coil towards head
     Motion parameters for first coil position are set to 0.
 
     Parameters
@@ -330,6 +329,7 @@ def calc_tms_motion_params(coil_positions, reference=None):
     euler_rots_rel : np.ndarray
         (3, n_pulses) Relative rotation angles in euler angles (alpha, beta, gamma).
     """
+    from scipy.spatial.transform import Rotation as rot
     np.set_printoptions(suppress=True)
     if reference is None:
         i_ref = 0
@@ -346,8 +346,8 @@ def calc_tms_motion_params(coil_positions, reference=None):
         reference_rot = reference[0:3, 0:3]
 
         # compute first rotation towards reference
-        rotmat_abs = pynibs.bases2rotmat(reference_rot, coil_positions[0:3, 0:3, 0])
-        if np.isnan(rotmat_abs).any():
+        rotmat_abs = pynibs.util.rotations.bases2rotmat(reference_rot, coil_positions[0:3, 0:3, 0])
+        if np.isnan(rotmat_abs).any() or (coil_positions[0:3, 0:3, 0]**2).sum() == 3:
             euler_rots_abs = [[np.nan, np.nan, np.nan]]
         else:
             euler_rots_abs = [rot.from_matrix(rotmat_abs).as_euler('xyz', degrees=True).tolist()]
@@ -363,15 +363,15 @@ def calc_tms_motion_params(coil_positions, reference=None):
     n_coilpos = coil_positions.shape[2]
     euler_rots_rel = [[0, 0, 0]]
     for i in range(0, n_coilpos - 1):
-        rotmat_abs = pynibs.bases2rotmat(reference_rot, coil_positions[0:3, 0:3, i + 1])
-        if np.isnan(rotmat_abs).any():
+        rotmat_abs = pynibs.util.rotations.bases2rotmat(reference_rot, coil_positions[0:3, 0:3, i + 1])
+        if np.isnan(rotmat_abs).any() or (coil_positions[0:3, 0:3, i + 1]**2).sum() == 3:
             euler_abs = [np.nan, np.nan, np.nan]
         else:
             euler_abs = rot.from_matrix(rotmat_abs).as_euler('xyz', degrees=True).tolist()
         euler_rots_abs.append(euler_abs)
 
-        rotmat_rel = pynibs.bases2rotmat(coil_positions[0:3, 0:3, i], coil_positions[0:3, 0:3, i + 1])
-        if np.isnan(rotmat_rel).any():
+        rotmat_rel = pynibs.util.rotations.bases2rotmat(coil_positions[0:3, 0:3, i], coil_positions[0:3, 0:3, i + 1])
+        if np.isnan(rotmat_rel).any() or (coil_positions[0:3, 0:3, i + 1]**2).sum() == 3:
             euler_rel = [np.nan, np.nan, np.nan]
         else:
             euler_rel = rot.from_matrix(rotmat_rel).as_euler('xyz', degrees=True).tolist()
@@ -410,6 +410,7 @@ def plot_tms_motion_parameter(pos_diff, euler_rots, pcd=None, fname=None):
     axes : matplotlib.pyplot.axes
         Figure axes.
     """
+    from matplotlib import pyplot as plt
     if pcd is not None:
         n_plot_rows = 3
     else:
@@ -480,11 +481,10 @@ def compute_pcd(delta_pos, delta_rot, skin_cortex_distance=20):
 
     The coil rotations (in euler angles) are transformed into a positional change projected on the cortex based on
     ``skin_cortex_distance`` as a proxy for the (local) change of the stimulation.
-    ``delta_pos`` and ``delta_rot`` are expected to quantify motion w.r.t. the target coil position/roation, for example
-    the absolute deltas to the first stimulation.
+    ``delta_pos`` and ``delta_rot`` are expected to quantify motion w.r.t. the target coil position/rotation,
+    for example the absolute deltas to the first stimulation.
 
     Axes definitions
-    ----------------
     ``delta_pos`` and ``delta_rot`` are supposed to follow this axes definition (SimNIBS):
 
     - delta_pos
@@ -501,21 +501,21 @@ def compute_pcd(delta_pos, delta_rot, skin_cortex_distance=20):
        :alt: Coil axes definition, following SimNIBS conventions.
 
 
-    Example
-    -------
+    Examples
+    --------
     .. code-block:: python
 
         # get TriggerMarkers from a Localite session
         mats = pynibs.read_triggermarker_localite(tm_fn)[0]
 
         # calculate absolute and relative coil displacements
-        delta_pos_abs, delta_rot_abs, delta_pos_rel, delta_rot_rel = pynibs.calc_tms_motion_params(mats)
+        delta_pos_abs, delta_rot_abs, delta_pos_rel, delta_rot_rel = pynibs.util.quality_measures.calc_tms_motion_params(mats)
 
         # compute PCD
-        pcd, delta_pos, delta_rot = pynibs.compute_pcd(delta_pos_abs, delta_rot_abs)
+        pcd, delta_pos, delta_rot = pynibs.util.quality_measures.compute_pcd(delta_pos_abs, delta_rot_abs)
 
         # plot movement
-        axes = pynibs.plot_tms_motion_parameter(pos_diff_rel, euler_rots_rel, pcd)
+        axes = pynibs.util.quality_measures.plot_tms_motion_parameter(delta_pos_rel, delta_rot_rel, pcd)
         matplotlib.pyplot.show()
 
     Parameters
@@ -536,6 +536,7 @@ def compute_pcd(delta_pos, delta_rot, skin_cortex_distance=20):
     delta_rot : np.ndarray
         (n_pulses, ) sum(abs(delta_rot projected by skin_cortex_distance)) per pulse.
     """
+    from scipy.spatial.transform import Rotation as rot
     # delta_pos_summed = np.sum(np.abs(delta_pos[:2, :]), axis=0)
     delta_pos_summed = np.sqrt(np.sum(delta_pos[: 2, :] ** 2, axis=0))
     delta_pos_summed = np.squeeze(delta_pos_summed + delta_pos[2, :] ** 2 * np.sign(delta_pos[2, :]))
@@ -551,12 +552,12 @@ def compute_pcd(delta_pos, delta_rot, skin_cortex_distance=20):
         # rots[2] = 0
         r = rot.from_rotvec(rots, degrees=True)
         ray_dir = r.apply([0, 0, 1])
-        intersec = pynibs.intersection_vec_plan(ray_dir, ray_origin, plane_n, plane_p, eps=1e-6)
+        intersec = pynibs.util.utils.intersection_vec_plan(ray_dir, ray_origin, plane_n, plane_p, eps=1e-6)
 
         # compute distance from new intersection with [0, 0, scd]
         delta_rot_a.append(np.linalg.norm(plane_p - intersec))
 
     # ray shift based on orientation doesn't include any rotations around z axis.
-    z_rotation_deltas = np.abs((skin_cortex_distance) * np.sin(np.deg2rad(delta_rot[2, :])))
+    z_rotation_deltas = np.abs(skin_cortex_distance * np.sin(np.deg2rad(delta_rot[2, :])))
     delta_rot = np.array(delta_rot_a) + z_rotation_deltas
     return delta_pos_summed + delta_rot, delta_pos_summed, delta_rot