User Tools

Site Tools


biac:matlab:tstatprofile

TSTATPROFILE

TSTATPROFILE is a Matlab function used to calculate statistics on event-related fMRI data and is very similar to the function MRTEST. Like MRTEST, the input to TSTATPROFILE is a control file that includes all parameters for the fMR data as well as the location of relevant input files and folders. TSTATPROFILE will then read this control file and analyze the data without any further user interaction. The most recent version of TSTATPROFILE can be found on the BIAC server Gall. (\\Gall\Programs\User_Scripts\TStatProfile).

Control File

The control file includes all of the imaging parameters and information on data file location that TSTATPROFILE needs in order to run properly. Some parameters and information are required, and others are optional (see a brief description below).

Required Fields

  • XPixels – Number of pixels in the X-plane.
  • YPixels – Number of pixels in the Y-plane.
  • ZPixels – Number of slices.
  • ParadigmColumn – List of the columns in the paradigm file to analyze.
  • PreEventPts – Number of time points in the epoch before the event.
  • PostEventPts – Number of time points in the epoch after the event.
  • Threshhold – Pixel intensity that defines the boundary between background and brain.
  • CorrelationTemplate – File name and path of the hemodynamic response template.
  • OutPath – Path where all output analysis data will be stored.
  • RunName – File name and path of each functional run to be analyzed.
  • Paradigm – File name and path of each paradigm file per run. If each run uses the same paradigm file, this parameter can be entered just once.
  • TimePts – Number of time points per run. If each run has the same number of time points, this parameter can be entered just once.

Optional Fields

  • SubjectNumber – The five-digit study code assigned by the scanner. This is used when naming the average and standard deviation volumes, and if it is not specified, a default filename will be used. (e.g. 41111.av will become grandAvg.img).
  • RunDataType – The input data type to be used by READMR. Default value is ‘volume’.
  • Bins – List of the event-coded “bins” the user wishes to analyze. If unspecified, the function will analyze all bins found in the specified column(s) of the paradigm files.
  • BinsTest – If the user wants to do T-Tests between two different bins, this parameter must be set. For example, to run a T-Test comparing bins 1 and 2, the user would enter: BinsTest = [1,2].
  • Base1 – The time point in the epoch relative to the event onset that defines the start of the baseline. If the baseline starts five time points before the event, the user would enter Base1 = -5. The default value is 0, which represents the same time point as the event onset.
  • Base2 – The time point in the epoch relative to the event onset that defines the end of the baseline. This value cannot be less than Base1, and the default value is 0.
  • FilenameType – Describes how the output files will be named to reflect which bin they represent. FilenameType = Normal will use the integer bin codes to name output files, e.g. Bin01.T. FilenameType = Unique will use unique identifiers described in the paradigm files (see explanation below) or bin/column identifiers to name the output files; e.g. BinRed.T or BinB001C01.T. Default is Normal.
  • Standard – The bin code that represents your standard/regular time points when no “events” occur. This can be specified once for all runs, or per run. Default value is 0.
  • OutFlags - An eleven-element array that specifies which output files (see output file descriptions below) should not be written. A 0 tells the function to write the file, a 1 tells the function not to write the file. This option is used to save disk space. The order of the array is as follows:

[*.av *.sd *.avb *.sdb Avg*.img Var*.img StdDev*.img Zscore*.img *.N *.COR *.T] Default is [0,0,0,0,0,0,0,0,0,0,0], all output files will be written.

