Difference between revisions of "Tunable Parameters"

From MEG Core
Jump to navigation Jump to search
Line 9: Line 9:
 
All parameters appear below. User defined input is given in all capital letters.
 
All parameters appear below. User defined input is given in all capital letters.
   
===DataSet===
+
==DataSet==
 
Specifies the MEG dataset to be analyzed.
 
Specifies the MEG dataset to be analyzed.
   
Parameter File: DataSet DNAME
+
Parameter File: DataSet DNAME
Command Line: -r DNAME
+
Command Line: -r DNAME
   
 
==PDFName==
 
==PDFName==
 
Only used for 4D/BTi datasets, this specifies the additional PDF file.
 
Only used for 4D/BTi datasets, this specifies the additional PDF file.
   
Parameter File: PDFName PDFNAME
+
Parameter File: PDFName PDFNAME
Command Line: -d PDFNAME
+
Command Line: -d PDFNAME
   
 
==NumMarkers==
 
==NumMarkers==
 
N specifies 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 sam_cov and sam_wts 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.
 
N specifies 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 sam_cov and sam_wts 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.
   
Parameter File: NumMarkers N
+
Parameter File: NumMarkers N
   
 
==MarkerN==
 
==MarkerN==
  +
  +
MarkerN MARKNAME T0 T1 TRUE|FALSE
  +
  +
Specify Marker1 through Marker6. The numbered markers must be sequential and agree with NumMarkers. Each MarkerN 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. Markers cannot be specified on the command line. 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
  +
  +
==CovBand==
  +
  +
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.
  +
  +
Parameter File: CovBand LO HI
  +
Command Line: --CovBand LO HI
  +
  +
==ImageBand==
  +
  +
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.
  +
  +
Parameter File: ImageBand LO HI
  +
Command Line: --ImageBand LO HI
  +
  +
==OrientBand==
  +
  +
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:
  +
  +
Parameter File: OrientBand LO HI
  +
Command Line: --OrientBand LO HI
  +
  +
==NoiseBand==
  +
  +
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.
  +
  +
Parameter File: NoiseBand LO HI
  +
Command Line: --NoiseBand LO HI
  +
  +
==SmoothBand==
  +
  +
Required for [[sam_4d | sam_4d]], [[sam_4dc|sam_4dc]], [[sam_ersc|sam_ersc]], and [[sam_hfo|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).
  +
  +
Parameter File: SmoothBand LO HI
  +
Command Line: --SmoothBand LO HI
  +
  +
  +
  +
  +
  +
==BlockName==
  +
  +
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).
  +
  +
Parameter File: BlockName MARKNAME
  +
Command Line: --BlockName MARKNAME

Revision as of 17:30, 1 March 2019

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.

All parameters appear below. User defined input is given in all capital letters.

DataSet

Specifies the MEG dataset to be analyzed.

 Parameter File:    DataSet DNAME
 Command Line:      -r DNAME

PDFName

Only used for 4D/BTi datasets, this specifies the additional PDF file.

 Parameter File:    PDFName PDFNAME
 Command Line:      -d PDFNAME

NumMarkers

N specifies 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 sam_cov and sam_wts 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.

 Parameter File:    NumMarkers N

MarkerN

 MarkerN MARKNAME T0 T1 TRUE|FALSE 

Specify Marker1 through Marker6. The numbered markers must be sequential and agree with NumMarkers. Each MarkerN 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. Markers cannot be specified on the command line. 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

CovBand

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.

 Parameter File:    CovBand LO HI
 Command Line:      --CovBand LO HI

ImageBand

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.

 Parameter File:    ImageBand LO HI
 Command Line:      --ImageBand LO HI

OrientBand

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:

 Parameter File:    OrientBand LO HI
 Command Line:      --OrientBand LO HI

NoiseBand

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.

 Parameter File:    NoiseBand LO HI
 Command Line:      --NoiseBand LO HI

SmoothBand

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).

 Parameter File:    SmoothBand LO HI
 Command Line:      --SmoothBand LO HI



BlockName

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).

 Parameter File:    BlockName MARKNAME
 Command Line:      --BlockName MARKNAME