SAMcov Version 3

Description: SAMcov reads a MEG dataset and a parameter file (*param) 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. 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 and have a suffix of ".cov". The subdirectory inherits the name of the parameter file concatenated with the covariance bandpass. For example, if the parameter file is "MyTest.param" and the 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.

Note that SAMcov creates the SAM subdirectory if none exist.

An optional orientation passband can be specified for use by the SAMwts program. The orientation covariance file should be generated from data in a band where signal-to-noise is high (such as 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 be contain artifacts due to variations in sensor noise. Without this, all sensors are assigned the average noise estimated from the covariance eigenvalue spectrum.

The version 3 ".cov" covariance files are not compatible with prior versions of SAMcov.

The optional DataSegment time window over-rides the active and control time-segments for covariance generation. This option is used when a) the active and control time windows are too small to obtain a useful covariance estimate, or b) when an imaging analysis requires lead-in and -out times such as for entropy analysis.

Usage:

SAMcov -r <dataset_name> -m <parameter_file_name> -v

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 without the .param suffix. The -v argument specifies verbose output — else SAMcov works silently.

The required parameters and keywords are:

If NumMarkers > 0:

The optional parameters are:

The rules are:

  1. A "Global.cov" file is always generated, by default, regardless of the number of markers or other parameters.
  2. If NumMarkers is greater than 0, 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:
  3. NumMarkers 3
    Marker1 9r0 -0.25 0.25 FALSE
    Marker2 9r1 -0.25 0.25 TRUE
    Marker3 9r2 -0.25 0.25 TRUE

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

  4. An "Orient.cov" file is always written tp the same frequency bandpass specfied by CovBand, unless OrientBand is specified.
  5. If a noise covariance file passband is designated in the parameter file, then an additional noise covariance file will be computed. Assuming that a dataset acquired with a DC-1000 Hz:
  6. NoiseBand 900.0 1000.0

    would generate a "Noise.cov" cpvariance file containing very little MEG brain signal and 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.

Diagnostics: SAMcov 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. SAMcov 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 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, SAMcov 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.

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.

Prerequisites: A MEG dataset and parameter file