Description: SAMwts 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. SAMwts 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 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, 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. 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!

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" keyword.

The output of SAMwts is now 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 mm" (where mm is the grid spacing in millimetres) in the parameter file. This results in a second NIFTI with a suffix "_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 ORTHO mm" (where mm is any number), which is optional 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 image file. This generates an image file named "brain+tlrc" that is read by the SAMwts program when ImageFormat TLRC is specified. The primary use of orthohull is to generate the hull.shape file used for realistic head modeling (Model Nolte)

The advantage of specifying Talairach space SAM weights is that subsequent analyses are automatically rendered in Talairach space for group studies. SAMwts calls the AFNI program @auto_tlrc, using nearest neighbor transformation (-rmode NN). In order to minimize the positional errors in Talairach space it is recommended that ImageStep designates a finer grid spacing than the transformation. For example, a parameter file containing:

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

Usage:

SAMwts -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, SAMwts works silently, except for error messages.

Optional flags:

-i: designates an optional pathname for the MRI directory (tested for access)
-Z: normalize SAM weights by projected noise
-B: output forward solutions (used together with parameter "TargetName")

Parameters & Keywords: The parameters specific to SAMwts include:

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

Example Parameter File for Rectangular ROI in "ortho" space:

Example Parameter File using Cortical Atlas:

Input File Formats:

1. Target File: 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 centimetres (separated by spaces or tabs).
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 "TargetName" parameter takes precedence over the ROI specifications. If both are present, only the target list will be used. This directs SAMwts to compute legacy formatted weights in the dataset SAM subdirectory. The targets may be specified with or without the "Atlas" keyword.
2. The optional MRI directory (designated by the -i flag) takes precedence over the directory named in the parameter file (if designated there).
3. 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.
4. Increasing the CovBand bandwidth is very useful for improving attenuation of strong interference such as from tDCS, tACS, and vagus nerve stimulators.
5. 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.
6. 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.