Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mvdoc/budapest-fmri-data

Quality assurance analyses of fMRI data collected while participants watched The Grand Budapest Hotel by Wes Anderson.
https://github.com/mvdoc/budapest-fmri-data

dataset fmri fmri-dataset grand-budapest-hotel neuroimaging

Last synced: 3 days ago
JSON representation

Quality assurance analyses of fMRI data collected while participants watched The Grand Budapest Hotel by Wes Anderson.

Awesome Lists containing this project

README 

        



[![DOI](https://zenodo.org/badge/251371344.svg)](https://zenodo.org/badge/latestdoi/251371344)



# An fMRI dataset in response to "The Grand Budapest Hotel", a socially-rich, naturalistic movie



This repository contains quality-assurance scripts for an fMRI dataset collected while 25 participants watched [The Grand Budapest Hotel](https://en.wikipedia.org/wiki/The_Grand_Budapest_Hotel) by Wes Anderson. The associated manuscript *An fMRI dataset in response to "The Grand Budapest Hotel", a socially-rich, naturalistic movie* by Matteo Visconti di Oleggio Castello, Vassiki Chauhan, Guo Jiahui, & M. Ida Gobbini is available as a preprint [here](https://www.biorxiv.org/content/10.1101/2020.07.14.203257v1).



The dataset is available on OpenNeuro: https://openneuro.org/datasets/ds003017. See below for information on how to install the dataset. If you use the dataset, please cite the corresponding paper:



> Visconti di Oleggio Castello, M., Chauhan, V., Jiahui, G., & Gobbini, M. I. An fMRI dataset in response to “The Grand Budapest Hotel”, a socially-rich, naturalistic movie. *Sci Data* **7**, 383 (2020). https://doi.org/10.1038/s41597-020-00735-4



This repository and associated code can be cited as follows:



> Visconti di Oleggio Castello, M., Chauhan,  V., Jiahui, G., & Gobbini, M. I. (2020).  *mvdoc/budapest-fmri-data*. Zenodo.  http://doi.org/10.5281/zenodo.3942173



## Cloning this repository and downloading the dataset



To clone this repository, run



```bash

$ git clone https://github.com/mvdoc/budapest-fmri-data.git

```



The OpenNeuro dataset is included in this repository as a git submodule, and it can be downloaded with [DataLad](https://www.datalad.org/) (see also the next section). Once you have cloned the repository, obtaining the data is as simple as



```bash

$ cd budapest-fmri-data

$ datalad install data

# If for example you want to download the data from one subject, you can run

$ datalad get data/sub-sid000005

# Alternatively, to get all the data, you can run

$ datalad get data

```



The dataset can also be installed from [DataLad](https://www.datalad.org/) to a different location by running



```bash

$ datalad install ///labs/gobbini/budapest/openneuro

```



Or it can be downloaded from the [OpenNeuro's website, dataset ds003017]( https://openneuro.org/datasets/ds003017). 



Please refer to the [DataLad handbook](http://handbook.datalad.org/en/latest/) to learn how to use DataLad.



## Setting up a python environment



We provide a conda environment file to set up an appropriate python environment for the preprocessing scripts. This environment has been tested on Linux and Mac OS X, however there's a chance it might not work on your system. Please feel free to open an issue here and we'll try to help.



Assuming you have already installed [anaconda or miniconda](https://docs.anaconda.com/anaconda/install/) on your system, you can set up a new conda environment with requirements as follows (note that it can take a while):



```bash

$ conda env create -f conda-environment.yml --name budapest

```



Once all packages have been installed, you should activate the environment and install an additional python package that we provide which contains additional helper functions:



```bash

$ conda activate budapest

$ pip install ./code

```



## Presentation, preprocessing, and quality assurance scripts



In this repository we provide the scripts used to generate and preprocess the stimuli, to present the stimuli in the scanner, to preprocess the fMRI data, and to run quality assurance analyses. These scripts can be found in the [`scripts`](scripts) directory. In particular,



- [`scripts/preprocessing-stimulus`](scripts/preprocessing-stimulus) contains the scripts to

  split the movie into separate parts to be presented in the scanner, and preprocess the audio of the movie to make it more audible in the scanner.

- [`scripts/presentation`](scripts/presentation) contains PsychoPy presentation scripts.

- [`scripts/preprocessing-fmri`](scripts/preprocessing-fmri) contains the scripts used to run [fMRIprep](https://fmriprep.readthedocs.io/) for preprocessing.

- [`scripts/quality-assurance`](scripts/quality-assurance) contains scripts to run QA analyses and generate the figures reported in the data paper.

- [`scripts/hyperalignment-and-decoding`](hyperalignment-and-decoding) contains scripts to perform hyperalignment and movie segment classification.

- [`notebooks`](notebooks) contains jupyter notebooks to generate figures and run additional analyses.



Below we describe the content of these directories and their role in the analyses.



### Stimulus preprocessing



The movie was extracted from a DVD and converted into mkv (`libmkv 0.6.5.1`) format using [HandBrake](https://handbrake.fr/). Unfortunately, this process was not scripted. The DVD had [UPC code 024543897385](https://www.upcitemdb.com/upc/24543897385). We provide additional metadata associated with the converted movie file to make sure that future conversions would match our stimuli as best as possible. The information is available in [`scripts/preprocessing-stimulus/movie-file-info.txt`](scripts/preprocessing-stimulus/movie-file-info.txt). The total duration of the movie was `01:39:55.17`. The video and audio were encoded with the following codecs:



```

Stream #0:0(eng): Video: h264 (High), yuv420p(tv, smpte170m/smpte170m/bt709, progressive), 720x480 [SAR 32:27 DAR 16:9], SAR 186:157 DAR 279:157, 30 fps, 30 tbr, 1k tbn, 60 tbc (default)

Stream #0:1(eng): Audio: ac3, 48000 Hz, stereo, fltp, 160 kb/s (default)

Stream #0:2(eng): Audio: ac3, 48000 Hz, 5.1(side), fltp, 384 kb/s

```



Once the movie was extracted and converted, it was split into different parts for a behavioral session and five imaging runs. The times for the behavioral session are available in [`scripts/preprocessing-stimulus/splits_behav.txt`](scripts/preprocessing-stimulus/splits_behav.txt). These first ~45 minutes of the movie were shown outside the scanner, right before the imaging session. The times of the five additional splits of the second part of the movie are available in [`scripts/preprocessing-stimulus/splits.txt`](scripts/preprocessing-stimulus/splits.txt). Each row indicates a pair of start/end times for each split.



We also provide the scripts used to generate these splits, which used `ffmpeg`. While the movies were converted, the audio was also postprocessed and passed through an audio compressor to reduce the dynamic range and make dialogues more audible in the scanner. These scripts are  [`scripts/preprocessing-stimulus/split_movie_behav.sh`](scripts/preprocessing-stimulus/split_movie_behav.sh) and [`scripts/preprocessing-stimulus/split_movie.sh`](scripts/preprocessing-stimulus/split_movie.sh), for the behavioral and imaging sessions respectively. They produce six files named `budapest_part[1-6].mp4` that were used for the experiment.



During the first anatomical scan, subjects were shown the last five minutes of `budapest_part1.mp4` so that they could select an appropriate volume for the remaining five functional scans. The clip showed during the anatomical scan is generated by the script [`scripts/preprocessing-stimulus/split_part1_soundcheck.sh`](scripts/preprocessing-stimulus/split_part1_soundcheck). This script generates a file named `budapest_soundcheck.mp4`. 



### Presentation scripts



For the behavioral session outside the scanner, subjects were  shown `budapest_part1.mp4` (generated as described above) using VLC and high-quality headphones. Subjects could adjust the volume as much as they liked, and no instructions were given.



All presentation scripts used [PsychoPy](https://www.psychopy.org/). Unfortunately, we are unable to access the computer used for presentation, so we cannot provide the specific version used in our experiment. Any recent version of PsychoPy should be able to run the presentation code. Feel free to open an issue on this repository if you encounter problems.



All presentation scripts assume that the stimuli are placed in a subdirectory named `stim`.



During the anatomical scan, subjects were shown the last five minutes of the part they saw outside the scanner. This was done so that subjects could select an appropriate volume. The presentation script used for this run is [`scripts/presentation/soundcheck.py`](scripts/presentation/soundcheck.py). The subject can decrease/increase the volume using the buttons `1` and `2` respectively. Once the script has run, it saves the volume level in a json file called `subjectvolume.json`. This is an example of such file



```json

{

 "sid000020": 1.0,

 "sid000021": 0.5,

 "sid000009": 0.75,

}

```



The presentation script used for the functional imaging runs is [`scripts/presentation/show_movie.py`](scripts/presentation/show_movie.py). Some (limited) config values can be defined in the config json file [`scripts/presentation/config.json`](scripts/presentation/config.json). Once the presentation script is loaded, it shows a dialog box to select the subject id and the run number. The volume is automatically selected by loading the volume information stored in `subjectvolume.json`. Log files are stored in a subdirectory named `res`. It's possible to stop the experiment at any point using `CTRL + q`. In that case, the logs are flushed, saved, and moved to a file with suffix `__halted.txt`. 



The logs save detailed timing information (perhaps eccessive) about each frame. By default, useful information for extracting event files is logged with a `BIDS` log level. Thus, one can easily generate a detailed events file by grepping `BIDS`. For example



```bash

$ grep BIDS sub-test_task-movie_run-1_20200916T114100.txt | awk '{for (i=3; i