img2fmri 1.0

img2fmri: a python package for predicting group-level fMRI responses to visual stimuli using deep neural networks

img2fmri

img2fmri: a python package for predicting group-level fMRI responses to visual stimuli using deep neural networks

Our model is intended to be used by researchers that might benefit from analyzing stimulus-driven patterns of activity in visual cortex, including research involving the temporal dynamics of visual cortex, or research conducted in the absence of an fMRI scanner and human subjects.

Users are encouraged to read the background science information for an overview of the model and its intended uses (science_overview.pdf).

Installation

To install and use img2fmri, users must work from a coding environment with FSL and AFNI installed or use our Docker container which comes with those packages pre-installed.

pip/PyPI

For users who already have FSL and AFNI installed, img2fmri can be installed and tested with:

pip install img2fmri
pytest -s --pyargs img2fmri

Docker

For users that intend to use our docker environment to test and use img2fmri, the Dockerfile included in this repo can be used to build an image as follows:

docker build --tag img2fmri --file Dockerfile .

and if successfully built, can be run and tested with:

docker run -it -p 8888:8888 img2fmri
pytest -s --pyargs img2fmri

Alternatively, our pre-built image can be pulled and used,though do note that this is a large (~10GB compressed) image.

docker pull mbennett12/img2fmri
docker run -it -p 8888:8888 mbennett12/img2fmri
pytest -s --pyargs img2fmri

Conda

Optionally, users can install Conda and create an environment with python 3.9 ready for img2fmri (NOTE: this conda environment still needs access to FSL and AFNI):

conda create --name name_of_environment python=3.9
conda activate name_of_environment
pip install img2fmri

(Optional) Jupyter and running analyses

In order to run the jupyter notebook analyses in overview.ipynb or model_training.ipynb, the following commands should be run.

If running the docker container from the command:

docker run -it -p 8888:8888 img2fmri

users should then clone this repo and run the following command from within the container:

git clone https://github.com/dpmlab/img2fmri.git
python3 -m notebook --allow-root --no-browser --ip=0.0.0.0

in order to then access their docker container's jupyter notebook at the following url: http://localhost:8888. Note that users will need to copy and paste the token shown in the output of the previous command in their web browser to access their docker container's directory.

Usage and Documentation

Users are encouraged to view our ReadTheDocs documentation for our API documentation, and also review overview.ipynb notebook which shows the import and use of the img2fmri.predict() function, as well as its extension to movies using img2fmri.predict(predict_movie=True).

img2fmri can also be used as a command-line interface, as:

img2fmri [-h] --input input_dir_or_movie [--output output_dir]
         [--roi_list each roi here] [--sigma sigma_val] [--center_crop true_or_false]
         [--predict_movie true_or_false]

Regions of Interests (ROIs) and neuroimaging files

fMRI ROI bool masks (in subject space, MNI space, and MNI space post-smoothing), T1 files, and other neuroimaging reference files that are used in our prediction pipeline can be found in the derivatives folder.

Testing

Users can test their img2fmri installation by using the following command:

pytest -s --pyargs img2fmri

which will run the tests located in img2fmri/tests/run_test.py, which test the python-imported image prediction, the movie prediction pipeline, and the command line interface package usage.

Support and Contributing

Users are encouraged to review CONTRIBUTING.rst with suggestions on how to report issues and contribute to the img2fmri software package. Users can also email the author at Max Bennett with questions or issues.

License

This package is licensed under an MIT license found in LICENSE.txt