HOME

prf-Validation Framework User Guide

How to install

Requirements

• Docker (or Singularity) 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

• 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

How to run

This instructions are for the Docker version. If you want to run the code interactively in Matlab, git clone this repository and follow this guide.

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.

2. 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 general, you can change many of the synthesize parameters (instructions). But for this example, just changing the subject name and session name is enough.

3. 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.

Instead of using the docker command every time, we prepared a bash script you can download from the repository in PRFmodel/gear/prfsynth/run_prfsynth.sh.

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

2. Edit the config json

mv $basedir/prfanalyze-vista-default-config.json $basedir/prfanalyze-vista-config_sub-001_sess-20200320.json

Here instructions for editing the default config json file.

3. 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.

We provide a bash script to run all prfanalyze tools as well, please download it from PRFmodel/gear/prfanalyze/prfanalyze.sh. The manual for the script can be obtained inline with the following command:

./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

prf-Report

The equivalent procedure applies to prfreport. prfreport can combine the results from several analyses. It plots the result of just one tool, but to illustrate it better, before running prfreport, run another analysis (for example, using aprf instead of vista).

1. Run it empty to obtain the config json

docker run --rm -it \
        -v empty:/flywheel/v0/input/config.json \
        -v $basedir:/flywheel/v0/output \
        garikoitz/prfreport

2. Edit the config json

mv $basedir/prfreport-configuration-defaults.json $basedir/prfreport-config_sub-001_sess-20200320.json

Here instructions for editing the prfreport default config json file. If you want to visualize some output plots, edit the field "createplots":true, and change the field "userfsize":1. 3. Run the Docker container with the analysis

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

Instead of using the docker command every time, we prepared a bash script you can download from the repository in PRFmodel/gear/prfsynth/run_prfreport.sh.

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).