How to develop an App

Jan 18, 2021

Attendees

Guiomar Niso
Franco Pestilli
Giulia Berto
@Aurore Bussalb (Unlicensed)

Documentation on how to make an App:

https://brainlife.io/docs/apps/introduction/

Examples of Apps:

https://github.com/brainlife/app-template-python
https://github.com/francopestilli/app-template-matlab

These Apps can be downloaded and locally tested.

Steps to develop an App:

First step: write code that runs on your local machine
Second step: run the code in a Docker container
Third: register the code in the Brainlife (BL) platform and be careful to the datatype of the input

Files required in an App:

LICENSE file (MIT License)
main file:
- shell script, we use PBS (manage clusters)
- Clusters: network of computers, which have a scheduler
- PBS parameters: how many nodes I need, how long the App will take to run. Apps that are fast to compute will be run first in BL. To know these PBS parameters, we used the info we obtained when the App ran on our local computer
- We can update the App to change the PBS parameters, they are flexible. But these parameters don’t adapt automatically (i.e. they are fixed, they don’t update with the size of the input file given to the App for instance)
- Write a simple code (don’t make useless copies of variables for instance)
- A Docker container is used to run the code. Docker runs with sudo, when you run Docker container you must have the administrators rights. So we run the code in singularity container (no need for administrator rights in this case)
- We can pull the Docker on our computer and then test the code. We don’t create a Docker container for each App, we used those already available (listed here: https://hub.docker.com/u/brainlife)
- For Brainstorm, we create a Matlab Docker container (no Docker on Brainstorm) so Brainstorm will run on a Matlab Docker
- It’s possible to display plots directly in the Brainlife interface by adding:

cat << EOF > product.json
{
    "brainlife": [
       { 
           "type": "image/png", 
	   "name": "Alpha peak on mean spectrum",
           "base64": "$(base64 -w 0 out_dir/psd_mean.png)"
       },
       { 
           "type": "image/png", 
	   "name": "Power spectrum for all channels",
           "base64": "$(base64 -w 0 out_dir/psd_channels.png)"
       }
]
}
EOF

and the results is:

It’s good practice to create a directory that will contain the output file by adding in the main: mkdir -p <output_directory>. When the App generates more than one output, an output directory for each output (corresponding to one datatype) must be created.
The output file name must correspond to the name of the file in File mapping section when you register an App. For instance, a meg file must be saved as “meg.fif”. This is important when you run an App after another in a pipeline (the second App takes as input the output of the previous one). If the name of the output of the first app is not right, a FileNotFoundError is raised (see How to run Apps one after another).

main file (in .py or .mat, not required to call it main):
- in this file, the config.json file (created by BL according to the parameters we specify when registering the App in BL) is loaded and parsed
- For a local test, we can create a config.json.example (BL overlooks it when registering the App)
- To parse the .json file, in Matlab we need the module jsonlab
- It’s possible to display messages in the Brainlife UI when executing an App: just create a product.json that stores all of the messages (see documentation)

config file:
- to test your App locally, create a config.json.example that contains all the parameters for your App to run
- BL will parse a config.json so you have to create a symlink towards that file
- In your code you can directly write config.json but this file won’t be part of your repository (except to give an example for the users), it’s up to the user to create its own config.json if he wants to run this App outside of BL

ln -s config.json.example config.json

BL interface:

See How to register an App on Brainlife
Register a new App: if we don’t add a description, the README.md is used (cf. template README https://github.com/brainlife/app-template-python/blob/master/README.md )
Nice to add a customized image for the App
Put the address to the GitHub repository (first we develop on your own user accounts, then move the App to the BL organization? BL will maintain the code in the long term). Usually don’t use the master branch
Create the configuration parameters (key/value → tell BL what your App expects),
1. enter the parameters,
2. enter the input (define the datatype, add a tag if you want),
3. specify the output: define also its datatype, and its tag but don’t worry too much about its datatype (we can use raw for instance)