TMS Optimization¶
SimNIBS can help finding the best TMS position for stimulating a certain target. This is done by searching coil positions in a grid around the target position and turning the coil at various angles.
Note
When using this feature in a publication, please cite either
or
in case you use the ADM method. The ADM code is distributed under the conditions below:
Authors of auxiliary dipole method (ADM) and code for determining rapidly the optimum coil position and orientation: Luis J. Gomez, Moritz Dannhauer, and Angel V. Peterchev; Duke University, Durham, North Carolina, U.S.A.
The development of the Duke ADM algorithm and code were supported by the National Institute of Mental Health and the National Institute on Aging of the National Institutes of Health under Award Numbers K99MH120046, RF1MH114268, RF1MH114253, and U01AG050618. The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.
The copyrights of this software are owned by Duke University. As such, two licenses to this software are offered:
An open source license under the GNU General Public License (GPL-v2.0) (https://opensource.org/licenses/gpl-2.0.php).
A custom license with Duke University, for use without the GPL-v2.0 restrictions.
As a recipient of this software, you may choose which license to receive the code under. Outside contributions to the Duke owned code base cannot be accepted unless the contributor transfers the copyright to those changes over to Duke University.
To enter a license agreement without the GPL-v2.0 restrictions, please contact the Digital Innovations department at Duke Office of Licensing and Ventures (https://olv.duke.edu/software/) at olvquestions@duke.edu with reference to “OLV File No. 7148” in your email.
Please note that this software is distributed AS IS, WITHOUT ANY WARRANTY; and without the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Basic Setting¶
Setting up a TMS optimization is similar to setting-up a TMS simulation. In the most basic setting, you need to select the head model, the coil being used and the target position. The target position has to be given in SimNIBS coordinates and can be determined using the nifti volumes produced by headreco, mri2mesh or by using the mni2subject_coords command line tool.
For accelerating the simulations, SimNIBS can use the MKL Pardiso direct solver. However, this solver uses approximately three times more memory than the standard solver.
Python¶
import os
from simnibs import opt_struct
# Initialize structure
tms_opt = opt_struct.TMSoptimize()
# Subject folder
tms_opt.subpath = 'm2m_ernie'
# Select output folder
tms_opt.pathfem = 'tms_optimization/'
# Select the coil model
tms_opt.fnamecoil = os.path.join('legacy_and_other','Magstim_70mm_Fig8.ccd')
# Select a target for the optimization
tms_opt.target = [-39.7, 7.5, 65.6]
# Optional: Use the MKL PARDISO solver
# Will make the simulations much faster
# but has large (approx 12GB) memory usage
tms_opt.solver_options = 'pardiso'
# Run optimization to get optimal coil position
opt_pos=tms_opt.run()
MATLAB¶
% Example script to run a TMS optimization
% Guilherme Saturnino, 2019
tms_opt = opt_struct('TMSoptimize');
% Subject folder
tms_opt.subpath = 'm2m_ernie';
% Select output folder
tms_opt.pathfem = 'tms_optimization/';
% Select the coil model
tms_opt.fnamecoil = fullfile('legacy_and_other','Magstim_70mm_Fig8.ccd');
% Select a target for the optimization
tms_opt.target = [-39.7, 7.5, 65.6];
% Optional: Use the MKL PARDISO solver
% Will make the simulations much faster
% but has large (approx 12GB) memory usage
tms_opt.solver_options = 'pardiso';
% Run optimization
run_simnibs(tms_opt);
This will first generate a grid of positions and start simulating. After it is done simulating, SimNIBS will return with the position that causes the largest electric field magnitude at the target.
The optimization will create the Gmsh output file ernie_TMS_optimize_Magstim_70mm_Fig8_nii.msh with the optimized field and coil position
Refining the Search¶
If you already have a good idea of where and how the coil should be located or oriented, you can refine the search by precisely specifying the search region, search angles and resolution.
Python¶
''' Refining the TMS Optimization '''
import os
from simnibs import opt_struct
# Initialize structure
tms_opt = opt_struct.TMSoptimize()
# Subject folder
tms_opt.subpath = 'm2m_ernie'
# Select output folder
tms_opt.pathfem = 'tms_optimization_refined/'
# Select the coil model
tms_opt.fnamecoil = os.path.join('legacy_and_other','Magstim_70mm_Fig8.ccd')
# Select a target for the optimization
tms_opt.target = [-39.7, 7.5, 65.6]
# Optional: Use the MKL PARDISO solver
# Will make the simulations much faster
# but has large (approx 12GB) memory usage
tms_opt.solver_options = 'pardiso'
# Set the center of the search area
tms_opt.centre = [-52.5, 8.8, 78.7]
# Change the search radius
tms_opt.search_radius = 10
# Change the search resolution
tms_opt.spatial_resolution = 2.5
# Set the coil direction reference
tms_opt.pos_ydir = [-52.5, 2.9, 80.0]
# Change the angles to include in the search
tms_opt.search_angle = 90
# Change the angular resolution
tms_opt.angle_resolution = 15
# Run optimization
tms_opt.run()
MATLAB¶
% Refining the TMS Optimization
% Initialize structure
tms_opt = opt_struct('TMSoptimize');
% subject folder
tms_opt.subpath = 'm2m_ernie';
% Select output folder
tms_opt.pathfem = 'tms_optimization_refined/';
% Select the coil model
tms_opt.fnamecoil = fullfile('legacy_and_other','Magstim_70mm_Fig8.ccd');
% Select a target for the optimization
tms_opt.target = [-39.7, 7.5, 65.6];
% Optional: Use the MKL PARDISO solver
% Will make the simulations much faster
% but has large (approx 12GB) memory usage
tms_opt.solver_options = 'pardiso';
% Set the center of the search area
tms_opt.centre = [-52.5, 8.8, 78.7];
% Change the search radius
tms_opt.search_radius = 10;
% Change the search resolution
tms_opt.spatial_resolution = 2.5;
% Set the coil direction reference
tms_opt.pos_ydir = [-52.5, 2.9, 80.0];
% Change the angles to include in the search
tms_opt.search_angle = 90;
% Change the angular resolution
tms_opt.angle_resolution = 15;
run_simnibs(tms_opt)
Auxiliary Dipole Method (ADM)¶
To use the Auxiliary Dipole Method (ADM), simply use a .ccd coil file and set the method = 'ADM':
tms_opt.fnamecoil = os.path.join('legacy_and_other','Magstim_70mm_Fig8.ccd')
tms_opt.method = 'ADM'
Python¶
import os
from simnibs import opt_struct, mni2subject_coords
# Initialize structure
tms_opt = opt_struct.TMSoptimize()
# Subject folder
tms_opt.subpath = 'm2m_ernie'
# Select output folder
tms_opt.pathfem = 'tms_optimization_adm'
# Select the coil model
# The ADM method requires a '.ccd' coil model
tms_opt.fnamecoil = os.path.join('legacy_and_other','Magstim_70mm_Fig8.ccd')
# Select a target for the optimization
tms_opt.target = mni2subject_coords([-37, -21, 58], 'm2m_ernie')
# Use the ADM method
tms_opt.method = 'ADM'
# Run optimization
opt_pos=tms_opt.run()
MATLAB¶
tms_opt = opt_struct('TMSoptimize');
% Subject folder
tms_opt.subpath = 'm2m_ernie';
% Select output folder
tms_opt.pathfem = 'tms_optimization_adm';
% Select the coil model
% The ADM method requires a '.ccd' coil model
tms_opt.fnamecoil = fullfile('legacy_and_other','Magstim_70mm_Fig8.ccd');
% Select a target for the optimization
tms_opt.target = mni2subject_coords([-37, -21, 58], 'm2m_ernie');
% Use the ADM method
tms_opt.method = 'ADM';
% Run optimization
run_simnibs(tms_opt);
Acknowledgements¶
We would like to thank Ole Numssen and Konstantin Weise for helping with the development of this functionality, and Luis Gomez for contributing the code for the ADM optimization.
Further Reading¶
Please see TMSoptimize for a detailed description of all TMS optimization options.
