SAMNwts Version 3

Description: SAMNwts is a simultaneous solution for a sparse number of linearly constrained minimum variance (LCMV) beamformer coefficients (SAM weights). Unlike SAMwts SAMNwts can correctly compute coefficients for both correlated and uncorrelated sources. It cannot be applied to a large ROI because each target coordinate costs one degree of freedom from the covariance matrix. For example, a 275-channel MEG has only 275 degrees of freedom with which to attenuate unwanted signal such as "brain noise" and environmental noise.

SAMNwts reads the covariance files within the named dataset for the covariance bandpass (CovBand) and a list of target voxels (specified by the parameter keyword "TargetName". Like SAMwts, SAMNwts is a scalar beamformer in which the optimal source dipole orientation is determined first - followed by [simultaneous] computation of the scalar beamformer coefficients. Source orientation is estimated from a separate orientation covariance matrix (Orient.cov) that uses all data samples and a passband in which signal-to-noise is optimal (see SAMcov). It is assumed that source orientation is stationary, whereas source amplitude may be non-stationary. An "atlas" file containing the position and orientation vectors of [neocortical] sources can be designated in the parameter file. If the atlas file is present, SAMNwts searches for the nearest voxel to each target and bypasses the orientation step by using the predetermined source orientation. In addition, the parameter file can designate a transform used to refine the translation and rotation of the atlas file. Generation of an atlas file requires FreeSurfer, FSnormals.py, and reduce_surface.py. At present, methods for computing the transform file are still under test. Three forward models are available for computing weights that are selectable using the "Model" keyword in that parameter file: 1) a single homogeneously conducting sphere (Sarvas), 2) multiple local spheres, and 3) realistic head model (Nolte).

If desired, the covariance matrix can be regularized by using the "Mu" keyword. If the Mu value is preceded by a "+" then a fixed noise value (units of fT/√Hz) is added to the covariance diagonal. If the Mu value is preceded by a "*" then the covariance diagonal is multiplied by that value. Regularization of the covariance matrix degrades the spatial selectivity of the beamformer coefficients. Use this optional parameter with caution!

Usage:

SAMNwts -r <dataset_name> -m < parameter_file_name> (optional flags) -v

where -r designates the dataset name (with or without the .ds suffix), -m designates the parameter file name without the .param suffix, and -v is "verbose" mode. Without -v, SAMNwts works silently, except for error messages.

Optional flags:

-i <mri_directory_path>: designates an optional pathname for the MRI directory, taking precedence over the path designated in the parameter file
-Z: normalize SAM weights by projected noise

Parameters & Keywords: The parameters specific to SAMNwts include:

NumMarkers
Marker1
Marker2
...
Marker6
XBounds
YBounds
ZBounds
ImageStep
ImageFormat
TargetName
MRIDirectory
PrefixLength
Atlas
Transform
Mu
Model

Example Parameter File:

NumMarkers 3
Marker1 9r0 -0.25 0.25 TRUE
Marker2 9r1 -0.25 0.25 TRUE
Marker3 9r2 -0.25 0.25 TRUE
CovBand 4.0 100.0
ImageBand 35.0 45.0
OrientBand 14.0 30.0
TargetName example_target
MRIDirectory WXYZABCD
PrefixLength 8
Model Nolte
CovType SUM

Input File Formats:

  1. Target File: Each line has three numbers - the x, y, and z-coordinates in centimetres (separated by spaces or tabs). The target file must must be located in the subject's MRI subdirectory - specified by the keywords "MRIDirectory" and "PrefixLength".
  2. Atlas File: Each line has six numbers - the x, y, and z coordinates (metres) and x, y, and z orientation (unit vector) (separated by spaces or tabs).

Notes:

  1. The named target file used in the current version of SAM must not have the number of targets in the first line. Instead, each line contains the x, y, z coordinates (cm) separated by tabs or spaces and terminated by a newline character.
  2. Increasing the CovBand bandwidth is very useful for improving attenuation of strong interference such as from tDCS, tACS, and vagus nerve stimulators.
  3. DataEditor can be used to view the virtual sensor (source) time-series for a small number of target locations by reading its SAM weights. If the "-Z" flag is used to generate the weights, the units will be beamformer output signal-to-noise. Otherwise, the units are A-m.
  4. A target file can be generated by NIFTIPeak, which reads a SAM image file (.nii) and finds its local maxima. The maxima coordinates are output to a .max file in order of their magnitude. This list (without the number of targets) must be moved or copied to the subject's MRI subdirectory.
  5. Note that the targets cannot be placed too close to one another as this may exceed the numerical resolution of double precision math and result in errors in beamformer coefficients.