Tunable Parameters

Return to Source Localization - SAM

All SAM analyses are directed by a named parameter file. The format of this file is plain text and can be created using any convenient text editor (i.e., vi, gedit, emacs, etc.). The parameter file is normally specified with -m.

Parameters may be abbreviated, and except where noted may also be specified on the command line prefixed with two dashes, e.g., --DataSet. Some also have single dash option flags (-h), and some (e.g., ds) may be specified as exported environment variables.

Parameters specified on the command line or environment override those specified in a parameter file. If command line options are used, the actual parameters that the analysis was run with will be reconstituted as a .param file in the SAM director of the MEG dataset.

Finally, you may also define an optional parameter file called .samrc in the directory from which the program is run, which may contain parameters common to a set of analyses.

Metaparameters

 %include PNAME

Specifies an additional parameter file to be read at that point. Parameters specified in the file which are already set will not be changed.

 Verbose

Enable verbose output. May be specified on the command line as -v.

Input and Output File Specification

DataSet

 DataSet DNAME

Specifies the MEG dataset to be analyzed. Specified on the command line using -r, or with the $ds environment variable.

PDFName

 PDFName PDFNAME

Only used for 4D/BTi datasets, this specifies the additional PDF file. Specified on the command line using -d.

MRIDirectory

 MRIDirectory MRIDIR

Specifies the MRI directory root. May also be specified on the command line with -i. Several files, derived from a participant’s anatomical MRI, are used in SAM analysis. By default, they are found using this directory and the MRIPattern. The files are the subject’s hull and ortho-space MRI transformed to Talairach space. By default, these are named hull.shape and ortho+tlrc. If MRIDirectory is absent, the SAM programs will look for hull.shape in the dataset directory. There is no default for the ortho MRI. If the Talairach transform is applied to the SAM beamformer coefficients, this is a required parameter. Using MRIDirectory is highly recommended in applications for batch analysis of large numbers of datasets and especially for using AFNI for group statistics.

MRIPattern

 MRIPattern PATTERN

This parameter controls how the input MRI files are assumed to be named. The default MRIPattern is %M/%P/%s, where %M represents the MRI root directory, %P is the first N characters of the dataset name (the length of the string can be designated with the PrefixLength parameter), and %s is replaced by the actual file name. Thus, under the default behavior, for dataset ABABABAB_rest_01.ds the hull.shape file would be assumed to have the following path:

  MRIDIR/ABABABAB/hull.shape

The full list of pattern variables which can be used:

~	(tilde) the value of $HOME
%M	the value of the MRIDirectory parameter
%P	the N (default 8) character prefix of the dataset name
%s	the passed name
%d	the dataset name
%H	(hashcode), the 1st “_” delimited field of the dataset name
%S	the study type (2nd field of the dataset name)
%D	the date (3rd field)
%R	the run number (4th field)

PrefixLength

 PrefixLength N

This parameter controls the number of characters at the beginning of the MEG dataset that are used to find the required MRI files, and to name the output files. The default is 8, according to the NIH convention for naming MEG datasets with an 8 digit hash code. For sites having a different number of characters for identifying datasets and participants, PrefixLength can be used. Note that setting PrefixLength to 0 will assume that all MRI files are in the MRIDirectory without subject-specific subdirectories.

ImageDirectory

 ImageDirectory IMAGEDIR

If present, this parameter specifies the directory where the NIFTI image files are written. If absent, the images are written to the SAM subdirectory inside the dataset. This option is highly recommended for batch analysis of large numbers of datasets and for using AFNI for group statistics.

Marker Related Specification

NumMarkers

 NumMarkers N

This parameter is deprecated, the value is ignored.

Marker

 Marker[N] MARKNAME T0 T1 TRUE|FALSE [COVNAME]

Specify Markers, which may optionally be numbered. Each Marker parameter requires four arguments: the marker name, the start and end time relative to this marker (in seconds) and a flag (TRUE or FALSE) indicating whether this marker is to be included in the SUM covariance and beamformer coefficients. An optional fifth argument specifies the name of the covariance matrix, which defaults to the marker name. Markers cannot be specified on the command line. For example:

 Marker r0 -.25 .25 FALSE
 Marker r1 -.25 .25 FALSE
 Marker r2 -.25 0 TRUE r2pre
 Marker r2 0 .25 TRUE r2post

SegFile

 SegFile MARKNAME FILE TRUE|FALSE

Specifies a Marker using a file. The lines of the file must contain three columns, "trial T0 T1", where the first trial is 0, and T0 and T1 are in seconds. Not applicable with analyses which assume constant length segments (everything except sam_3d). Incompatible with DataSegment.

