Skip to content
NeuroScout web app and API
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add release drafter Mar 13, 2019
celery_worker Normalize all Jun 8, 2019
neuroscout HOTFIX: Remove double space Jun 11, 2019
nginx Move nginx references May 22, 2019
.env.example Update docs May 21, 2019
.gitignore Ignore config.ts, but copy example ts for travis. Closes #308 Aug 22, 2018
.pliersenv.example Update README and modify example env files Jan 18, 2019
.travis.yml Make neuroscout installable package May 21, 2019
.zenodo.json Fix license in .zenodo Apr 26, 2019
LICENSE Create LICENSE Aug 2, 2018 Update docs May 21, 2019
codecov.yml Add codecov Nov 1, 2017 Remove monitor May 22, 2019
docker-compose.yml Remove monitor May 22, 2019 Add May 21, 2019


Build Status codecov DOI

This is the repository for the neuroscout server.

Requirements: Docker and docker-compose.


First, set up the main environment variables in .env (see: .env.example). Set DATASET_DIR, KEY_DIR, and FILE_DATA to folders on the host machine.

Optionally, set up pliers API keys for feature extraction in .pliersenv (see: .pliersenv.example). More information on pliers API keys

Next, set up the Flask server's environment variables by modifying neuroscout/config/ and saving as neuroscout/config/

Finally, set up the frontend's env variables by modifying neuroscout/frontend/src/config.ts.example and saving as neuroscout/frontend/src/config.ts.

For single sign on using Google, a sign-in project is needed.

Initalizing backend

Build the containers and start services using the development configuration:

docker-compose build
docker-compose -f docker-compose.yml -f up -d

The server should now be running at http://localhost/

Next, initialize, migrate and upgrade the database migrations. If you have a database file, load it using pg_restore. Otherwise, delete the migrations folder, initalize the database and add a test user.

docker-compose exec neuroscout bash
rm -rf /migrations/migrations
python db init
python db migrate
python db upgrade
python add_user useremail password

Setting up front end

The frontend dependencies are managed using yarn

Enter the neuroscout image, and install all the necessary libraries like so:

docker-compose exec neuroscout bash
cd frontend

You can then start a development server:

yarn start

Or make a production build:

yarn build

Ingesting datasets and extracting features

You can use commands to ingest data into the database. Run the following commands inside docker: docker-compose exec neuroscout bash

To add BIDS datasets

python add_task bids_directory_path task_name

For example for dataset ds009

python add_task /datasets/ds009 emotionalregulation

Finally, once having added a dataset to the database, you can extract features using pliers into the database as follows:

python extract_features bids_directory_path task_name graph_json

For example:

python extract_features /datasets/ds009 emotionalregulation graph.json

Even easier, is to use a preconfigured dataset config file, such as:

docker-compose exec neuroscout python ingest_from_json /neuroscout/config/ds009.json

Maintaining docker image and db

If you make a change to /neuroscout, you should be able to simply restart the server.

docker-compose restart neuroscout

If you need to upgrade the db after changing any models:

docker-compose exec neuroscout python db migrate
docker-compose exec neuroscout python db upgrade

To inspect the database using psql:

docker-compose run postgres psql -U postgres -h postgres


Once the server is up and running, you can access the API however you'd like.

The API is document using Swagger UI at:



To authorize API requests, we use JSON Web Tokens using Flask-JWT. Simply navigate to localhost:5000/auth and post the following

    "username": "",
    "password": "string"

You will receive an authorization token in return, such as:

    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNDQ0OTE3NjQwLCJuYmYiOjE0NDQ5MTc2NDAsImV4cCI6MTQ0NDkxNzk0MH0.KPmI6WSjRjlpzecPvs3q_T3cJQvAgJvaQAPtk1abC_E"

You can then insert this token into the header to authorize API requests:

GET /protected HTTP/1.1
Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNDQ0OTE3NjQwLCJuYmYiOjE0NDQ5MTc2NDAsImV4cCI6MTQ0NDkxNzk0MH0.KPmI6WSjRjlpzecPvs3q_T3cJQvAgJvaQAPtk1abC_E

Note that in order to use any protected routes, you must confirm the email on your account. Confusingly, you can get a valid token without confirming your account, but protected routes will not function until confirmation.

Running tests

To run tests, after starting services, create a test database:

docker-compose exec postgres psql -h postgres -U postgres -c "create database scout_test"

and execute:

docker-compose run -e "" --rm -w /neuroscout neuroscout python -m pytest neuroscout/tests

or run them interactively: docker.compose exec neuroscout bash python -m pytest neuroscout/tests/ --pdb

To run frontend tests run:

docker-compose run --rm -w /neuroscout/neuroscout/frontend neuroscout npm test
You can’t perform that action at this time.