-
Notifications
You must be signed in to change notification settings - Fork 142
Initialization
mrVista organizes data into directories according to sessions and then individual scans within the session. This page describes how fMRI data for a session (say an evening's scan) are initialized into the directory and file formats used by mrVista.
The Initialization process is the procedure by which functional and (usually) anatomical images are read in from the raw format produced by the MRI scanner, and converted into the mrVista structure. During this process, the mrSESSION.mat file, the Inplane/ directory, and the Inplane/Original data type are created.
The first step is to create a data directory and put your session data in it, including the inplane anatomy and functional runs.
Variables (data-structures) that contain information about the session will be stored in the mrSESSION file in the root of the data directory. The data themselves, including time series, regions of interest, and other key data sets are organized into directories within the root directory. These directories are separated into the different types of visualizations (inplane, gray view, flat view) of the data.
mrInit can be used either interactively -- as a wizard, like mrInitRet -- or from the command line. In either case, you'll want to have the following basic input files:
- a series of functional image files
- an Inplane anatomical file
To use mrInit interactively, cd to the session you want to initialize and type
mrInit
You will be presented with the main GUI dialog:
This dialog allows you to specify which input files to use for the new session, as well as what additional initialization parameters you wish to set.
There are several buttons next to the list of functional input files. The "add" button provides a dialog to locate a single, 4-D image file (NIFTI).
The set of input files will correspond to the scans in the 'Original' data type in the new session. The "Move up" and "Move down" buttons let you move each entry earlier or later in the scan order. For Lucas P-mags, the code by default will read the headers and sort by the time acquired.
In addition to these input files, you can specify the volume anatomy (will check for the path 3DAnatomy/t1.nii.gz), as well as which other parameters you want to set. You can add descriptions to the session and individual scans, set analysis parameters for later analyses, and select different preprocessing options such as motion compensation, slice timing correction and GLM analyses.
mrInit Session Description Dialog
The session description dialog allows you to enter a scan description (which will be stored in mrSESSION.description), and descriptions for each scan (dataTYPES.scanParams.annotation), as well as more lengthy comments about the session (stored in mrSESSION.comments).
Cropping data is no longer enabled.
mrInit Analysis Parameters Dialog
This dialog allows you to set parameters for two of the more commonly-performed analyses -- Traveling-Wave / Coherence Analyses and GLM Analyses -- for each scan.
These parameters can also be set later, from within mrVista. But it may be more convenient to do it at the beginning, especially if you want to have mrInit go ahead and run some of these analyses once the data are initialized.
To use the dialog, first select scans for which you want to assign parameters in the left-hand listbox. You can select multiple scans by holding down shift (contiguous sets of scans) or control (pick and choose scans). Then select one of the buttons on the right hand side. Each of the buttons will provide a prompt to set certain parameters. Those parameters will then be applied to each of the selected scans.
If you select Assign Coherence Parameters, you will be assigning parameters for a traveling-wave / coherence analysis, commonly used to analyze retinotopic mapping scans and certain A/B/A/B alternating block-design scans. The key parameter to set here is the number of cycles: this should match the stimulus frequency (either the number of cycles the stimulus traversed in a scan, or the number of A/B block alternations in a scan). These parameters will be stored in the mrSESSION.mat file in the variable dataTYPES.blockedAnalysisParams.
The remaining buttons apply to General Linear Model analyses. They will be stored in the mrSESSION.mat file in the variable dataTYPES.eventAnalysisParams.
Assign GLM Params will assign the GLM and Event-Related Analysis Parameters for the assigned scans.
If you select Assign Parfiles, you will get a prompt to assign a set of .par "paradigm" files for each scan. These are text files which describe the experimental paradigm / design matrix of your analysis for each scan, and are described in detail on the GLM page.
Similarly, if you select Assign Parfile Pattern, you will be able to assign a range of parfiles for each scan, according to a sequence of integer numbers. For instance, suppose you ran your experiment in reverse order: scan 1 is stimulus 10, scan 2 is stimulus 9, and so on to scan 10/stimulus 1. Suppose the corresponding .par files are name stim1.par through stim10.par You would first enter the pattern, as if you were using a MATLAB sprintf-style command: stim%i.par . Then you would enter the range 10:-1:1 .
The key information is stored in two data-structure variables (named mrSESSION and dataTYPES) saved in the file mrSESSION.mat. The structure of the variables in the mrSESSION file is described on its own page. The mrSESSION file also contains a third variable, vANATOMYPATH, that is used find the T1 anatomical associated with that data set.
For analyzing functional data from a scanner, mrVista requires an Inplane directory, which contains scanner data in the Inplane format.
The mrVista directories
The directories are organized by the view, such as mySession/Inplane or mySession/Gray. Each directory contains all data related to the given session stored in the relevant view.
Initially, the Inplane directory has data oriented according to the functional data files. After aligning the inplane data to a volume, Volume and Gray directories have data re-oriented to the reference anatomy; and the Flat directory has data projected onto a flattened 2D representation of a gray matter patch.
Each view directory has subdirectories for different data types, as well as an ROIs directory to save regions of interest. At first, only an 'Original' data type is created, referring to the Original data returned from the scanner in the Raw files. This subdirectory (e.g., mySession/Inplane/Original) contains all time series and analysis files related to this data type, including parameter maps and traveling wave analyses, and population receptive field models. The function dataDir will return this directory; e.g., savePath = dataDir(INPLANE{1}) will return the data directory for the selected data type for the INPLANE view.
After assigning .par files for each scan, the updated assignments will be shown in the parfile listbox to the right of the scans listbox.
Finally, Group Scans will cause the selected scans to be grouped together. That is, when GLM type analyses are run on the data, the grouped scans will all be considered together in a single analysis. The updated scan groups will be reflected in the scan group listbox in the dialog.
The preprocessing options dialog lets you set a series of data preprocessing and analysis steps which will be done immediately after mrInit finishes saving the new session data. Since some of these steps, such as motion compensation, can take a long time, this can be potentially useful, if you want to leave the initialization process running overnight, for instance.
Currently, the options you can set are to do motion compensation (both between and/or within-scans) on the functional data, perform temporal interpolation on the data to correct for varying slice acquisition times within each temporal frame, run a Traveling Wave Analysis on the preprocessed data, and apply a general linear model to the preprocessed data. Note that the motion compensation steps utilize the rigid-body code originally described in Nestares et al., 2000.
The GUIs provided when you run mrInit from the command line produce a single output, a 'params' struct. This struct is saved when the core part of mrInit begins, so if it crashes, you can retrieve the parameters without re-typing. You can also manually specify the params struct, and run mrInit from the command line:
mrInit(params);
This foregoes the dialogs and runs the core initialization routine automatically.
The params struct can be initialized to default values using the function mrInitDefaultParams. Here is a definition of the fields in the params struct:
- sessionDir: directory of the session to be initialized.
- inplane (*required*): path to inplane anatomy (NIFTI).
- functionals (*required*): cell array of paths to functional scans (NIFTI).
- vAnatomy: if this file is specified and exists, will set the
- sessionCode: name of session. Default: get from directory name.
- subject: subject name. Default: get from inplane header.
- description: description of session. Default: empty.
- parfile: {1 x nScans} list of parfile paths for each scan. These
- coParams: {1 x nScans} cell array of coherence anaysis ("blocked analysis
- glmParams: {1 x nScans} cell array of GLM analysis parameters
- scanGroups: cell array specifying sets of scans to group together
- applyGlm: flag to apply a General Linear Model to each scan group
- applyCorAnal: an array specifying scans to which to apply a coherence
- motionComp: flag to do motion correction. 0: don't do it; 1 do
As of 2013-03-01, there is a new method in the works for mrInit. The difference is that the Inplane/anat.mat file is no longer being written out as 'anat.mat' but instead is stored as a path to a NIFTI file. The same GUI/command line commands may be used as above, however, the necessary files are different (inplane and functional should be NIFTI).
- Change the Matlab directory to where you want the session to be stored. A sample data set can be found in vistadata/functional/mrBOLD_01.
- To set up a new session, use mrInit in the GUI form (just by typing in mrInit) or, by filling out the same inputs as the current process on the command line.
- Once the session has been initialized, mrVista can be called once you are in the directory containing the mrSESSION.
As a result of changes made to the initialization process and released as of 2013-04-01, any sessions initialized prior to that date will need to be converted before they will be opened successfully in the new version of mrVista. Please follow the steps below to migrate your session.
- Navigate to the root folder of a session that needs to be migrated. This is the folder containing the 'mrSESSION.mat' file.
- Inside this folder, run mrInit_sessionMigration from MATLAB.
- Check for a 'Successful Update' message to be printed.
- In the folder, you should now see a backup mrSESSION file for the inplane migration: 'mrSESSION_inplaneMigrationBackup.mat'.
- Once these checks have been completed, your migration is complete and you can now run mrVista as normal.
Sometimes the GUI described above (mrInit) may not work well for a particular set of files, when a simpler, command-line-based approach will work. For instance, here is a very simple way to initialize data from a set of ANALYZE files representing an inplane and 3 functional time series:
ip = mrLoad('inplane.img', 'analyze'); % name of ANALYZE file for inplane
mrSave(ip, 'myMrVistaSession', '1.0anat');
for scan = 1:3
func = mrLoad( sprintf('functional%i.img', scan), 'analyze' ); % load each functional according to a file pattern
mrSave(func, 'myMrVistaSession', '1.0tSeries');
end
If the inplane and functionals end up not being co-registered, or there are no inplanes, the mean functional can be used as an ad-hoc inplane:
func = mrLoad('functional1.img', 'analyze'); % name of hypothetical ANALYZE file for first functional
ip = mrComputeMeanMap(func); % take the mean image over time
mrSave(ip, 'myMrVistaSession', '1.0anat');
for scan = 1:3
func = mrLoad( sprintf('functional%i.img', scan), 'analyze' ); % load each functional according to a file pattern
mrSave(func, 'myMrVistaSession', '1.0tSeries');
end
For some scanners, data are returned as a series of 2-dimensional DICOM images, in which the files need to be concatenated across both slices and time points to form a 4D series of image volumes. To initialize this sort of data, use the following format. In this example, there are 26 slices and 80 time points; each time series is in its own directory (including the inplanes, which are concatenated across slices but not time):
ip = mrReadDicom('Inplane/*.dcm', 3, 26); % [3]=concatenate across 3rd dimension; 26=26 slices
mrSave(ip, 'myMrVistaSession', '1.0anat');
for scan = 1:3
func = mrReadDicom( sprintf('Scan%i/*.dcm', scan) [3 4], [26 80] ); % load each functional according to a file pattern
mrSave(func, 'myMrVistaSession', '1.0tSeries');
end
Finally, some scanners provide DICOM images in which each individual file contains all slices for a given time point, but arranged as a 2-D image montage. For this particular purpose, the function script_convertDicomSession in the repository can serve as a template to convert the whole session. You will need to edit this file, and adjust the parameters at the top of the file, to specify how many scans there are, and how many slices / time points for each scan.
The code examples above will provide a session with Inplane anatomies and time series, but will not crop the data, or do preprocessing, such as motion compensation or slice timing correction. These preprocessing steps can be done afterwards using the Analysis menu. Also, no annotation about what each scan represented, nor analysis parameters for each scan, will be set. These can be added using the Edit | Edit Data Type options in the mrVista window.
Starting mrVista
After you've completed the initialization stage, you're ready to start processing data. You can read about the various processing steps on the mrVista page.
mtInitRet is now deprecated.
The mrVista2 toolbox has some support for reading in MR data in a standard format and saving as a mrVista session. Here is some sample code for how to do this. In this example, a session has a set of functional (4-D) scans in ANALYZE format, named 'scan1.img' through 'scan10.img', and a coregistered anatomical, 'inplane.img'.
anat = mrLoad('inplane.img', 'analyze');
mrSave(anat, pwd, '1.0anat');
for scan = 1:10
func = mrLoad( sprintf('scan%i.img', scan), 'analyze' );
mrSave(func, pwd, '1.0tSeries');
end
Note that this method assumes you've collected anatomies that are coregistered to the functional images. We understand that some SPM sessions only have functionals and a whole-brain 3D anatomy, and rely on the SPM coregistration stage to align the functionals on to the alignments. While we recommend collecting inplane anatomies that lie along the functionals, there are a number of ways to deal with this data.
First, the mean functional image can be saved as a '1.0anat' format file, so that analyses in the Inplane view of mrVista will project data on the mean functional image. The alignment steps described on the Alignment page can be used to coregister the functionals onto the 3D Anatomy. (However, it can be tricky to align the T2*-weighted images onto the T1-weighted anatomy.) Second, the coregistered functionals can be saved as the time series, with the 3D anatomy as the inplanes. In this approach, the Inplane and Volume views will be effectively the same. However, because of the standard way Analyze images store data--(rows, cols, slices) become increasingly (right, anterior, superior)--the Inplane images will look rotated. (The first slice will be the lowest axial, and the front of the brain will be pointing to the right.) Again, these rotations will be fixed after aligning to the Volume anatomy.
Further, the code above applies to the case where the time series from each scan is stored as a single, 4-D ANALYZE file. We also understand SPM may initialize volumes to save a separate ANALYZE image for each time point: e.g., V001.img, V002.img, etc. A separate method can deal with this case. In this example, the V-files for each scan are kept in separate subdirectories bold/002, bold/003, and bold/004:
for scan = 2:4
vfileDir = sprintf('bold/003/V%03.0f.img', scan);
func = mrLoad(vfileDir, 'vfiles');
mrSave(func, pwd, '1.0tSeries');
end
The 'vfiles' flag will cause the mrLoad function to loop across all files in the directory matching V*.img, and concatenate them across time. Note that if you have several series of V-files, corresponding to different data (such as motion corrected or normalized), you will need to keep them in separate directories.
- Vistasoft
- Getting Started
- mrVista Overview
- Anatomy
- Functional MRI
- mrVista
- Retinotopy tutorial
- Population RF methods also prf Model, prf_tutorial, prf tutorial
- Diffusion weighted MRI
- Visualization
- Tractography
- Tutorials
- Software overview