pynibs package¶
Subpackages¶
Submodules¶
pynibs.coil module¶
pynibs.freesurfer module¶
pynibs.hdf5_io module¶
- pynibs.hdf5_io.create_fibre_geo_hdf5(fn_fibres_hdf5, overwrite=True)¶
Reformats geometrical fibre data and adds a /plot subfolder containing geometrical fibre data including connectivity
- pynibs.hdf5_io.create_fibre_xdmf(fn_fibre_geo_hdf5, fn_fibre_data_hdf5=None, overwrite=True, fibre_points_path='fibre_points', fibre_con_path='fibre_con', fibre_data_path='')¶
Creates .xdmf file to plot fibres in Paraview
- Parameters
fn_fibre_geo_hdf5 (str) – Path to fibre_geo.hdf5 file containing the geometry (in /plot subfolder created with create_fibre_geo_hdf5())
fn_fibre_data_hdf5 (str (optional) default: None) – Path to fibre_data.hdf5 file containing the data to plot (in parent folder)
fibre_points_path (str (optional) default: fibre_points) – Path to fibre point array in .hdf5 file
fibre_con_path (str (optional) default: fibre_con) – Path to fibre connectivity array in .hdf5 file
fibre_data_path (str (optional) default: "") – Path to parent data folder in data.hdf5 file (Default: no parent folder)
- Returns
<File>
- Return type
.xdmf file for Paraview
- pynibs.hdf5_io.create_position_path_xdmf(sorted_fn, coil_pos_fn, output_xdmf, stim_intens=None, coil_sorted='/0/0/coil_seq')¶
Creates one .xdmf file that allows paraview plottings of coil position paths.
- Parameters
sorted_fn (str) – .hdf5 filename with position indices, values, intensities from pynibs.sort_opt_coil_positions()
coil_pos_fn (str) – .hdf5 filename with original set of coil positions. Indices from sorted_fn are mapped to this. Either ‘/matsimnibs’ or ‘m1’ and ‘m2’ datasets.
output_xdmf (str) –
stim_intens (int, optional) – Intensities are multiplied by this factor
- Returns
output_xdmf
- Return type
<file>
- Other Parameters
coil_sorted (str) – Path to coil positions in sorted_fn
- pynibs.hdf5_io.data_superimpose(fn_in_hdf5_data, fn_in_geo_hdf5, fn_out_hdf5_data, data_hdf5_path='/data/tris/', data_substitute=- 1, normalize=False)¶
Overlaying data stored in .hdf5 files except in regions where data_substitute is found. These points are omitted in the analysis and will be replaced by data_substitute instead.
- Parameters
fn_in_hdf5_data (list of str) – Filenames of .hdf5 data files with common geometry (e.g. generated by pynibs.data_sub2avg(…))
fn_in_geo_hdf5 (str) – Geometry .hdf5 file, which corresponds to the .hdf5 data files
fn_out_hdf5_data (str) – Filename of .hdf5 data output file containing the superimposed data
data_hdf5_path (str) – Path in .hdf5 data file where data is stored (e.g. ‘/data/tris/’)
data_substitute (float or NaN) – Data substitute with this number for all points in the inflated brain, which do not belong to the given data set (Default: -1)
normalize (boolean or str) – Decide if individual datasets are normalized w.r.t. their maximum values before they are superimposed (Default: False) - ‘global’: global normalization w.r.t. maximum value over all datasets and subjects - ‘dataset’: dataset wise normalization w.r.t. maximum of each dataset individually (over subjects) - ‘subject’: subject wise normalization (over datasets)
- Returns
<File> – Overlayed data
- Return type
.hdf5 file
- pynibs.hdf5_io.hdf_2_ascii(hdf5_fn)¶
Prints out structure of given .hdf5 file.
- Parameters
hdf5_fn (str) – Filename of .hdf5 file.
- Returns
h5 – Structure of .hdf5 file
- Return type
items
- pynibs.hdf5_io.load_mesh_hdf5(fname)¶
Loading mesh from .hdf5 file and setting up TetrahedraLinear class.
- Parameters
fname (str) – Name of .hdf5 file (incl. path)
- Returns
obj – Instance of TetrahedraLinear class
- Return type
pyfempp.TetrahedraLinear
Example
hdf5 file format and contained groups. The content of .hdf5 files can be shown using the tool HDFView (https://support.hdfgroup.org/products/java/hdfview/)
mesh I---/elm I I--/elm_number [1,2,3,...,N_ele] Running index over all elements starting at 1, triangles and tetrahedra I I--/elm_type [2,2,2,...,4,4] Element type: 2 triangles, 4 tetrahedra I I--/node_number_list [1,5,6,0;... ;1,4,8,9] Connectivity of triangles [X, X, X, 0] and tetrahedra [X, X, X, X] I I--/tag1 [1001,1001, ..., 4,4,4] Surface (100X) and domain (X) indices with 1000 offset for surfaces I I--/tag2 [ 1, 1, ..., 4,4,4] Surface (X) and domain (X) indices w/o offset I I---/nodes I I--/node_coord [1.254, 1.762, 1.875;...] Node coordinates in (mm) I I--/node_number [1,2,3,...,N_nodes] Running index over all points starting at 1 I I--/units ["mm"] .value is unit of geometry I I---/fields I I--/E/value [E_x_1, E_y_1, E_z_1;...] Electric field in all elms, triangles and tetrahedra I I--/J/value [J_x_1, J_y_1, J_z_1;...] Current density in all elms, triangles and tetrahedra I I--/normE/value [normE_1,..., normE_N_ele] Magnitude of electric field in all elements, triangles and tetrahedra I I--/normJ/value [normJ_1,..., normJ_N_ele] Magnitude of current density in all elements, triangles and tetrahedra /data I---/potential [phi_1, ..., phi_N_nodes] Scalar electric potential in nodes (size N_nodes) I---/dAdt [A_x_1, A_y_1, A_z_1,...] Magnetic vector potential (size 3xN_nodes)
- pynibs.hdf5_io.load_mesh_msh(fname)¶
Loading mesh from .msh file and return object instance of TetrahedraLinear class.
- Parameters
fname (str) – Name of .msh file (incl. path)
- Returns
obj
- Return type
pyfempp.TetrahedraLinear
- pynibs.hdf5_io.msh2hdf5(fn_msh=None, skip_roi=False, include_data=False, approach='mri2mesh', subject=None, mesh_idx=None)¶
Transforms mesh from .msh to .hdf5 format. Mesh is read from subject object or from fn_msh.
- Parameters
fn_msh (str, optional, default: None) – Filename of .msh file
skip_roi (bool, optional, default: False) – Skip generating ROI in .hdf5
include_data (bool, optional, default: False) – Also convert data in .msh file to .hdf5 file
subject (Subject object, optional, default: None) – Subject object
mesh_idx (int or list of int, optional, default: None) – Mesh index, the conversion from .msh to .hdf5 is conducted for
parameters (Depreciated) –
---------------------- –
approach (str) – Approach the headmodel was created with (“mri2mesh” or “headreco”)
- Returns
<File> – .hdf5 file with mesh information
- Return type
.hdf5 file
- pynibs.hdf5_io.print_attrs(name, obj)¶
Helper function for hdf_2_ascii. To be called from h5py.Group.visititems()
- pynibs.hdf5_io.read_arr_from_hdf5(fn_hdf5, folder)¶
Read array and transform to list: strings saved as np.bytes_ to str and ‘None’ to None
- fn_hdf5: str
Filename of .hdf5 file
- folder: str
Folder inside .hdf5 file to read
- Returns
l – List containing data from .hdf5 file
- Return type
- pynibs.hdf5_io.read_data_hdf5(fname)¶
Reads phi and dA/dt data from .hdf5 file (phi and dAdt are given in the nodes!).
- Parameters
fname (str) – Filename of .hdf5 data file
- Returns
phi (nparray of float [N_nodes]) – Electric potential in the nodes of the mesh
da_dt (nparray of float [N_nodesx3]) – Magnetic vector potential in the nodes of the mesh
- pynibs.hdf5_io.read_dict_from_hdf5(fn_hdf5, folder)¶
Read all arrays from from hdf5 file and return them as dict
- pynibs.hdf5_io.simnibs_results_msh2hdf5(fn_msh, fn_hdf5, S, pos_tms_idx, pos_local_idx, subject, mesh_idx, mode_xdmf='r+', n_cpu=4, verbose=False, overwrite=False, mid2roi=False)¶
Converts simnibs .msh results file(s) to .hdf5 / .xdmf tuple.
- Parameters
fn_msh (str list of str) – Filenames (incl. path) of .msh results files from simnibs
fn_hdf5 (str or list of str) – Filenames (incl. path) of .hdf5 results files
S (Simnibs Session object) – Simnibs Session object the simulations are conducted with
pos_tms_idx (list of int) – Index of the simulation w.r.t. to the simnibs TMSList (inside Session object S) For every coil a separate TMSList exists, which contains multiple coil positions.
pos_local_idx (list of int) – Index of the simulation w.r.t. to the simnibs POSlist in the TMSList (inside Session object S) For every coil a separate TMSList exists, which contains multiple coil positions.
subject (Subject object) – Subject object loaded from .pkl file
mesh_idx (int) – Mesh index
mode_xdmf (str, optional, default: "r+") – Mode to open hdf5_geo file to write xdmf. If hdf5_geo is already separated in tets and tris etc., the file is not changed, use “r” to avoid IOErrors in case of parallel computing.
n_cpu (int) – Number of processes
verbose (bool, optional, default: False) – Print output messages
overwrite (bool, optional, default: False) – Overwrite .hdf5 file if existing
mid2roi (bool or string, optional, default: False) – If the mesh contains ROIs and the e-field was calculated in the midlayer using simnibs (S.map_to_surf = True), the midlayer results will be mapped from the simnibs midlayer to the ROIs (takes some time for large ROIs)
- Returns
<File> – .hdf5 file containing the results. An .xdmf file is also created to link the results with the mesh .hdf5 file of the subject
- Return type
.hdf5 file
- pynibs.hdf5_io.simnibs_results_msh2hdf5_workhorse(fn_msh, fn_hdf5, S, pos_tms_idx, pos_local_idx, subject, mesh_idx, mode_xdmf='r+', verbose=False, overwrite=False, mid2roi=False)¶
Converts simnibs .msh results file to .hdf5 (including midlayer data if desired)
- Parameters
fn_msh (list of str) – Filenames (incl. path) of .msh results files from simnibs
fn_hdf5 (str or list of str) – Filenames (incl. path) of .hdf5 results files
S (Simnibs Session object) – Simnibs Session object the simulations are conducted with
pos_tms_idx (list of int) – Index of the simulation w.r.t. to the simnibs TMSList (inside Session object S) For every coil a separate TMSList exists, which contains multiple coil positions.
pos_local_idx (list of int) – Index of the simulation w.r.t. to the simnibs POSlist in the TMSList (inside Session object S) For every coil a separate TMSList exists, which contains multiple coil positions.
subject (Subject object) – Subject object loaded from .pkl file
mesh_idx (int) – Mesh index
mode_xdmf (str, optional, default: "r+") – Mode to open hdf5_geo file to write xdmf. If hdf5_geo is already separated in tets and tris etc, the file is not changed, use “r” to avoid IOErrors in case of parallel computing.
verbose (bool, optional, default: False) – Print output messages
overwrite (bool, optional, default: False) – Overwrite .hdf5 file if existing
mid2roi (bool, list of string, or string, optional, default:False) – If the mesh contains ROIs and the e-field was calculated in the midlayer using simnibs (S.map_to_surf = True), the midlayer results will be mapped from the simnibs midlayer to the ROIs (takes some time for large ROIs)
- Returns
<File> – .hdf5 file containing the results. An .xdmf file is also created to link the results with the mesh .hdf5 file of the subject
- Return type
.hdf5 file
- pynibs.hdf5_io.split_hdf5(hdf5_in_fn, hdf5_geo_out_fn='', hdf5_data_out_fn=None)¶
Splits one hdf5 into one with spatial data and one with statistical data. If coil data is present in hdf5_in, it is saved in hdf5Data_out. If new spatial data is added to file (curve, inflated, whatever), add this to the geogroups variable.
- Parameters
- Returns
<File> (.hdf5 file) – hdf5Geo_out_fn (spatial data)
<File> (.hdf5 file) – hdf5Data_out_fn (data)
- pynibs.hdf5_io.write_arr_to_hdf5(fn_hdf5, arr_name, data, overwrite_arr=True, verbose=False, check_file_exist=False)¶
Takes an array and adds it to an hdf5 file
If data is list of dict, write_dict_to_hdf5() is called for each dict with adapted hdf5-folder name Otherwise, data is casted to np.ndarray and dtype of unicode data casted to ‘|S’.
- pynibs.hdf5_io.write_data_hdf5(out_fn, data, data_names, hdf5_path='/data', mode='a')¶
Creates a .hdf5 file with data.
- Parameters
out_fn (str) – Filename of output .hdf5 file containing the geometry information
data (nparray or list of nparrays of float) – Data to save in hdf5 data file
data_names (str or list of str) – Labels of data
hdf5_path (str) – Folder in .hdf5 geometry file, where the data is saved in (Default: /data)
mode (str, optional, default: "a") – Mode: “a” append, “w” write (overwrite)
- Returns
<File> – File containing the stored data
- Return type
.hdf5 file
Example
File structure of .hdf5 data file
data |---/data_names[0] [data[0]] First dataset |---/ ... ... ... |---/data_names[N-1] [data[N-1]] Last dataset
- pynibs.hdf5_io.write_data_hdf5_surf(data, data_names, data_hdf_fn_out, geo_hdf_fn, replace=False, replace_array_in_file=True)¶
Saves surface data to .hdf5 data file and generates corresponding .xdmf file linking both. The directory of data_hdf_fn_out and geo_hdf_fn should be the same, as only basenames of files are stored in the .xdmf file.
- Parameters
data (ndarray or list [N_points_ROI x N_components]) – Data to map on surfaces
data_hdf_fn_out (str) – Filename of .hdf5 data file
geo_hdf_fn (str) – Filename of .hdf5 geo file containing the geometry information (has to exist)
replace (boolean, optional, default: False) – Replace existing .hdf5 and .xdmf file completely
replace_array_in_file (boolean, optional, default: True) – Replace existing array in file
- Returns
<File> (.hdf5 file) – data_hdf_fn_out.hdf5 containing data
<File> (.xdmf file) – data_hdf_fn_out.xdmf containing information about .hdf5 file structure for Paraview
Example
File structure of .hdf5 data file
/data |---/tris | |---dataset_0 [dataset_0] (size: N_dataset_0 x M_dataset_0) | |--- ... | |---dataset_K [dataset_K] (size: N_dataset_K x M_dataset_K)
- pynibs.hdf5_io.write_dict_to_hdf5(fn_hdf5, data, folder, check_file_exist=False, verbose=False)¶
Takes dict (from subject.py) and passes its keys to write_arr_to_hdf5()
- pynibs.hdf5_io.write_geo_hdf5(out_fn, msh, roi_dict=None, hdf5_path='/mesh')¶
Creates a .hdf5 file with geometry data from mesh including region of interest(s).
- Parameters
out_fn (str) – Filename of output .hdf5 file containing the geometry information
msh (TetrahedraLinear object instance) – Mesh of TetrahedraLinear class
roi_dict (dict of RegionOfInterestSurface and/or RegionOfInterestVolume object instance(s)) – Region of interest (surface and/or volume) class instance
hdf5_path (str) – Folder in .hdf5 geometry file, where the mesh information are saved in (Default: /mesh)
- Returns
<File> – File containing the geometry information
- Return type
.hdf5 file
Example
File structure of .hdf5 geometry file
mesh I---/elm I I--/elm_number [1,2,3,...,N_ele] Running index over all elements starting at 1 (triangles and tetrahedra) I I--/elm_type [2,2,2,...,4,4] Element type: 2 triangles, 4 tetrahedra I I--/tag1 [1001,1001, ..., 4,4,4] Surface (100X) and domain (X) indices with 1000 offset for surfaces I I--/tag2 [ 1, 1, ..., 4,4,4] Surface (X) and domain (X) indices w/o offset I I--/triangle_number_list [1,5,6;... ;1,4,8] Connectivity of triangles [X, X, X] I I--/tri_tissue_type [1,1, ..., 3,3,3] Surface indices to differentiate between surfaces I I--/tetrahedra_number_list [1,5,6,7;... ;1,4,8,12] Connectivity of tetrahedra [X, X, X, X] I I--/tet_tissue_type [1,1, ..., 3,3,3] Volume indices to differentiate between volumes I I--/node_number_list [1,5,6,0;... ;1,4,8,9] Connectivity of triangles [X, X, X, 0] and tetrahedra [X, X, X, X] I I---/nodes I I--/node_coord [1.254, 1.762, 1.875;...] Node coordinates in (mm) I I--/node_number [1,2,3,...,N_nodes] Running index over all points starting at 1 I I--/units ['mm'] .value is unit of geometry roi_surface I---/0 Region of Interest number I I--/node_coord_up [1.254, 1.762, 1.875;...] Coordinates of upper surface points I I--/node_coord_mid [1.254, 1.762, 1.875;...] Coordinates of middle surface points I I--/node_coord_low [1.254, 1.762, 1.875;...] Coordinates of lower surface points I I--/tri_center_coord_up [1.254, 1.762, 1.875;...] Coordinates of upper triangle centers I I--/tri_center_coord_mid [1.254, 1.762, 1.875;...] Coordinates of middle triangle centers I I--/tri_center_coord_low [1.254, 1.762, 1.875;...] Coordinates of lower triangle centers I I--/node_number_list [1,5,6,0;... ;1,4,8,9] Connectivity of triangles [X, X, X] I I--/delta 0.5 Distance parameter between GM and WM surface I I--/tet_idx_tri_center_up [183, 913, 56, ...] Tetrahedra indices where triangle center of upper surface are lying in I I--/tet_idx_tri_center_mid [185, 911, 58, ...] Tetrahedra indices where triangle center of middle surface are lying in I I--/tet_idx_tri_center_low [191, 912, 59, ...] Tetrahedra indices where triangle center of lower surface are lying in I I--/tet_idx_node_coord_mid [12, 15, 43, ...] Tetrahedra indices where the node_coords_mid are lying in I I--/gm_surf_fname .../surf/lh.pial Filename of GM surface from segmentation I I--/wm_surf_fname .../surf/lh.white Filename of WM surface from segmentation I I--/layer 3 Number of layers I I--/fn_mask .../simnibs/mask.mgh Filename of region of interest mask I I--/X_ROI [-10, 15] X limits of region of interest box I I--/Y_ROI [-10, 15] Y limits of region of interest box I I--/Z_ROI [-10, 15] Z limits of region of interest box I I---/1 I I ... roi_volume I---/0 Region of Interest number I I--/node_coord [1.254, 1.762, 1.875;...] Coordinates (x,y,z) of ROI nodes I I--/tet_node_number_list [1,5,6,7;... ;1,4,8,9] Connectivity matrix of ROI tetrahedra I I--/tri_node_number_list [1,5,6;... ;1,4,8] Connectivity matrix of ROI triangles I I--/tet_idx_node_coord [183, 913, 56, ...] Tetrahedra indices where ROI nodes are I I--/tet_idx_tetrahedra_center [12, 15, 43, ...] Tetrahedra indices where center points of ROI tetrahedra are I I--/tet_idx_triangle_center [12, 15, 43, ...] Tetrahedra indices where center points of ROI triangles are I---/1 I I ...
- pynibs.hdf5_io.write_geo_hdf5_surf(out_fn, points, con, replace=False, hdf5_path='/mesh')¶
Creates a .hdf5 file with geometry data from midlayer.
- Parameters
out_fn (str) – Filename of output .hdf5 file containing the geometry information
points (nparray [N_points x 3]) – Coordinates of nodes (x,y,z)
con (nparray [N_tri x 3]) – Connectivity list of triangles
replace (boolean) – Replace .hdf5 geometry file (True / False)
hdf5_path (str) – Folder in .hdf5 geometry file, where the geometry information is saved in (Default: /mesh)
- Returns
<File> – File containing the geometry information.
- Return type
.hdf5 file
Example
File structure of .hdf5 geometry file:
mesh |---/elm | |--/triangle_number_list [1,5,6;... ;1,4,8] Connectivity of triangles [X, X, X] | |--/tri_tissue_type [1,1, ..., 3,3,3] Surface indices to differentiate between surfaces | |---/nodes | |--/node_coord [1.2, 1.7, 1.8; ...] Node coordinates in (mm)
- pynibs.hdf5_io.write_temporal_xdmf(hdf5_fn, data_folder='c', coil_center_folder=None, coil_ori_0_folder=None, coil_ori_1_folder=None, coil_ori_2_folder=None, coil_current_folder=None, hdf5_geo_fn=None, overwrite_xdmf=False, verbose=False)¶
Creates .xdmf markup file for given ROI hdf5 data file with 4D data. This was written to be able to visualize data from the permutation analysis of the regression approach It expects an .hdf5 with a data group with (many) subarrays. The N subarrays name should be named from 0 to N-1 Each subarray has shape = (N_elemns,1)
Not tested for whole brain.
- hdf5:/data_folder/0
/1 /2 /3 /4 …
- Parameters
hdf5_fn (str) – Filename of hdf5 file containing the data
data_folder (str) – Path within hdf5 to group of dataframes
hdf5_geo_fn (str (optional)) – Filename of hdf5 file containing the geometry
overwrite_xdmf (boolean) – Overwrite existing xdmf file if present
coil_center_folder (str) –
coil_ori_0_folder (str) –
coil_ori_1_folder (str) –
coil_ori_2_folder (str) –
coil_current_folder (str) –
verbose (boolean) – Print output or not
- Returns
<File> – hdf5_fn[-4].xdmf
- Return type
.xdmf file
- pynibs.hdf5_io.write_xdmf(hdf5_fn, hdf5_geo_fn=None, overwrite_xdmf=False, overwrite_array=False, verbose=False, mode='r+')¶
Creates .xdmf markup file for given hdf5 file, mainly for paraview visualization. Checks if triangles and tetrahedra already exists as distinct arrays in hdf5_fn . If not, these are added to the .hdf5 file and rebased to 0 (from 1). If only hdf5_fn is provided, spatial information has to be present as arrays for tris and tets in this dataset.
- Parameters
hdf5_fn (str) – Filename of hdf5 file containing the data
hdf5_geo_fn (str) – Filename of hdf5 file containing the geometry. Optional.
overwrite_xdmf (bool) – Overwrite existing xdmf file if present. Default: False.
overwrite_array (bool) – Overwrite existing arrays if present. Default: False.
verbose (boolean) – Print output or not
mode (str, optional, default: "r+") – Mode to open hdf5_geo file. If hdf5_geo is already separated in tets and tris etc., nothing has to be written, use “r” to avoid IOErrors in case of parallel computing.
- Returns
<File> (.xdmf file) – hdf5_fn[-4].xdmf (only data if hdf5Geo_fn provided)
<File> (.hdf5 file) – hdf5_fn changed if neccessary
<File> (.hdf5 file) – hdf5geo_fn containing spatial data
pynibs.main module¶
pynibs.muap module¶
pynibs.neuron module¶
pynibs.opt module¶
pynibs.para module¶
- pynibs.para.ResetSession()¶
Resets Paraview session (needed if multiple plots are generated successively)
- pynibs.para.b2rcw(cmin_input, cmax_input)¶
BLUEWHITERED Blue, white, and red color map. This function is designed to generate a blue to red colormap. The color of the colorbar is from blue to white and then to red, corresponding to the data values from negative to zero to positive, respectively. The color white always correspondes to value zero. The brightness of blue and red will change according to your setting, so that the brightness of the color corresponded to the color of his opposite number. e.g. b2rcw(-3,6) is from light blue to deep red e.g. b2rcw(-3,3) is from deep blue to deep red
- pynibs.para.create_plot_settings_dict(plotfunction_type)¶
Creates a dictionary with default plotsettings.
- Parameters
plotfunction_type (str) –
Plot function the dictionary is generated for:
’surface_vector_plot’
’surface_vector_plot_vtu’
’volume_plot’
’volume_plot_vtu’
- Returns
ps (dict) – Dictionary containing the plotsettings:
axes (boolean) – Show orientation axes (TRUE / FALSE)
background_color (nparray [1 x 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 [N_clips x 3]) – Coordinates of clip surface origins (x,y,z)
clip_normals (nparray of float [N_clips x 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) – Type of clipping:
’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
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 (boolean) – Plot coil axes visualizing the principle direction and orientation of the coil (Default: True)
colorbar_label (str) – Label of plotted data close to colorbar
colorbar_position (list of float [1 x 2]) – Position of colorbar (lower left corner) 0…1 [x_pos, y_pos]
colorbar_orientation (str) – Orientation of colorbar (‘Vertical’, ‘Horizontal’)
colorbar_aspectratio (int) – Aspectratio of colorbar (higher values make it thicker)
colorbar_titlefontsize (float) – Fontsize of colorbar title
colorbar_labelfontsize (float) – Fontsize of colorbar labels (numbers)
colorbar_labelformat (str) – Format of colorbar labels (e.g.: ‘%-#6.3g’)
colorbar_numberoflabels (int) – maximum number of colorbar labels
colorbar_labelcolor (list of float [1 x 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
if str: colormap of plotted data chosen from included presets:
’Cool to Warm’,
’Cool to Warm (Extended)’,
’Blue to Red Rainbow’,
’X Ray’,
’Grayscale’,
’jet’,
’hsv’,
’erdc_iceFire_L’,
’Plasma (matplotlib)’,
’Viridis (matplotlib)’,
’gray_Matlab’,
’Spectral_lowBlue’,
’BuRd’
’Rainbow Blended White’
’b2rcw’
colormap_categories (boolean) – Use categorized (discrete) colormap
datarange (list [1 x 2]) – Minimum and Maximum of plotted datarange [MIN, MAX] (default: automatic)
domain_IDs (int or list of int) – Domain IDs
surface plot: Index of surface where the data is plotted on (Default: 0)
volume plot: Specify the domains IDs to show in plot (default: all) Attention! Has to be included in the dataset under the name ‘tissue’! e.g. for SimNIBS:
1 -> white matter (WM)
2 -> grey matter (GM)
3 -> cerebrospinal fluid (CSF)
4 -> skull
5 -> skin
domain_label (str) – Label of the dataset which contains the domain IDs (default: ‘tissue_type’)
edges (boolean) – Show edges of mesh (TRUE / FALSE)
fname_in (str or list of str) – Filenames of input files, 2 possibilities:
.xdmf-file: filename of .xmdf (needs the corresponding .hdf5 file(s) in the same folder)
.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) – Name of .vtu volume file containing volume data (incl. path)
fname_vtu_surface (str) – Name of .vtu surface file containing surface data (incl. path) (to distinguish tissues)
fname_vtu_coil (str) – Name of coil .vtu file (incl. path) (optional)
info (str) – Information about the plot the settings are belonging to
interpolate (boolean) – Interpolate data for visual smoothness (TRUE / FALSE)
NanColor (list of float [3]) – RGB color values for “Not a Number” values (range 0 … 1)
opacitymap (nparray) – Points defining the piecewise linear opacity transfer function (transparency) (default: no transparency) connecting data values with opacity (alpha) values ranging from 0 (max. transparency) to 1 (no transparency)
plot_function (str) – Function the plot is generated with:
’surface_vector_plot’
’surface_vector_plot_vtu’
’volume_plot’
’volume_plot_vtu’
png_resolution (float) – Resolution parameter of output image (1…5)
quantity (str) – Label of magnitude dataset to plot
surface_color (nparray [1 x 3]) – Color of brain surface in RGB (0…1) for better visability of tissue borders
surface_smoothing (bool) – Smooth the plotted surface (True/False)
show_coil (boolean) – show coil if present in dataset as block termed ‘coil’ (Default: True)
vcolor (nparray of float [N_vecs x 3]) – Array containing the RGB values between 0…1 of the vector groups in dataset to plot
vector_mode (dict) – dict key determines the type how many vectors are shown: - ‘All Points’ - ‘Every Nth Point’ - ‘Uniform Spatial Distribution’
dict value (int) is the corresponding number of vectors
’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 [[3 x CameraPosition], [3 x CameraFocalPoint], [3 x CameraViewUp], 1 x CameraParallelScale]
viewsize (nparray [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)
vscales (list of float) – Scale parameters of vector groups to plot
vscale_mode (list of str [N_vecs x 1]) – List containing the type of vector scaling:
’off’: all vectors are normalized
’vector’: vectors are scaled according to their magnitudeeee
- pynibs.para.crop_data_hdf5_to_datarange(ps)¶
Crops the data (quantity) in .hdf5 data file to datarange and overwrites the original .hdf5 data file pointed by the .xdmf file.
- pynibs.para.crop_image(fname_image, fname_image_cropped)¶
Remove surrounding empty space around an image. This implemenation assumes that the surrounding space has the same colour as the top leftmost pixel.
- Parameters
fname_image (str) – Filename of image to be cropped
- Returns
<File> – Cropped image file saved as “fname_image_cropped”
- Return type
.png file
- pynibs.para.surface_vector_plot(ps)¶
Generate plot with Paraview from data in .hdf5 file(s).
- Parameters
ps (dict) – Plot settings dict initialized with create_plot_settings_dict(plotfunction_type=’surface_vector_plot’)
- Returns
<File> – Generated plot
- Return type
.png file
- pynibs.para.surface_vector_plot_vtu(ps)¶
Generate plot with Paraview from data in .vtu file.
- Parameters
ps (dict) – Plot settings dict initialized with create_plot_settings_dict(plotfunction_type=’surface_vector_plot_vtu’)
- Returns
<File> – Generated plot
- Return type
.png file
- pynibs.para.volume_plot(ps)¶
Generate plot with Paraview from data in .hdf5 file.
- Parameters
ps (dict) – Plot settings dict initialized with create_plot_settings_dict(plotfunction_type=’’volume_plot’’)
- Returns
<File> – Generated plot
- Return type
.png file
- pynibs.para.volume_plot_vtu(ps)¶
Generate plot with Paraview from data in .vtu file.
- Parameters
ps (dict) – Plot settings dict initialized with create_plot_settings_dict(plotfunction_type=’’volume_plot_vtu’’)
- Returns
<File> – Generated plot
- Return type
.png file
- pynibs.para.write_vtu(fname, data_labels, points, connectivity, idx_start, data)¶
Writes data in tetrahedra centers into .vtu file, which can be loaded with Paraview.
- Parameters
fname (str) – Name of .vtu file (incl. path)
data_labels (list with N_data str) – Label of each dataset
points (array of float [N_points x 3]) – Coordinates of vertices
connectivity (array of int [N_tet x 4]) – Connectivity of points forming tetrahedra
idx_start (int) – Smallest index in connectivity matrix, defines offset w.r.t Python indexing, which starts at ‘0’
*data (array(s) [N_tet x N_comp(N_data)]) – Arrays containing data in tetrahedra center multiple components per dataset possible e.g. [Ex, Ey, Ez]
- Returns
<File> – Geometry and data information
- Return type
.vtu file
- pynibs.para.write_vtu_coilpos(fname_geo, fname_vtu)¶
Read dipole data of coil (position and magnitude of each dipole) from geo file and store it as vtu file.
- pynibs.para.write_vtu_mult(fname, data_labels, points, triangles, tetrahedras, idx_start, *data)¶
Writes data in triangles and tetrahedra centers into .vtu file, which can be loaded with Paraview.
- Parameters
fname (str) – Name of .vtu file (incl. path)
data_labels (list of str [N_data]) – Label of each dataset
points (nparray of float [N_points x 3]) – Coordinates of vertices
triangles (nparray of int [N_tri x 3]) – Connectivity of points forming triangles
tetrahedras (nparray of int [N_tri x 4]) – Connectivity of points forming tetrahedra idx_start: int smallest index in connectivity matrix, defines offset w.r.t python indexing, which starts at ‘0’
*data (nparray(s) [N_tet x N_comp(N_data)]) – Arrays containing data in tetrahedra center multiple components per dataset possible e.g. [Ex, Ey, Ez]
- Returns
<File> – Geometry and data information
- Return type
.vtu file
pynibs.postproc module¶
pynibs.regression module¶
pynibs.roi module¶
pynibs.simnibs module¶
pynibs.subject module¶
pynibs.tensor_scaling module¶
- pynibs.tensor_scaling.ellipse_eccentricity(a, b)¶
Calculates the eccentricity of an 2D ellipse with the semi axis a and b. An eccentricity of 0 corresponds to a sphere and an eccentricity of 1 means complete eccentric (line) with full restriction to the other axis
- pynibs.tensor_scaling.rescale_lambda_centerized(D, s, tsc=False)¶
Rescales the eigenvalues of the matrix D according to their eccentricity. The scale factor is between 0…1 a scale factor of 0.5 would not alter the eigenvalues of the matrix D. A scale factor of 0 would unify all eigenvalues to one value such that it corresponds to a isotropic sphere. A scale factor of 1 alters the eigenvalues in such a way that the resulting ellipsoid is fully eccentric and anisotropic.
- Parameters
D (nparray of float [3 x 3]) – Diffusion tensor
s (float) – Scale parameter [0 (iso) … 0.5 (unaltered)… 1 (aniso)]
tsc (boolean) – Tensor singularity correction
- Returns
Ds – Scaled diffusion tensor
- Return type
nparray of float [3 x 3]
- pynibs.tensor_scaling.rescale_lambda_centerized_workhorse(D, s, tsc=False)¶
Rescales the eigenvalues of the matrix D according to their eccentricity. The scale factor is between 0…1 a scale factor of 0.5 would not alter the eigenvalues of the matrix D. A scale factor of 0 would unify all eigenvalues to one value such that it corresponds to a isotropic sphere. A scale factor of 1 alters the eigenvalues in such a way that the resulting ellipsoid is fully eccentric and anisotropic
- Parameters
D (ndarray of float [n x 9]) – Diffusion tensor
s (float) – Scale parameter [0 (iso) … 0.5 (unaltered)… 1 (aniso)]
tsc (boolean) – Tensor singularity correction
- Returns
Ds – Scaled diffusion tensor
- Return type
list of nparray of float [3 x 3]