DataSegment

 DataSegment START END

The DataSegment specifies the time, relative to the markers, over which sam_cov calculates the SUM and ALL covariance matrices. This parameter can be used to extend the integration window beyond what is specified by T0 and T1 in the MarkerN specification. This parameter also interacts with several SAM imaging programs where a lead-in time is required for computing RVE or power.

Evoked or Event Related Parameters

Baseline

 Baseline START END

This parameter is used by sam_ers and sam_ersc only. This gives the start and end times, relative to the first Marker, over which the baseline is calculated (and subtracted). If baseline subtraction is not desired, omit this parameter. For example, the following parameters could be used for a somatosensory evoked response analysis:

 Marker npuff 0 0.2
 DataSegment -0.2 0.2
 Baseline -0.2 0

SignSegment

 SignSegment START END

This parameter designates the time, relative to Marker1 and/or Marker 2 for determine the polarity of sam_ers and |sam_ersc voxel time courses. This parameter can be used to resolve the ambiguity in the polarity of the SAM beamformer. Users should be mindful that voxels containing only noise will also be forced to be positive in the SignSegment time interval, which may lead to undesired results when averaging images.

Image Coordinate Space Specification

XYZBounds

 XBounds START END
 YBounds START END
 ZBounds START END

Required for sam_wts — except when using an Atlas or a target list (-t option to sam_wts). In the latter case, the image bounds are determined by the atlas ROI limits. XBounds sets the anterior-posterior ROI dimensions in centimeters, where it is positive in the anterior direction. YBounds sets the left-right ROI dimensions, which is positive in the left direction. ZBounds sets the inferior-superior ROI dimensions, which is positive in the superior direction. Units of START and END are in centimeters

ImageStep

 ImageStep STEP

Required for all SAM image analyses — except when using an atlas or a target file list. Units are in centimeters

HullName

 HullName HULLFILE

The hull file estimates the boundary of the inner skull surface, which is used for magnetic field calculations when using the Nolte magnetic field model, and also the boundary of the ROI when using MultiSphere. Voxels in the space defined by XBounds, YBounds, and ZBounds that lie outside the hull are not calculated. Hulls are computed using orthohull.

ImageFormat

 ImageFormat ORIG|TLRC RES

This parameter controls how the SAM beamformer coefficients (weights) are generated. The default is ORIG in which the weights correspond precisely to the ROI and grid spacing specified by XBounds, YBounds, ZBounds and ImageStep. The beamformer weights are written as a NIFTI file. Designating the ImageFormat as TLRC will apply the AFNI program @auto_tlrc to the beamformer weight file, transforming the weights into the common Talairach space according to the Talairach transform included in the ortho+tlrc MRI image. The transform is applied to each SAM coefficient file. The original weight files are retained and the new transformed file names are appended with _at.nii. The resolution of the transform is specified in millimeters. It is recommended that the original ROI grid spacing (specified by ImageStep) be smaller than the Talairach grid spacing because the transform uses nearest neighbor to move the ortho grid to Talairach grid. The Talairach transform can also be applied to weights derived from an atlas. This parameter cannot be specified on the command line.

Mask

 Mask MASKFILE

Mask file name required when ImageFormat TLRC is used. The mask file resolution must agree with the resolution (RES) specified in ImageFormat.

Atlas

 Atlas ATLASFILE

Instead of using a rectilinear space of voxels, beam former weights can be calculated for each "voxel" or greyordinate on a cortical surface derived from the MRI using FreeSurfer. The atlas file contains the coordinates and orientation vector for each neocortical location. An atlas may be generated by applying FSnormals.py and reduce_surface.py to the subject’s surface data obtained from FreeSurfer. If present, it overrides the XBounds, YBounds, ZBounds, and ImageStep parameters. The default location of the atlas is set using the MRIDirectory, PrefixLength, and MRIPattern parameters.

Surface

 Surface white|smoothwm|pial

Specifies which surface was used to create the cortical normals contained in the Atlas file.

Transform

 Transform

This parameter is only used if sam_coreg is used. sam_coreg will use the FreeSurfer normals and the MEG data to determine the best fit coregistration of the MRI and MEG. The result will be a transform, the name of which defaults to <surface>.xfm where <surface> is the FreeSurfer surface used (see the Surface parameter). The given transform defines a translation and rotation to be applied to the MEG sensors. By default no transform is applied, you must specify Transform (no arguments) to use the transform.

TargetName

 TargetName TARGETFILE

Instead of estimating beamformer weights at every point within a rectilinear grid, or on a surface, you can instead request beamformer weights only for a discrete list of coordinates. The Target file is a simple text file which gives x, y, and z coordinates (in centimeters), with one set of coordinates per line. SAM routines will look for the target file in the MRI directory of the designated participant (or, if PrefixLength is set to 0, the directory designated by MRIDirectory).

