fruitflybrain/neuronlp repository overview

⁠System Requirements

• Supported OS: Linux, Windows, macOS.
• Docker CE 19.03 or higher.
• SSD storage preferred, storage size needs depend on the dataset (see Tags⁠ below).
• A machine with at least 8GB of memory is recommended.

⁠Tags

Each tag corresponds to a NeuroNLP application on a particular dataset. For example, fruitflybrain/neuronlp:hemibrain provides a Docker image for the NeuroNLP application for the Hemibrain dataset. Currently, the available tags/datasets are:

• flycircuit: Flycircuit dataset v1.2⁠ - requires 5GB disk storage
• hemibrain: Hemibrain dataset v1.2⁠ - requires 18GB disk storage
• larva: Larva L1EM dataset⁠ - requires 500MB disk storage
• medulla: Medulla 7-column dataset⁠ - requires 400MB disk storage

Additional information about the datasets can be found at https://github.com/flybrainlab/datasets⁠

⁠Basic Usage

WARNING: The NeuroNLP image provides minimal security. Password for root and the user ffbo are both exposed in the build. Do not map any personal information in your local file system onto the Docker container if you intend to host the image publicly. To change the passwords, see Advanced Usage below..

For the instruction, we will use the tag hemibrain as an example.

Step 1: Pull the Docker image:

docker pull fruitflybrain/neuronlp:hemibrain

Step 2: Start a Docker container:

docker run --name hemibrain_nlp -p 8081:8081 -it fruitflybrain/neuronlp:hemibrain

If you want to use a port other than 8081, please launch the Docker container using the Advanced Usage below.

You will be asked if you want to download datasets to /home/ffbo/orientdb.

After a bit of wait, you should see a message in the terminal saying Servers started.

Step 3: Launch NeuroNLP from your host's browser at http://localhost:8081.

Step 4 Accessing the container:

You can login to the running container by

docker exec -it hemibrain_nlp bash

where fbl is the name of the container specified previously using --name. See Advanced Usage below for more details of the setup.

Step 5 Stop NeuroNLP:

press ctrl+c to stop the container.

Step 6 (optional) Restart NeuroNLP container:

docker start -i hemibrain_nlp

where hemibrain_nlp is the name of the container specified previously using --name. You will be asked if you want to download datasets. You can skip this if you have already downloaded the dataset. You can also choose to load a fresh copy of the datasets by overwriting the existing one.

⁠Advanced Usage

If you want to have more control of the Docker container, and/or you want to use a different port for the NeuroNLP application on your browser, you can launch the Docker container by

docker run --name hemibrain_nlp -p 8085:8081 -it fruitflybrain/neuronlp:hemibrain /bin/bash

The container will be launched and attached. Once you are inside the container, you can download the dataset by

~/ffbo/bin/download_hemibrain.sh /home/ffbo/orientdb

Edit the config file at /home/ffbo/.ffbo/config/config.ini, and change the line under NLP, exposed-port = 8085. Then launch:

~/ffbo/bin/start.sh hemibrain

To properly shutdown all the servers:

~/ffbo/bin/shutdown.sh

Default user in the Docker container is ffbo, and its password is Drosophila.

The image contains two conda environments: ffbo and ffbo_legacy.

• ffbo_legacyonly contains packages necessary for running the NeuroNLP server in Python 2.7.
• ffbo contains packages to run all other servers, including processor, NeuroArch, Neurokernel, and FlyBrainLab, in Python 3.7. Additional Python libraries should be installed in this environment.

OrientDB is installed in /home/ffbo/orientdb.

We provide a set of scripts in ~/ffbo/bin to launch servers and applications.

• Shortcuts (recommended way of starting NeuroNLP):
  • start.sh: start NeuroNLP, including starting all backend servers, each in a tmux session.
  • shutdown.sh: stop NeuroNLP and all backend servers, the tmux sessions will be killed.
  • update.sh: update all packages to the latest version.
• Individual scripts (must be executed in the following order):
  • download dataset script:
    • download_hemibrain.sh: download hemibrain dataset.
    • download_flycircuit.sh: download flycircuit dataset.
    • download_l1em.sh: download l1em dataset.
    • download_medulla.sh: download medulla dataset.
  • run_processor.sh: start crossbar and FFBO processor.
  • run_nlp.sh: start NeuroNLP server.
  • run_database.sh: start OrientDB database.
  • run_neuroarch.sh: start NeuroArch server.