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.
- 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.
- 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:
NumMarkers |
3 |
Marker1 |
9r0 |
-0.25 |
0.25 |
TRUE |
Marker2 |
9r1 |
-0.25 |
0.25 |
TRUE |
Marker3 |
9r2 |
-0.25 |
0.25 |
TRUE |
- 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).
- 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.
- 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
- ImageBand < highpass lowpass (Hz) > — Required.
Passband frequencies for SAM imaging. For example:
- 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:
- 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:
- 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:
- 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.
- 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.
- YBounds < start end (cm) > — Same as XBounds, except
YBounds sets the left-right ROI dimensions, which is positive in the left
direction.
- ZBounds < start end (cm) > — Same as YBounds, except
ZBounds sets the inferior-superior ROI dimensions, which is positive in the
superior direction.
- 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:
XBounds |
-12.0 |
12.0 |
YBounds |
-9.0 |
9.0 |
ZBounds |
-2.0 |
15.0 |
ImageStep |
0.5 |
- 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.
- 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:
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.
- 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:
MRIDirectory |
/data2/MRI |
Atlas |
3mm.mesh |
This identifies the atlas file: /data2/MRI/XYZABC/3mm.mesh.
- 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.
- 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:
- 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:
ImageDirectory |
/data2/SMI/N-Back_Results |
- 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:
ImageFormat |
TLRC |
8.0 |
Mask |
/data2/SMI/Mask8mm.nii |
- 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.
- 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:
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.
- 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:
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.
- 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:
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.
- 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:
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)
- 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.
- 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.
- 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.
- 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.
- 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.
- TimeInt < sec > Integration time required for smoothing
the 3D+time outputs of non-continuous analyses
(SAM4d, and
SAMers).
- RemoveBaseline < method > — Optional. For
SAMpower and
SAMentropy, only.
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.