4. Usage - Stereo-Boy/Pipeline_AS GitHub Wiki

You can find a lot of general help about mrVista in the Wandell lab wiki and in the Winaver lab wiki.

Folder structure and parameter file [necessary for all steps]

  • Create a subject folder and an analysis folder in it.
  • In the analysis folder, place a parameterFile.m. This file allows you to specify your folder structure, state expected numbers (# of images, runs, TR...) and provide a set of options. You can find a template of that file in the configuration folder (parameterFile_template_retino.m). See the latter section to understand how to adapt the parameter file to your needs.
  • Note that we often (wrongly) refer to the high-resolution anatomical volume as mprage and to the low-resolution inplane anatomical volume as gems. We also refer to the functionals scans as epis, regardless of whether they actually involve echo-planar imaging.
  • Depending on whether you start with a set of DICOM or nifti files, see below.

pipeline_JAS

  • The pipeline main function is called pipeline_JAS (in Modules folder).

  • Run:

          pipeline_JAS(stepList2run, subj_dir, subjID, notes_dir)

with stepList2run the numbers of the steps that you want to run, subj_dir the subject folder, subjID the label of the subject, notes_dir an optional folder where to store dated logs of the command windows

  • I recommend to use the step in the order we give to avoid issues but steps can be run independently.
  • Important: if you re-run a step, it will delete the previous version of that step, to avoid conflicts.

Step 1: nifti conversion of anatomical volume

This module converts the dicom files of your anatomical volume to nifti format using dcm2niix from MRIcroGL.

  • Create a folder for the anatomical volume (for example 01_Raw_DICOM - the name should match o.mpr_dicom_dir in the parameter file). Place also a folder in it and call it mprage. Copy the dicoms of the anatomical in it.
  • Be sure to input the number of volume slices that you expect in variable o.mprageSliceNb in the parameter file.

Important: o.mpr_slice_duration should be let to 0 to avoid issues.

  • Run:

             pipeline_JAS(1, subj_dir, subjID)

  • You should find the nifti files in the folder o.mpr_ni_dir defined in the parameterFile.

Step 2: segmentation of anatomical volume

The step categorizes some of the voxels in the anatomical volume as white matter and other as gray or CSF using Freesurfer. This is a long step that can take up to 24h.

  • It looks for nifti files in o.mpr_ni_dir (defined in parameterFile).

  • Run:

             pipeline_JAS(2, subj_dir, subjID)

  • It yields a categorization file (class file) and a precious nu file (an intensity-normalized isometric 256x256 anatomical nifti file). Those files arrive in o.mpr_segm_dir (defined in parameterFile).

Step 3: correction of gray mesh irregularities

This is a manual step using itkGray. We only provide a link to this tutorial for that step. The goal is to visualize and correct the irregularities of the cortical mesh that can occur during the segmentation process.

  • The pipeline expects that you drop the edited class file in the folder o.mpr_segm_dir (defined in parameterFile). It is important the name of the file contains the word edited.

  • Run:

             pipeline_JAS(3, subj_dir, subjID)

  • In the parameter file, if o.itkgray_skip = 0; the pipeline will stop to let you to drop the edited file manually: this is a safeguard. If o.itkgray_skip = 1; it will take the non-edited class file and rename it 'edited' and pretend it was edited for the next steps.

Step 4: nifti header repair of anatomical image

The header of the nifti files are expected to be formatted in a specific way in mrVista. This step fixes the header. Specifically, there are missing fields let by conversion which generates warnings later and this is mostly annoying. It does not seem to affect any of the results though.

  • The expected folder for the nifti file to correct is o.mpr_ni_dir (defined in parameterFile). You cannot really skip that step anymore with parameter o.nifti_fix_skip = 1 (in parameterFile). If you want to modify the code to make it possible again, you may define o.mpr_niFixed_dir = o.mpr_ni_dir; in the parameter file to avoid issues.

  • Run:

             pipeline_JAS(4, subj_dir, subjID)

  • The corrected files are going to o.mpr_niFixed_dir (defined in parameterFile) along with a file 'headers_FIXED.txt'.

Step 5: nifti conversion of retinotopy epi/inplane and removal of ''pRF dummy'' frames

This module converts the dicom files of your functionals retinotopic epis and the inplane anatomical (same resolution and prescription as the epis) to 4D nifti format using dcm2niix from MRIcroGL. It also removes frames that the pRF analysis will consider dummy.

  • In the analysis folder, create a folder for the epi (called 01_Raw_epi_DICOM for example - the name should match o.ret_dicom_dir in the parameter file). Place each epi folder in it (one for each run) and rename the folders as “epi01_whatever”, “epi02_”...
  • Place also the inplane anatomical in that folder as “gems_whatever”.
  • If you plan to use the pipeline to run a GLM (or similar) with mrVista (rather than retinotopy analysis), also create a folder called 01_PAR and put in that folder your paradigm .par files for each epi, in the same order than your epis. Look at the section for PAR files in the Wandell and Winaver wikis.
  • Be sure that the following parameters in the parameter file is what you expect:
    • o.retinoEpiNb - the nb of retinotopic epis you provided for analysis
    • o.retinoEpiTRNb - the nb of TR (volume images) in each retinotopic epis
    • o.pRFdummyFramesNb - the nb of dummy frames to remove
    • o.retinoGemsSliceNb - the nb of slices in the inplane volume

Important: o.retinoGems_slice_duration should be let to 0 to avoid issues.

  • Run:

          pipeline_JAS(5, subj_dir, subjID)

  • You should find the nifti files in the folder o.ret_ni_dir defined in the parameterFile.

Step 6: motion correction of retinotopy epi/inplane

We use McFLIRT from FSL to motion-correct the epis to a reference.

  • Choose the reference to use in the parameter file (we recommend option 3) with parameter o.reference whose values can be:

              1. the inplane downsampled at epi resolution is used as a reference
          2. the inplane at its original resolution is used as a reference. Epis will be upsampled to gems resolution
          3. The first TR of the first epi is used as a reference, leaving the inplane uncorrected
          4. The first TR of the first epi is used as a reference, and the inplane is aligned to it
          5. The middle TR of the first epi is used as a reference, leaving the inplane uncorrected

  • Be sure to have the epi and inplane nifti files in o.ret_ni_dir (defined in parameterFile).

  • Run:

             pipeline_JAS(6, subj_dir, subjID)

  • Motion-corrected files are produced in o.ret_mc_dir (defined in parameterFile) with keyword mc in the name.

Step 7: MC parameter check and artefact removal [this step is still in developement]

We run an FSL code trying to detect the likely frames with motion-related artefacts so that you can visualize them and correct them. It will show you a list of run/TR that are suspicious and that you may want to check manually. Alternately, we have a function called check_outliers (in Tools folder) that you could try to use to visualize each item on the list and to replace artefactual TR with the mean of the same TR in all other runs. Motion_parameters can be used too.

Step 8: nifti header repair of retinotopy epi/inplane

This is like step 4 but applied to inplane and epi files.

  • Be sure to have the epi and inplane nifti files in o.ret_ni_dir (defined in parameterFile) and the expected TR in o.retinoEpi_slice_duration.

  • Run:

             pipeline_JAS(8, subj_dir, subjID)

  • The fixed files are going to o.ret_mcFixed_dir (defined in parameterFile) along with a file 'headers_FIXED.txt'.

Step 9: initialization of a new mrVista session

The center of mrVista is the mrVista session, made of several core files in a folder (like mrSESSION.mat). You need it to run mrVista command in that folder and start a GUI.

  • It expects motion corrected epis and inplane with fixed headers in o.ret_mcFixed_dir (defined in parameterFile) and a nu file with fixed header in o.ret_mr_dir (defined in parameterFile).

  • Run:

             pipeline_JAS(9, subj_dir, subjID)

  • It will create the mrVista session in folder o.ret_mr_ni_dir (defined in parameterFile) with a folder o.ret_mr_ni_dir (defined in parameterFile) that contains all the nifti files.

Step 10: registration of inplane and volume in the mrVista session

mrVista want to know the transformation necessary to align the inplane to the volume. Once it knows it, it neatly keep it in mind and applies it only last minute, which avoids loosing signal during transformations. The alignment process (called registration) uses a series of automated steps from spm and mrVista (you can use FSL too). It often fails so see later for manual instructions.

  • It needs an mrVista session in folder o.ret_mr_ni_dir (defined in parameterFile) with populated nifti files in folder o.ret_mr_ni_dir.

  • You can choose which algorithm to try for that step in o.align_steps (defined in parameterFile). Default is all 5 following steps:

          1. run fsl brain extraction
      2. run mrvista coarse alignment (spm_coreg)
      3. run mrvista fine alignment 
      4. run mrvista Nestares fine alignment
      5. save alignment matrix to mrSESSION.mat

  • Run:

          pipeline_JAS(10, subj_dir, subjID)

  • It will save the alignment matrix in the mrSESSION.mat.

  • If it fails, follow below steps:

    • we recommend to start rxAlign in the mrVista session folder and to first align grossly
    • The goal is to set up prescribed (interpolated volume) slice window to be identical to the reference slice (inplane) window through all the slices (use rx slice slider to navigate between them)
    • start by flipping the brain with checkbox to get the correct orientations
    • use large steps by clicking on the white part of the sliders: use rotations and translations.
    • important: be sure to check that your vitE caps in on the same side, otherwise left-right may be inverted (and automatic alignment may fail) - if you don't have a caps or if you are doing a retinotopic scan, then use the shape of the skull (often asymetric).
    • save results in control window (save>xform settings - do often and whenever you make significant changes). Stored alignments cannot be retrieved if you exit out of matlab or matlab crashes! You need to use File>save>xForm Setting to be able to retrieve it later.
    • once you have a gross alignment in the GUI, do Alignment > Fine > Nestares code
    • run the Nestares code several times
    • When is it aligned enough? It depends. Check visually using Window>Open Rx/Ref comparison window. A correlation >0.80 is good from my experience.
    • save the rx as the mrVista alignment: to make an alignment available for the mrVista session, you need to do File>save>mrVista alignment. It stores it in mrSESSION.alignment.

  • if it keeps failing, consider using the Winawer lab / KNK alignment procedure. Find help here. There is a function running the procedure in version_AS folder, called s_alignInplaneToAnatomical.m. You will need to download in a folder called KNK the knkutils and the alignvolumedata. You will also need to add KNK to your path.

Step 11: Installing segmentation in the mrVista session

This is a simple step in which we indicate where are the segmented and anatomical nu files to mrVista.

  • Be sure that you have defined o.ret_mr_dir (mrVista session folder), o.mpr_segm_dir (where are the class file is), o.ret_mr_ni_dir (where the nu file is) in the parameter file.

  • Run:

          pipeline_JAS(11, subj_dir, subjID)

  • If you are asked for options in a GUI, keep it to default values, which should be:

Step 12: mesh creation and smoothing in the mrVista session

The goal is to localize on the gray matter a set of nodes to create a mesh that can be later unfolded. At the same time, the mesh is inflated (=smoothed) for an easier visualization.

  • Be sure that you have defined o.ret_mr_dir (mrVista session folder), o.mpr_segm_dir (where are the class file is), o.smoothingIterations (the nb of smoothing operations you ask for - the more the smoother), and o.ret_mr_mesh_dir (where to store the mesh file) in the parameter file.

  • Run:

          pipeline_JAS(12, subj_dir, subjID)

  • Allow incoming connections if asked.

  • In o.ret_mr_mesh_dir, you will find 4 files, one pair for each hemisphere (lh -rh). The uninflated is called pial and the inflated is called inflated.

Step 13: Estimation of the pRF model

This will create an average of the retinotopic epi runs as a dataTYPES in mrVista and then estimate for each voxel the most likely visual receptive field, defined as 3 (gaussian filter) parameters: the eccentricity of the filter center relative to the fovea, the polar angle of the vector fovea - filter center, the size of the filter (std). This is a long step that can take up to 12h.

  • Be sure that you have defined o.ret_mr_dir (mrVista session folder), o.ret_mr_ni_dir (where are the nifti files are in the session) and fully populated o.analysis (all the parameters for the pRF model calculation) in the parameter file.

  • Run:

          pipeline_JAS(13, subj_dir, subjID)

  • The model is stored in the mrVista session folder, in Gray/Averages/. There are a few files and the full one contains the word fFit.

Step 14: mesh visualization of pRF values

This step load the pRF model of left hemisphere with the polar angle as the visualized parameter, open an mrm server, open the left inflated mesh and project the pRF parameters on it.

  • Be sure that you have defined o.ret_mr_dir (mrVista session folder), the lh and rh inflated files in o.ret_mr_mesh_dir and the pRF "fFit" model file in Gray/Averages/.

  • Run:

          pipeline_JAS(14, subj_dir, subjID)

  • You will see the model performance in the command window and you should see something like this in the mrm server:

Phase Eccentricity

Step 15 (manual): Create interesting flat patches

Goal is to make a flat patch for drawing ROIs on, defined either on the Gray window or on the inflated mesh window. This is a projection from the gray view, so there is a loss of data. It is obtained by cutting a disk with a specified radius out of the inflated mesh and by projecting it flat. Flat patches are useful to define ROI (for example, from retinotopic functional data) that can be transformed back to the volume anatomy view and transferred to a different set of EPI in another session. As a result, it is only necessary to process that step when you need to easily define a ROI (although ROI can be defined otherwise from any other view). You can see below how to do this from the gray window, or from the inflated mesh.

Define and install a flat patch from the inflated mesh window

  • Load a mesh in the mesh server (in Gray window>gray>surface mesh>load and display, then select your desired inflated mesh file in mesh folder).
  • Select your ROI: press d to enter (or exit) draw mode, then click to define a polygon that will be the center of the ROI. Close the polygon with c (only in draw mode) and fill the polygon with f (only in draw mode), clicking inside it.
  • Retrieve the mesh ROI: Gray>Mesh ROI>Get ROI from mesh (drawn with 'd' key, all layers). Then, select Gray>Flat Patch>Create Flat Path from Center of Current ROI.
    • if asked, specify the coords.mat file (in volume) and the nifti-header-fixed t1_class_edited.nii.gz file (in segmentation folder)
    • Keep 60mm default radius
    • Select the correct hemisphere (?although it does not seem to change anything if you do not?)
    • Specify name of output files: by convention - location_unfolded_lh/rh. Careful: click the browse button instead of writing directly in the box - do not put in a Flat folder.
    • Hit Go and close after you see ****** End mrFlatMesh in matlab command window (prompt may appear earlier with the words “Done finding nearest mesh” but it may still be running and it sometimes looks like it crashed although it did not).
    • result image files are not important
  • Install the flat patch
    • you need to have the flat patch files for the two hemispheres in order to install them without error
    • In gray windows, Gray>Flat Patch>install new unfold
    • Specify the Flat folder (call it Flat, or something else if it exists, say yes to warnings)
    • Specify the location of the unfolded flat patch file for each hemisphere
    • check that everything is alright: window>open Flat window, you should get no error and something on the window, for left and right hemispheres (toggle button at the bottom)

Step 16 (manual): project a pRF model on a flat patch

  • Open gray window
  • Change dataType from Original to Averages in Flat window
  • Load retino model (File -> Retinotopy Model -> Select and Load Model)
  • Open flat patch from volume window (Window -> Open Flat Window)
  • Transform retinotopy model toward the Flat window (Flat window -> Xform -> Retinotopic Model)