Example Control File

  XPixels=64 
  YPixels=64 
  ZPixels=16 
  Bins=1 2 3 4 
  BinsTest=[1 2] 
  ParadigmColumn=1 2 
  PreEventPts=5 
  PostEventPts=9 
  Base1=-5 
  Base2=0 
  FilenameType=Unique 
  Threshhold=300 
  RunDataType=float 
  CorrelationTemplate=\\Server\Data\BIAC\Study.01\Control\weights.txt 
  OutPath=\\Server\Data\BIAC\Study.01\Analysis\49999\ 
  RunName=\\Server\Data\BIAC\Study.01\Data\TRAlign\49999\run01\V*.img 
  Paradigm=\\Server\Data\BIAC\Study.01\Control\Paradigm1.txt 
  Timepts=200 
  RunName=\\Server\Data\BIAC\Study.01\Data\TRAlign\49999\run02\V*.img 
  Paradigm=\\Server\Data\BIAC\Study.01\Control\Paradigm2.txt 
  Timepts=200 

Paradigm File Note

TSTATPROFILE has an additional capability that allows the function to read paradigm files with bin descriptions so that filenames can be understood a little better. For example, say there is a red visual stimulus shown to the subject that is encoded as bin “1”. Normally, any output representing this bin would have the number “1” in its name, e.g. “Bin01.T”. However, if the paradigm file specifies that the bin code “1” represent a red visual stimulus, then TSTATPROFILE can write out the file as “BinRed.T”. To use this option, the FilenameType parameter in the control file must be set to Unique, and the paradigm files must have the bin names defined within.

Example paradigm file:

  binnames = 
    1 red 
    2 blue 
  matrix = 
    0 
    0 
    1 
    0 
    0 
    2 
  etc… 

Usage

  >>  TStatProfile; 
  >>  out = TStatProfile; 
  >>  TStatProfile(controlfname); 
  >>  TStatProfile(flags); 
  >>  TStatProfile(controlfname,flags); 

Inputs

  • If there are no inputs to the function, a file dialog box will open and ask the user to browse and select the particular control file to run.
  • Optional – controlfname. String that describes the location of the control file, which includes the parameters that will be used during processing of MR data. (Example: controlfname = ‘D:\study\controlfiles\controlfile1.txt’;). Used mostly when running batch scripts.
  • Optional – flags. An eleven-element array that specifies which output files (see output file descriptions below) should not be written. The order of the array is as follows:

[*.av *.sd *.avb *.sdb Avg*.img Var*.img StdDev*.img Zscore*.img *.N *.COR *.T]

Outputs

  • Optional – out. A five dimensional array that is the average, baseline subtracted, raw MR volume for each bin per timepoint. Size of the array is:

xSize * ySize * zSize * numTimePts * numBins where xSize, ySize and zSize represent the resolution of the x, y and z dimensions of the image respectively, numTimePts is the number of time points in the epoch, and numBins is the number of bins that the program analyzed, defined in the control file.

  • Log file – A description of every step done during the function. This file is very useful to examine after a run if there is an error to determine what went wrong and when it occurred. The file is saved in the same folder as the control file, and has the same file prefix as the control file and the file extension .log.
  • *.av or grandAvg.img file – The raw MR signal average volume for every time point over all runs.
  • *.sd or grandSd.img – The raw MR signal standard deviation volume for every time point over all runs.
  • *.avb or baselineAvg.img file – The raw MR signal average volume for every time point in the baseline over all runs.
  • *.sdb or baselineSd.img file – The raw MR signal standard deviation volume for every time point in the baseline over all runs.
  • Avg*.img – The average, baseline subtracted, time-series-volume (TSV) for all epochs defined by a specific bin (same as out, if specified).
  • Var*.img – The variance of the baseline subtracted TSVs for all epochs of a specific bin.
  • StdDev*.img – The standard deviation of the baseline subtracted TSVs for all epochs of a specific bin.
  • Zscore*.img – The z-score of the baseline subtracted TSVs for all epochs of a specific bin.
  • *.N – Each voxel in this volume represent the number of events found and analyzed for each bin.
  • *.COR – The correlation map calculated with the hemodynamic response template defined in the control file for all specified bins.
  • *.T – The T map calculated with the correlation map for all specified bins.
biac/matlab/tstatprofile.txt · Last modified: 2014/08/04 16:03 (external edit)