Sam cov

Return to Source Localization - SAM

Description

sam_cov reads an MEG dataset and a parameter file (with the .param extension) and outputs multiple covariance files in accord with the contents of the parameter file and a set of internal rules. The parameter file is parsed for the frequency passband(s), time windows and markers (if present). It also allows for generation of an optional noise covariance file for determination of individual sensor noise levels. Beamformer weights are generated from data within the specified covariance bandpass. The covariance files are stored in a subdirectory within the SAM/ directory of the dataset. The subdirectory inherits the name of the parameter file concatenated with the covariance bandpass. For example, if the parameter file is MyTest.param and CovBand is 4–50 Hz, the subdirectory will be named MyTest,4-50Hz. The subdirectory name is not influenced by the ImageBand, OrientBand or NoiseBand frequencies. Assuming a dataset named XYZABC.ds, the covariance files will be written to the directory: XYZABC.ds/SAM/MyTest.4-50Hz. Several covariance files will be saved. The Global.cov file contains a covariance matrix defined from the entire dataset. If there are markers, there will be a covariance file for each marker (named MARKERNAME.cov), and there will be a Sum.cov covariance file which is calculated from the data surrounding all the named markers marked 'TRUE' in the parameter file. SAMcov-Segments defines the start and endpoints in the dataset over which each covariance file was created. Eigenvalue files are also created for each named marker, which give the ranked singular values for the covariance matrix.

Note that sam_cov creates the SAM/ subdirectory if it does not exist.

An optional orientation passband can be specified for use by the sam_wts program. The orientation covariance file should be generated from data in a band where the signal-to-noise ratio is high (such as the beta band). The orientation covariance is computed using all data samples, under the assumption that, for any given voxel, the orientation must be stationary over time.

An optional noise covariance file may also be specified. The passband should be as high as possible, where the MEG signal is vanishingly small. The noise covariance accounts for variations in noise among sensors. This becomes important when attempting to image very high frequency activity where the image may contain artifacts due to variations in sensor noise. Without this, all sensors are assigned the average noise estimated from the covariance eigenvalue spectrum.

note: The version 3 .cov covariance files are not compatible with prior versions of SAMcov. The optional DataSegment time window overrides the active and control time-segments for covariance generation. This option is used when either the active and control time windows are too small to obtain a useful covariance estimate, or when an imaging analysis requires lead-in and -out times such as for entropy analysis.

Usage

 sam_cov -r <dataset_name> -m <parameter_file_name> [-v] [options]

The -r flag is followed by the dataset name (with or without the .ds suffix). The -m flag is followed by the parameter file name (with or without .param). The -v option specifies verbose output, else sam_cov works silently. Many of the parameters are also available on the command line, see the output of sam_cov -h.

The required parameters are:

 NumMarkers: the number of markers or zero
 CovBand: high- and low-pass frequencies (Hz)
 ImageBand: high- and low-pass frequencies (Hz) for subsequent analysis

If NumMarkers is greater than zero, Marker1 through MarkerN should also be specified - see parameter descriptions as well as the examples below.

Optional parameters are:

 OrientBand: high- and low-pass frequencies for determining the beamformer dipole orientation
 NoiseBand: high- and low-pass frequencies for estimating the SQUID sensor noise
 DataSegment: override the start and end times of all the markers

The OrientBand defaults to CovBand if OrientBand is not given. It is suggested that orientation is determined by a frequency band for which the signal-to-noise ratio is highest (beta-band is a good choice). If NoiseBand is specified, it should be far above frequencies where MEG signals are significant.

Output Files

A Global.cov file is always generated, by default, regardless of the number of markers or other parameters.

If NumMarkers is greater than zero, then a covariance file is computed for each named marker. In addition, a Sum.cov covariance file is generated by summing over the time segments for all markers flagged as TRUE. For example, assuming a parameter file containing:

 NumMarkers 3
 Marker1 9r0 -.25 .25 TRUE
 Marker2 9r1 -.25 .25 FALSE
 Marker3 9r2 -.25 .25 TRUE

sam_cov will generate Global.cov, 9r0.cov, 9r1.cov, 9r2.cov, and Sum.cov. The Sum.cov includes only markers that are flagged as TRUE.

An Orient.cov file is always written, using the frequency bandpass specfied by CovBand, unless OrientBand is specified.

If a noise covariance passband is designated in the parameter file, then an additional noise covariance matrix will be computed. Ideally, when the bandwidth is above physiologically plausible brain signal, the Noise.cov covariance file will contain very little MEG brain signal and will be dominated by the primary SQUID sensor noise. When multiplied by the SAM beamformer coefficients, Noise.cov will yield the most accurate estimate of beamformer projected noise for any given voxel. When setting this parameter, be mindful of your sampling rate and the quarter-Nyquist filter automatically imposed by the system.

sam_cov will also output the time segments used for calculating the covariance matrices, as well as eigenvalue spectra. Information on interpreting these files is given in the next section.

Diagnostics

sam_cov computes the eigenvalue spectrum for each covariance file it generates. The average primary sensor noise is estimated from the eigenvalue spectrum at the rank where its 1st-derivative is minimum. The effective rank and noise are printed as a diagnostic if the -v flag is used. sam_cov also computes the ratio of “effective” samples to the number of primary sensors. The effective sample rate is 2x the bandwidth. Poor beamformer performance will result if the ratio of samples to sensors is less than about 3. In practice, a ratio of 10 or more is preferred. If one or more sensors is dead or there has been preprocessing affecting the rank of the measurements (such as ICA), sam_cov will display an error message that the covariance is degenerate. A degenerate covariance matrix will have a least-significant eigenvalue that is much smaller than the true sensor noise. If you know what you are doing, this can be overcome by using a pseudo-inverse (see the Pinv param) and regularization. A text listing of the eigenvalue spectrum for each covariance matrix will be found in the same subdirectory as the covariance files. In addition, the samples parsed for each time segment are found in the SAMcov-Segments file. These files may be useful for diagnosing defective datasets or poorly selected parameters.