Extent

 Extent EXT

The primary purpose of Extent is to give an extent to the ROI centroids listed in a Target file for use by patch_wts or roi_wts. Extent can also be used by sam_wts to add interpolation around each voxel or target. Units are in mm.

ROIList

 ROIList ROILISTFILE

After running FSNormals.py, the result is a .norm file that gives the list of vertices for each ROI in the selected FreeSurfer parcellation (generally, the Desikan or Destrieux). However, the user may not want to estimate the beamformer for all ROIs in the parcellation, in order to save computational time and reduce the multiple comparisons problem. Standard ROIList files are distributed with SAMsrcV5 for both Desikan and Destrieux parcellations. The user may copy these files and comment out ROIs that are of no interest using the # character.

Unconstrained

 Unconstrained

Only applicable to roi_wts. Instead of using surface normals generated by FreeSurfer, when Unconstrained is specified, the dipole moment is calculated the usual way using the OrientBand covariance.

Frequency Specification

CovBand

 CovBand LO HI

Passband frequencies (in Hz) for filtering the data prior to computing the covariance matrices. A wide bandwidth covariance (much wider than ImageBand) is useful when analyzing MEG data that has very large artifacts, due to tDCS, tACS, or VNS. In such cases, a wide bandwidth will improve rejection of interference by including interference in the beamformer coefficient computations.

ImageBand

 ImageBand LO HI

Passband frequencies (in Hz) for SAM imaging. In instances where you may want to use a wider bandwidth for calculation of the covariance matrix to improve rejection of interference, you can still calculate your desired image metric with a more narrow bandwidth.

OrientBand

 OrientBand LO HI

A separate covariance matrix, using all data samples is used for estimating the dipole orientation in the two-step scalar SAM beamformer. If OrientBand is present, the data are filtered to this passband prior to computing the Orient.cov file. Otherwise, the Orient.cov file will be identical to Global.cov. This option allows the user to optimize the source orientation by specifying a passband where signal-to-noise is high (such as beta). As a first principle, the source orientation is assumed to be stationary, which is why all data samples are used. For example:

NoiseBand

 NoiseBand LO HI

The default method of determining mean sensor noise is finding the rank where the first derivative is at a minimum in the covariance eigenvalue spectrum; this yields only a mean noise value for all sensors. In practice, however, there may be differences in individual SQUID sensor noise. This factor becomes important when imaging high frequency power (fast ripples, etc.) where signal-to-noise is marginal. The mean sensor noise will result in a non-uniform SAM image magnitude, which may be misleading. To overcome this limitation, the user can specify a NoiseBand passband that extends well above the frequencies of interest where the MEG signal is (presumably) vanishingly small. The product of the noise covariance with the SAM beamformer coefficients will give the best estimate of the actual projected noise for each voxel.

SmoothBand

 SmoothBand LO HI

Required for sam_4d, sam_4dc, sam_ersc, and sam_hfo, The lowpass filter (the HI value) is used to smooth the moment, Hilbert envelope of power, excess kurtosis or RVE time-series prior to saving multiple images for each latency. If LO is non-zero, then the metric is bandpass filtered (a highpass other than zero is not recommended).

Notch

 Notch TRUE|FALSE

Enables/disables notch filtering for power mains frequency and its harmonics. The default notch frequencies are based on 60 Hz power mains. This can be switched to 50 Hz using the Hz parameter. The default notch width is 4 Hz (+/- 2 Hz), using a 20th-order FFT filter. Up to 6 notch frequencies are used. Usually this is done by filtering the raw dataset using newDs. Notch filtering is recommended when operating on raw datasets.

FilterType

 FilterType FFT|IIR

Specify use of either an FFT or IIR filter.

Hz

 Hz MAINSFREQ

Used to specify the frequency of electrical mains in the country of origin of the dataset. Defaults to 60Hz, for US recordings.

SAM Parameters

CovType

 CovType Global|SUM|ALL

CovType determines which covariance file(s) and SAM beamformer coefficients will be used in an analysis. GLOBAL selects a covariance matrix based on all dataset samples, without regard to markers or data segments. If NumMarkers is greater than zero, the SAM beamformer coefficients are computed for each marker using the GLOBAL covariance. SUM selects a covariance matrix based on the data corresponding to the designated marker segments. It can only be computed if NumMarkers is greater than zero. The beamformer coefficients are computed from the covariance of the sum over the designated markers. Note that there is a flag, TRUE or FALSE, on the line giving the numbered markers. If TRUE, then that marker’s data segments are included in the computation of the sum covariance. ALL selects independent covariance matrices for each marker. The beamformer coefficients for each marker are computed from the corresponding covariance matrices. Although contrast may be improved by selecting ALL, this may also introduce a bias in the results due to the differences in beamformer coefficients for each marker condition. Note, the CovType parameter does not affect the computation of the covariance matrices or the beamformer coefficients — only which of them is used for the analyses. All are computed by sam_cov.

