Sam wts

Return to Source Localization - SAM

Description

sam_wts computes linearly constrained minimum variance (LCMV) beamformer coefficients (SAM weights) for any designated ROI or target voxel list using the covariance files within the named dataset, calculated by sam_cov. sam_wts is a scalar beamformer in which the optimal source dipole orientation is determined first, followed by computation of the scalar weights. Source orientation is estimated from a separate orientation covariance matrix (Orient.cov) that uses all data samples and a specified passband (ideally one in which signal-to-noise is optimal; see sam_cov). It is assumed that source orientation is stationary across time, whereas source amplitude may be non-stationary.

In contrast to setting up a rectilinear grid by hand, an “atlas” file (created from a FreeSurfer parcellation) containing the position and orientation vectors of neocortical sources can be designated with the Atlas parameter. If the atlas file is present, the source grid (ROI and voxel spacing) is predetermined and the orientation estimate step is bypassed. 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. If an atlas is specified, sam_wts will only solve for voxels that are immediate neighbors to the FreeSurfer surface, which will produce a sparse representation in a rectilinear voxel space.

Three forward models are available for computing weights that are selectable using the Model parameter:

• A single homogeneously conducting sphere, computed using the Sarvas equation.
• Multiple local spheres, one per sensor, also computed with Sarvas.
• A realistic head model (using the Nolte equations) computed

with an estimate of the inner skull surface as determined by the AFNI program 3dSkullStrip.

If desired, the covariance matrix can be regularized by adding a fixed noise value to its diagonal using the Mu or PropMu parameters. Regularization is in units of fT/\surdHz.

Users who wish to develop real-time beamforming can also output a file containing the forward solutions for a small list of target locations using the -B option together with specifying a target file using the TargetName parameter (or -t).

The output of sam_wts is a NIFTI file (number of voxels x number of sensors). In this format the SAM coefficients can be transformed to Talairach space by specifying ImageFormat TLRC RES (where RES is the grid spacing in millimetres) in the parameter file. This results in a second NIFTI file with a suffix of _at.nii, labeling it as @auto_tlrc output. If ImageFormat is absent, the weights default to the coordinates and grid spacing specified in the parameter ROI, as designated by XBounds, YBounds, ZBounds, and ImageStep. The user can also use ImageFormat ORIG, for which the output is .nii, only.

Transformation of the SAM coefficients to Talairach space requires that the specified subject has an MRI that has been transformed to Talairach space. The recommended procedure is to run orthohull using the -t option on the subject’s anat+orig AFNI image file. This generates an image file named brain+tlrc that is read by the sam_wts program when ImageFormat TLRC is specified.

The advantage of specifying Talairach space SAM weights is that subsequent analyses are automatically rendered in Talairach space for group studies. sam_wts calls the AFNI program @auto_tlrc, using nearest neighbor transformation (-rmode NN). Note that if the same resolution is used for ImageStep and the Talairach transform, with a nearest neighbor transformation, the output may contain neighboring voxels with the same beam former weights. In order to avoid this, it is recommended that ImageStep designates a finer grid spacing than the transformation. For example, a parameter file containing:

 XBounds 10 10
 YBounds -9 9
 ZBounds 0 15
 ImageStep .5
 ImageFormat TLRC 8.

will compute SAM weights on a 5 mm grid and transform this to an 8 mm Talairach grid, using the nearest neighbors in ortho space for the corresponding weight in Talairach space.

It’s also perfectly fine to run @auto_tlrc separately on the functional images produced by other SAM programs (such as sam_3d).

Usage

 sam_wts -r <dataset_name> -m <parameter_file_name> [options]

The -r flag designates the dataset name (with or without the .ds suffix), and -m designates the parameter file name.

Other options:

 -v  Verbose mode, without this flag sam_wts works silently except for error messages
 -Z  Normalize the SAM weights by the projected noise.
 -B  Output forward solutions for a target list (along with the weights)
 -h  Show help

Required Parameters (in the .param file or on the command line):

 Model: Specify the head model
 XBounds,YBounds,ZBounds,ImageStep or Atlas: Define the output coordinate space
 CovBand: Bandwidth used for covariance matrix calculation

Optional Parameters:

 MRIDirectory: Specify where to locate the necessary MRI files
 PrefixLength: Specify characters used for identifying MRI and headmodel files.
 TargetName: Specify use of a list of coordinates on which to calculate the weights
 Atlas: Specify use of a FreeSurfer surface atlas
 Transform: Specify a transform for the Atlas
 NumMarkers and MarkerN: Specify task markers
 ImageFormat: Specify Talairach or orig space weights

Notes:

The TargetName parameter takes precedence over the ROI (XBounds, YBounds, ZBounds) specifications. If both are present, only the target list will be used. This directs sam_wts to compute legacy formatted weights in the dataset SAM subdirectory. The targets may be specified with or without the Atlas parameter. The named target file must be located in the subject’s MRI subdirectory (specified by the MRIDirectory and PrefixLength keywords). Each line has three numbers — the x, y, and z-coordinates in centimeters separated by whitespace (tab or space) and terminated with a newline character. The 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. 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 file must be moved or copied to the subject’s MRI subdirectory. DataEditor can be used to view the virtual sensor (source) time-series for a small number of target locations by reading its SAM weights.

Each line in the Atlas file has six numbers — the x, y, and z-coordinates (meters) and x, y, and z orientation (unit vector) (separated by whitespace).

Increasing the CovBand bandwidth is very useful for improving attenuation of strong interference such as from tDCS, tACS, and vagus nerve stimulators.

Output Files

sam_weights will produce 3D+time nifti (.nii) format output images. Instead of time, each sub-brick will correspond to a single sensor. The weights file will be placed in the same subdirectory as the covariance matrices, and will be named according to the covariance file used to generate them. For example, if Global.cov was used to generate the covariance matrix, the weights will be stored in Global.nii.

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.