View source for Mut img

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

==Description==

This is an experimental program for calculating mutual information between all voxels in an image, based upon rank vector entropy. First, this program will calculate a symbolic state time series, similar to that initially calculated by [[sam_entropy | sam_entropy]]. The program requires that the user specify the embedding dimension, which must be 4 or 5. Unlike [[sam_entropy | sam_entropy]], however, an ADVANCE parameter can be specified, which governs the number of time samples that the window is advanced in each encoding step. In [[sam_entropy|sam_entropy]], the window is always advanced by one step. Similar to [[sam_entropy|sam_entropy]], the lag between samples in the window is calculated from the sampling rate and the maximum frequency. A surrogate state time series is also created. Following creation of the symbolic state time series, the mutual information between each voxel and all other voxels is calculated. Mutual information is also calculated for the surrogate data. Any value for mutual information is set to zero if it lies below three times the surrogate mutual information. 

==Usage==

  mut_img  -r <dataset_name> -m <parameter_file_name> [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). 

Other options:
  
  -b  read in a previously calculated mutual information matrix
  -v  verbose mode

Note that the -b flag is only useful if for some reason you already have the binary file that gives the mutual information matrix for every voxel with every other voxel, but you do not have this reshaped into a NIFTI format image. 

Required Parameters:

  ImageMetric: Must be MutualInformation with ADVANCE and DIMS set.
  NumMarkers: Must be zero
  CovBand: Bandpass for covariance matrix, also specifies subdirectory for weights
  ImageBand: designates the bandpass for imaging the power
  CovType: must be GLOBAL
  FilterType: Type of filter (FFT vs. IIR) used for bandpass

Optional Parameters:

  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 used for naming MRI and output files.

==Output Files==

For each voxel in the image, the maximum mutual information calculated for that voxel is output in a maxima.txt file in the SAM directory of the dataset. In addition, the entire mutual information matrix (which is a square matrix with dimension equal to the total number of non-zero voxels) is written as a binary file, appended Connections.bin. Finally, a 3D+time NIFTI format image is written, with the time dimension encoding each non-zero voxel. Thus, each sub-brick in the image (to use AFNI-speak) will be the mutual information with a single seed voxel. This will thus be an extremely large image. Don't say we didn't warn you.