Model

 Model SingleSphere x y z | MultiSphere | Nolte N

This parameter is used to select the conductive model needed for computation of the forward solution for sam_wts and sam_Nwts There are three available. SingleSphere uses a single homogeneously conducting sphere to approximate the brain (using the Sarvas equation) with the origin specified by the x, y, z coordinates, in centimeters. The MultiSphere model creates a best-fit sphere for each primary sensor. If this model is specified, SAM will look for a compatible default.hdm (or hs_file for 4D/BTi MEG) in the MEG data directory. The Nolte model is a realistic head model. The user can additionally specify N, the desired order for the spherical harmonic expansion of the hull. The default order is 20. Both MultiSphere and Nolte require the hull.shape file located in the participant’s MRI directory or in the MEG dataset.

Mu

 Mu [+|*]MU

This parameter is used to specify the regularization applied, in $fT/{\sqrt {Hz}}$. Prior to the computation of the SAM weights, the diagonal of the covariance matrices may be adjusted. This is a form of “whitening”, since increasing the magnitude of the diagonal of the covariance has the same effect as adding white (uncorrelated) noise to the data. Regularization is used when the MEG data are noisy, or contain linear dependencies that may be introduced by (for example) ICA pre-processing. Regularization is frequently used in connectivity analyses. Regularization will decrease the resolution of the beamformed images. See also regularization

In detail, for additive MU, the specified value is squared, and multiplied by the scaled (to Tesla) bandwidth:

$\mu =10^{-30}*BW*{MU}^{2}$

For the case of multiplicative MU, the specified value multiplies the covariance diagonal directly.

PropMu

 PropMu N

This is another way of specifying regularization. Proportional regularization adds the projected noise floor, multiplied by N, to the diagonal of the covariance matrix. The noise value is derived from the point at which the eigenvalue spectrum of the covariance matrix flattens out.

ImageMetric

The image metric specifies how the raw MEG signal will be transformed to another metric for the final SAM images. Definitions appear below.

 ImageMetric Signal

Specifying the ImageMetric as Signal returns the source moment.

 ImageMetric Power

ImageMetric set to power will give source power as the output units - the method for calculating power varies across individual SAM imaging programs

 Kurtosis

Requests the excess kurtosis (g2) of the signal, this is particularly useful in the detection of occult epileptic spikes.

 RankVectorEntropy TAU DIMS

This specification returns rank vector entropy, with an integrator time constant TAU, in ms, and an embedding space dimension DIMS. Recommended value of DIMS is either 4 or 5.

 SpectEntropy

Specifies spectral entropy as the output metric

 MutualInfo ADVANCE DIMS

Output metric is symbolic mutual information, with a time advance parameter ADVANCE specified in ms, and an embedding space dimension DIMS.

 TransferEntropy ADVANCE DIMS

Output metric is symbolic transfer entropy, with a time advance parameter ADVANCE specified in ms, and an embedding space dimension DIMS.

 ConditionalEntropy TAU ADVANCE DIMS

Computes conditional rank vector entropy, with an integrator time constant TAU (in seconds) ADVANCE (in ms) and embedding space dimension DIMS.

TimeStep

 TimeStep STEP

This defines the time step used in output images. It is used in all SAM programs which return 3D+time images, including sam_ers, sam_ersc, sam_4d, sam_4dc, and sam_power.

TimeInt

 TimeInt INT

This specifies the integration time (in seconds) for smoothing the 3d+time output of sam_4d and sam_ers. It is a required parameter for those programs.

MinSNR

 MinSNR SNRTHRESH

This parameter specifies a minimum SNR for writing a voxel to the output image. This is always an optional parameter, by default all voxels in the ROI or hull are written.

RemoveBaseline

 RemoveBaseline NONE|BYVOXEL|GLOBAL

This parameter is used by sam_power and sam_entropy. By default, no baseline is removed (NONE). If BYVOXEL is specified, the mean value for each voxel over time will be subtracted. If GLOBAL is specified, the mean value is calculated for all non-zero voxels over time and subtracted.

BlockName

  BlockName MARKNAME

This is required only for ste_ers - calculation of transfer entropy. The marker name designates the epochs or blocks to be processed for computation of the covariance matrix and probability distribution functions (PDFs).