Skip to content

HOME

Jump to bottom
Brian Wandell edited this page Mar 29, 2020 · 57 revisions

prf-Validation Framework User Guide

3 Main components of prf-Validation

How to install

Requirements

  • Docker installed in the machine being used to run the analysis.
  • Text editor to edit the configuration json files.
  • Select a base directory, a folder called BIDS will be automatically created here. We will call it basedir. We recommend to create a variable with the full path (Docker requires full paths to be passed), such as:
mkdir /Users/myusername/testFolder
export basedir=/Users/myusername/testFolder
cd $basedir

Install docker containers

To run the example on this page you will need to use docker pull to install prf-Synthesize, prf-Analyze-vista, and prf-Report.

  • prf-Synthesize: docker pull garikoitz/prfsynth
  • prf-Analyze:
    • prf-Analyze-afni: docker pull garikoitz/prfanalyze-afni
    • prf-Analyze-vista: docker pull garikoitz/prfanalyze-vista
    • prf-Analyze-analyzePRF: docker pull garikoitz/prfanalyze-aprf
    • prf-Analyze-popeye: docker pull garikoitz/prfanalyze-popeye
  • prf-Report: docker pull garikoitz/prfreport

prf-Synthesize

The prf-Synthesize container takes two inputs. The first is the name of a JSON parameter file used as input, and the second is the directory where the BIDS directory will be written ($basedir).

  1. The first step of the installation is to create the JSON parameter file and the BIDS directory. You do this by running the following command:
docker run --rm -it \
        -v empty:/flywheel/v0/input/config.json \
        -v $basedir:/flywheel/v0/output \
        garikoitz/prfsynth

This will generate a template file in $basedir, called prfsynth-config-defaults.json.

  1. You should rename the JSON file so that it reflects the current calculations, for example:
mv $basedir/prfsynth-config-defaults.json $basedir/prfsynth_sub-001_sess-20200320.json

Next, use a simple text editor to change the subject name and the session name in the config file. In particular, for this example change the subjectName and sessionName fields to be

"subjectName":"001",
"sessionName":"20200320"

In general, you can change many of the synthesize parameters (instructions). But for this example, just changing the subject name and session name is enough.

  1. Now you can execute the analysis with this command:
docker run --rm -it \
        -v $basedir/prfsynth_sub-001_sess-20200320.json:/flywheel/v0/input/config.json \
        -v $basedir:/flywheel/v0/output \
           garikoitz/prfsynth

After the Docker container finishes the execution, there will be a new folder called BIDS in the output directory. Inside this folder, the 3 main files are organized according the BIDs guidelines. The directory tree will look like:

The directory tree has a number of folders that comply with the BIDS format. The synthesized data are contained in the NIfTI file in the folder sub-001/ses-20200320/func. There are several sidecars in this folder as well. The stimulus is represented in the NIfTI file in the folder stimuli. The file deep in the derivatives directory contains the parameters that are used for each simulated voxel (prf-synthesis can simulate multiple voxels in a single run). As you work through the analysis, the derivatives folder will contain many additional files.

prf-Analyze

There is one Docker container for every tool. The containers need to be installed separately. For this example we assume you have downloaded the prfanalyze-vista (see the top of this page).

The procedure is similar to prfsynth:

  1. Run it empty to obtain the config json
docker run --rm -it \
      -v $basedir/empty:/flywheel/v0/input:ro  \
      -v $basedir:/flywheel/v0/output  \
         garikoitz/prfanalyze-vista:latest
  1. Edit the config json
mv $basedir/prfanalyze-vista-default-config.json $basedir/prfanalyze-vista-config_sub-001_sess-20200320.json

Again, change the subjectName and sessionName as we described earlier.

In addition, each tool has many options that can be set. For this example, you do not need to change any of the settings. But if you wish to explore a tool and its options, you can do so by editing the JSON config file for that tool. This is a link to the instructions for editing the default config json file.

  1. Run the Docker container with the analysis
docker run --rm -it \
      -v $basedir:/flywheel/v0/input \
      -v $basedir:/flywheel/v0/output \
      -v $basedir/prfanalyze-vista-config_sub-001_sess-20200320.json:/flywheel/v0/input/config.json:ro  \
         garikoitz/prfanalyze-vista

The container will print a lot of information to the screen as it runs. When it finishes, you can list the directory tree again. You will see the outputs which are stored in NIfTI files and JSON sidecars in the derivatives folder. Although some mat-files do appear, you can ignore them.

prf-Report

Next, we run the prfreport on the output. We assume you have pulled the prfreport Docker container (see the top of this page).

  1. Run the prfreport container with the 'empty' parameter to obtain the prefreport's config file
docker run --rm -it \
        -v empty:/flywheel/v0/input/config.json \
        -v $basedir:/flywheel/v0/output \
        garikoitz/prfreport
  1. Rename and edit the JSON config file.
mv $basedir/prfreport-configuration-defaults.json $basedir/prfreport-config_sub-001_sess-20200320.json

Again, use your editor to set the subjectName to '001' and the sessionName to '20200320'.

In this case, too, there are many configurable options. This link points to more complete instructions for editing the prfreport default config json file.

  1. Run the Docker container to create the report
docker run --rm -it \
        -v $basedir/prfreport-config_sub-001_sess-20200320.json:/flywheel/v0/input/config.json \
        -v $basedir:/flywheel/v0/output \
        garikoitz/prfreport

The output files will be in the derivatives/prfreport folder. The output is a Matlab .mat file and a equivalent .json file. If "createplots":true was edited, then a .svg file will be in the output as well (the file type can be changed with the option "saveToType":"png", to change it to png, for example).

N.B. prfreport can combine the results from several analyses. To test this feature, run another analysis (for example, using aprf instead of vista). Then edit the "Type" slot in the configuration file to indicate that you have two analyses to report. In this case the field would read: "Type":"vista aprf"

Utility scripts

The Docker command lines are a bit complicated. Rather than typing the docker command every time, we prepared a set of bash scripts in the repository that you can download and run. We find that this reduces the number of 'typos' during the execution. These are

  • PRFmodel/gear/prfsynth/run_prfsynth.sh.
  • PRFmodel/gear/prfanalyze/prfanalyze.sh.
  • PRFmodel/gear/prfreport/run_prfreport.sh.

Instructions for each script can be obtained inline with the following command, such as:

./prfanalyze.sh --help

An example call of the function would look like this:

./prfanalyze.sh vista $basedir $basedir/prfanalyze-vista-config_sub-001_sess-20200320.json

Running the code locally

If you want to run the code locally on your machine (in Matlab), you must clone this repository. You can see examples of how we run the code in the script XXXX.

Singularity

A few sites will not support Docker, but only Singularity. In that case, you can convert the Docker containers to Singularity containers using the method described here XXXX. Otherwise the code will run in the same way.

Clone this wiki locally