Parameter File Man Page (64-bit Version 3)

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.). There is an extensive list of keywords and their parameters that are in use for various SAM analyses. Those wishing to examine the parameters, see: SAMsrcV3/include/Params.h and SAMsrcV3/Libs/SAMLIB GetParams.c. Some of the keywords listed are for features that are under test and not for regular use.

  1. NumMarkers <0 to 6>Required. This keyword defines the number of unique event marker names found in the dataset that are to be used in the analysis. Up to six markers are currently permitted. If no named markers are present, the user must specify zero markers for analyses that are not state dependent. The SAMcov and SAMwts programs, together, read this parameter and parse the dataset for the named markers — generating up to six named SAM beamformer coefficient files plus Global and Sum coefficients.
  2. MarkerN <marker_name start end (s) TRUE | FALSE> — e.g., Marker1 through Marker6. The numbered markers must be sequential and agree with NumMarkers. Each MarkerN keyword requires four arguments: the marker name, the start and end time relative to this marker (seconds) and a flag (TRUE or FALSE) indicating whether this marker is to be included in the "Sum" covariance and beamformer coefficients. For example:
  3. NumMarkers 3
    Marker1 9r0 -0.25 0.25 TRUE
    Marker2 9r1 -0.25 0.25 TRUE
    Marker3 9r2 -0.25 0.25 TRUE

  4. BlockName < epoch marker name >Required for STEers, only. This marker name designates the epochs or blocks to be processed for computation of the covariance matrix and probability distribution functions (PDFs).

  5. FilterType < IIR | FFT >Optional Selects the filtering method - either IIR or FFT. Both the IIR and FFT filters are type Butterworth (flat passband response). The FFT filter has a 20th order response, and yields the sharpest cutoffs. The IIR filter is fastest but cannot generate stabile filters at high sample rates for narrow bandwidths or for frequencies close to the band limits, unless the data are decimated to a lower sample rate. If FilterType is not specified, the default is FFT.
  6. CovBand < highpass lowpass (Hz) >Required. Passband frequencies 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. For example
  7. CovBand 4.0 100.0

  8. ImageBand < highpass lowpass (Hz) >Required. Passband frequencies for SAM imaging. For example:
  9. ImageBand 35.0 45.0

  10. OrientBand < highpass lowpass (Hz) >Optional. 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. As a first principle, the source orientation is assumed to be stationary, which is why all data samples are used. For example:
  11. OrientBand 14.0 30.0

  12. NoiseBand < highpass lowpass (Hz) >Optional. The default method of determining mean sensor noise is finding the rank where the 1st 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. For example:
  13. NoiseBand 900.0 1000.0

  14. SmoothBand < highpass lowpass (Hz) >Required for SAM4dc, SAMersc, and SAMhfo. The lowpass filter 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 highpass is non-zero, then the metric is bandpass filtered (a highpass other than zero is not recommended). For example:
  15. SmoothBand 0.0 15.0

  16. Notch < TRUE | FALSE >Optional. 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 by defining -DMAINS50 in the SAMsrcV3/config/Makefile.site. file. The default notch width is 4 Hz (+/- 2 Hz), using a 20th-order FFT filter. Up to 6 notch frequencies are used. Notch filtering is recommended when operating on raw dataset.
  17. XBounds < start end (cm) >Required for SAMwts - except when using an Atlas or a target list (-t option to SAMwts). In the latter case, the image bounds are determined by the atlas ROI limits. XBounds sets the anterior-posterior ROI dimensions in centimetres, where it is positive in the anterior direction.
  18. YBounds < start end (cm) > — Same as XBounds, except YBounds sets the left-right ROI dimensions, which is positive in the left direction.
  19. ZBounds < start end (cm) > — Same as YBounds, except ZBounds sets the inferior-superior ROI dimensions, which is positive in the superior direction.
  20. ImageStep < step (cm) >Required for all SAM image analyses - except when using an atlas or a target file list. For example, to designate a rectangular ROI on a 5 mm grid:
  21. XBounds -12.0 12.0
    YBounds -9.0 9.0
    ZBounds -2.0 15.0
    ImageStep 0.5

  22. TargetName < target_file_name >Required. Used in place of ROI specifications when analyzing an explicit list of coordinates. The target file is comprised of a list of x, y, and z values (cm) - one set of coordinates per line. The target file is to be placed in the MRI subdirectory for the designated subject, so that it is available for all analyses. The target file can be used for SAMwts, SAMNwts, and STEers.

  23. Interpolate <cm>Optional. Used to obtain averaged SAM coefficients (weights) over a volume, when a coarse grid is used. The weights are computed at +/- the distance specified in the x, y, and z directions for each point in the grid. For example:
  24. XBounds -12.0 12.0
    YBounds -9.0 9.0
    ZBounds -2.0 15.0
    ImageStep 1.0
    Interpolate 0.5

    would compute the weights at 26 points at 5mm distance from the center of each coordinate in a 1 cm grid. The weights are averaged over the 27 points to obtain the final weights for each coordinate.

  25. Atlas < atlas_file_name >Optional. The atlas file determines the coordinates and orientation vector for each neocortical voxel. The atlas is generated by applying FSnormals.py and reduce_surface.py to the subject's segmented MRI, obtained from FreeSurfer. If present, it over-rides the XBounds, YBounds, ZBounds, and ImageStep parameters. The location of the atlas is defined by the concatenation of the MRIdirectory pathname and the subject prefix. Example for patient prefix XYZABC:
  26. MRIDirectory /data2/MRI
    Atlas 3mm.mesh

    This identifies the atlas file: /data2/MRI/XYZABC/3mm.mesh.

  27. CovType < GLOBAL | SUM | ALL >Required. Determines which covariance file(s) and SAM beamformer coefficients are 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 markers 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. Once more, the covType keyword does not affect the computation of the covariance matrices or the beamformer coefficients — only which of them is used for the analyses.
  28. MRIDirectory < pathname >Optional. If present, gives the partial path for the directory containing all MRIs for all subjects. The full path for finding is formed by concatenation The full path for finding items derived from a subject's anatomical MRI is formed by concatenation of the MRIDirectory with a prefix. The prefix defaults to the first 8 characters of the dataset name and should uniquely identify the subject. The full path is used for finding the subject's hull.shape and ortho+tlrc files. The default (if MRIDirectory is absent) for finding hull.shape is the dataset directory. There is no default for ortho+tlrc. If the Talairach transform is applied to the SAM beamformer coefficients, this is a required parameter. Using the MRIDirectory keyword is highly recommended in applications for batch analysis of large numbers of datasets and especially for using AFNI for group statistics. Example:
  29. MRIDirectory /data1/mri

  30. ImageDirectory < pathname >Optional. If present, gives the full path to the directory where the NIFTI image files are written. If absent, the images are written to the SAM subdirectory. This option is highly recommended for batch analysis of large numbers of datasets and for using AFNI for group statistics. For example:
  31. ImageDirectory /data2/SMI/N-Back_Results

  32. Mask < pathname >Optional. Required for Talairach transform of SAM beamformer coefficients. The mask file resolution must agree with the resolution specified in ImageFormat. For example:
  33. ImageFormat TLRC 8.0
    Mask /data2/SMI/Mask8mm.nii

  34. PrefixLength <N>Optional. Default is 8-character prefix (e.g., NIMH hashcode) for identifying subjects. The prefix is parsed from the first N characters of the dataset name. For sites having a different number of characters for identifying datasets and subjects, NumPrefix will specify that character string. The prefix is used to find the subject's MRI and is used in naming the image files generated by the SAM analysis.
  35. ImageFormat < ORTHO | TLRC resolution (mm) >Optional. This parameter controls how the SAM beamformer coefficients (weights) are generated. The default is "ORTHO" in which the weights correspond precisely to the ROI and grid spacing specified by XBounds, YBounds, ZBounds and ImageStep. In version 3 the beamformer weights are written as a NIFTI file. Designating the ImageFormat as "tlrc", will applies the afni program @auto_tlrc to the beamformer weight file, transforming the weights into the common Talairach space. The transform is applied to each SAM coefficient file. The original weight files are retained and the new transformed file names are appended with the "_at.nii". The resolution of the transform is specified in mm. It is recommended that the original ROI grid spacing be smaller than the Talairach grid spacing because the transform uses nearest neighbor to move the ortho grid to Talairach grid. In the following example, an "ortho" ROI grid is designated with a 5 mm spacing from which a "tlrc" spacing of 8 mm is derived:
  36. XBounds -12.0 12.0
    YBounds -9.0 9.0
    ZBounds 0.0 15.0
    ImageStep 0.5
    ImageFormat TLRC 8.0

    Note that if you specify ORTHO, a resolution parameter is still required (and is ignored). The Talairach transform can also be applied to weights derived from an atlas.

  37. Model < model_name >Required. This parameter is used to select the conductive model needed for computation of the forward solution for SAMwts and SAMNwts. The available model name values are:
  38. SingleSphere < x, y, z (cm) > — Single homogeneously conducting sphere (using Sarvas equation) with origin specified by the x, y, z coordinates, in centimetres.

    MultiSphere — Multiple local spheres (one per primary sensor). Looks for compatible default.hdm (or hs_file for 4D/BTi MEG).

    Nolte — Realistic head model (requires hull.shape file located in subject's MRI directory.

  39. Mu < regularization_value >Optional. Used in computing weights (SAMwts, SAMNwts). If the regularization value is preceded by '+' it is interpreted as noise density (units: ft/√Hz) and the band-limited power is computed by squaring the noise density and multiplying by the covariance bandwidth (yielding units of T2). This quantity is added to the diagonal of the covariance matrices prior to computation of SAM weights. If the regularization value is preceded by '*' the diagonal of the covariance matrix is multiplied the this value. For example:

    Mu +2.5
    Mu *5.0

    Augments the covariance diagonal by adding 2.5 fT/root-Hz or multiplying the diagonal by 5.0, respectively. Unless the data are badly corrupted, regularization should be unnecessary.
  40. ImageMetric < measure_to_be_imaged >Required. Denotes the transformation of the MEG signal into another metric. This specifies the voxel units in the image. Choices are:
  41. Signal — source waveform

    Power — source power (may be band-limited power)

    RankVectorEntropy < tau (s) dims > — rank vector entropy, with integrator time constant "tau" (ms) and embedding space dimension "dims" either 4 or 5 in the current implementation

    ConditionalEntropy < tau (s) advance (ms) dims > &8212; conditional rank vector entropy, with integrator time constant "tau" (seconds), advance "advance" (ms) and embedding space dimension "dims" (either 4 or 5 in current implementation)

    Kurtosis — excess kurtosis (g2)

    MutualInformation < advance (ms) dims > — symbolic mutual information, with time advance "tau" (ms) relative to seed voxel and embedding space dimension "dims" either 4 or 5 in the current implementation

    TransferEntropy < advance (ms) dims > — symbolic transfer entropy with time advance "advance" milliseconds and embedding space dimension "dims" either 4 or 5 in current implementation (currently under test)

  42. DataSegment < start end (sec) >Optional. A sufficient number of samples are required to compute a statistically significant covariance matrix. When the number of trials, together with the start and end times of any designated Marker result in a deficiency of samples, the covariance integration window for each trial can be extended using the DataSegment times. This option interacts with SAMcov, where it extends the integration windows, and with several SAM imaging programs where lead-in time is required for computing RVE or power.
  43. Baseline < start end (sec) >Required for SAMers and SAMersc, only. Mean value between start and end relative to Marker1 (and, optionally Marker2) determines baseline of output.
  44. SignSegment < start end (sec) >Optional. The SignSegment designates the time, relative to Marker1 and/or Marker2 for determining the polarity of the SAMers or SAMersc images. The mean value of averaged source activity within the SignSegment determines the sign of each voxel. This parameter can be used to resolve the ambiguity in the polarity of the SAM beamformer.
  45. Transform < transform_file_name >Optional. For Use with Atlas. The transform defines a translation and rotation to be applied to the Atlas, in order to improve the fit to the true frame of reference. This parameter is currently experimental.
  46. TimeStep < sec >Required for SAM4d, SAM4dc, SAMers, SAMersc, etc. This defines the output time sample interval for all 3D+time analyses. Each time step is a full 3D image for that latency.
  47. TimeInt < sec > Integration time required for smoothing the 3D+time outputs of non-continuous analyses (SAM4d, and SAMers).
  48. RemoveBaseline < method >Optional. For SAMpower and SAMentropy, only.
  49. NONE — no baseline removal (default)

    BYVOXEL — subtract mean value determined for each individual voxel over time.

    GLOBAL — subtract mean value determined for all non-zero voxels over time.