Skip to content

HOME

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

prf-Validation Framework User Guide

How to install

Requirements

  • Docker must be installed
  • A text editor (e.g., emacs, vim) to edit the configuration json files.
  • Select a base directory variable ($basedir) must be set. For bash or zsh or csh we suggest:
mkdir /Users/myusername/testFolder
export basedir=/Users/myusername/testFolder
cd $basedir

Install docker containers

To run this example you will need to use install prf-Synthesize, prf-Analyze-vista, and prf-Report. You can use the commands below. There are additional analyze Docker containers listed below as well.

  • prf-Synthesize: docker pull garikoitz/prfsynth
  • prf-Analyze:
    • prf-Analyze-vista: docker pull garikoitz/prfanalyze-vista
    • prf-Analyze-afni: docker pull garikoitz/prfanalyze-afni
    • 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: An example

prf-Synthesize

The prf-Synthesize requires a JSON parameter file that specifies the parameters and the name of the BIDS directory where the the synthetic functional data will be written ($basedir).

  1. To create the JSON parameter file and initialize the BIDS directory, run this command:
docker run --rm -it \
        -v empty:/flywheel/v0/input/config.json \
        -v $basedir:/flywheel/v0/output \
        garikoitz/prfsynth

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

  1. 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 your text editor to change the subject name and the session name in the config file. For this example, change the subjectName and sessionName fields to be

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

You can control synthesize parameters (instructions), and this way perform many experiments. Just changing the subject name and session name is enough for this example.

  1. Execute the pRF synthesis 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

Docker container creates a folder called BIDS. Inside this folder, the files are organized comply with the BIDS format. The directory tree will look like:

The synthesized functional 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 additional files.

prf-Analyze

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

  1. First create the configuration JSON file
docker run --rm -it \
      -v $basedir/empty:/flywheel/v0/input:ro  \
      -v $basedir:/flywheel/v0/output  \
         garikoitz/prfanalyze-vista:latest
  1. Rename and edit the configuration JSON file
mv $basedir/prfanalyze-vista-default-config.json $basedir/prfanalyze-vista-config_sub-001_sess-20200320.json

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

Each analysis tool has many optional parameters. 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 for the prf-analysis, in this case for vista
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 prints 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. Some mat-files appear, but you can ignore them. See this page for a more detailed description of the output.

prf-Report

We assume you have pulled the prfreport Docker container (see the top of this page).

  1. Run the prfreport container to initialize its configuration JSON 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 an equivalent JSON file. In this example, only the synthetic parameters and the solved vista parameters will be in the results table. The table should look like this:

By default one plot will saved in the output. In this example, only one pane showing the ground truth values in a dashed blue line, and the fits in grey. By default, the plots will be saved with the .png format. All the formats implemented in Matlab's saveas() function are allowed, for example 'svg' for vectorial images or 'tiff'. See the full reference in the documentation. This is how the plot should look like:

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 "analyze" slot in the configuration file to indicate that you have two analyses to report. In this case the field would read:

"analyze":[{"Type":"vista"},{"Type":"aprf"}],

The plot will show the results from different tools separately. If aprf is added to the analysis, there will be two panes in the figure.

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 a step by step guide here.

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. Otherwise the code will run in the same way.

Clone this wiki locally