View source for Sam 4d and sam 4dc

[[Source Localization - SAM | Return to Source Localization - SAM]]

==Description==

The sam_4d and sam_4dc routines are extensions of the sam_3d and sam_3dc routines, extended to the time dimension sam_4d and sam_4dc compute temporo-dynamic (3D+time) event-related functions of source moment, power, or rank vector entropy, from multiple trial MEG, relative to one or more named markers. This program assumes that beamformer coefficients have been estimated using sam_wts. Weight files from roi_wts, patch_wts, or sam_Nwts can also be used, although the result will not be an image in the traditional sense.

Two versions of this program — sam_4d and sam_4dc are offered. They differ in the order in which the functions of moment, power, or RVE are parsed. The “c” in sam_4dc denotes a “continuous” analysis, as will be explained.

sam_4d first applies the beamformer coefficients to the filtered MEG data (using ImageBand) to compute the source time series for each marked trial (the start and end times relative to each named marker). Next, the timeseries of the metric function (source moment, Hilbert envelope of power, or rank vector entropy) is computed for each trial. A boxcar integrator (designated by the parameter TimeInt) is applied to resample the metric time-series at the sample rate indicated by the TimeStep parameter. The mean and variance at each sample latency (for each marker and voxel) is computed and written to their respective 3D+time NIFTI image files. If, for example, there were three named markers, the output will be six NIFTI image files — a mean and variance file for each marker.

By contrast, sam_4dc applies the beamformer weights to the filtered MEG data over the entire time series — without respect to epochs or markers. The metric function (source moment, Hilbert envelope of power, or rank vector entropy) is then computed continuously over the entire time series and lowpass filtered using an anti-aliasing (smoothing filter) before resampling to the rate indicated by the TimeStep parameter. The resulting metric time series for every voxel is then parsed into trials and the mean and variance accumulated over all trials for each marker and then written to their respective image files.

The problem that arises for sam_4d is that the functions of power and especially RVE are biased by their being computed over the segments of each trial. Short time segments add uncertainties to these measures. To reduce this bias, sam_4dc computes power and entropy over the entire dataset time series, for every voxel. This makes sam_4d faster than sam_4dc. Nonetheless, it is strongly recommended that sam_4dc is used in the analysis.

==Usage==

  sam_4d -r <dataset_name> -m <parameter_file_name> [options]
  sam_4dc -r <dataset_name> -m <parameter_file_name> [options]

The -r flag designates the dataset name (with or without the .ds suffix), and -m designates the parameter file name.

Other options:

  -v  Verbose mode, without this flag sam_wts works silently except for error messages
  -h  Show help

Required Parameters:

  CovBand: Bandpass for the covariance matrices (and directory for weights files)
  ImageBand: Bandpass for the image
  ImageMetric: Can be MOMENT, POWER, or RVE
  TimeStep: designates the sampling interval for the output timeseries
  TimInt: designates the duration for the boxcar integration 
  SmoothBand: designates the anti-aliasing lowpass filter
  NumMarkers: Number of markers used in the analysis
  MarkerN: Marker specification details
  CovType: Which covariance/weights are used for the image

It is important to note that when using sam_4d, GLOBAL, SUM, or ALL can be chosen for CovType. However, use of the ALL beamformer weights may introduce unwanted bias because they are derived from the covariance of short data segments. Because sam_4dc computes the power continuously across the entire dataset, only the SUM or GLOBAL options are allowed for CovType.

  ImageFormat: Designates whether the weights are in +orig or +tlrc space
  ImageDirectory: Directory where the output images are written, default is the SAM directory
  PrefixLength: Number of characters in the MEG dataset name used for naming MRI files.

==Output Files==

For each named marker, sam_4d and sam_4dc will compute two 3d+time NIFTI images for the mean and variance across trials