This is a collaborative space. In order to contribute, send an email to maximilien.chaumon@icm-institute.org
On any page, type the letter L on your keyboard to add a "Label" to the page, which will make search easier.

How to register an App on Brainlife

Owned by Aurore Bussalb (Unlicensed)
Last updated: Jun 08, 2021
4 min read

Once the App being developed runs locally and is pushed to a GitHub repository, the next step is to register it on Brainlife. The steps are described in the Brainlife documentation.

Meeting with Giulia Berto

Feb 5, 2021

Attendees:

  • Giulia Berto

  • Guiomar Niso

  • @Aurore Bussalb (Unlicensed)

Pre-requisites before registering Apps on Brainlife

Register an App on Brainlife

  • Detail

    • maintainer: put name of the creator of the App

    • if you let the Projects field empty, the App will be public

    • when the App is under development, it’s good practice to make it private by adding a project (see list of Projects): can be ‘My Default Project’ (possible to add collaborators on it to have feedback) or an App test project that already exists (ask Soichi or Giulia to be added to it)

    • when the App is being developed, work on the master branch

    • when the App is going to become public, release a new branch and specify it (see Brainlife documentation)

When you select “My default project” as a project, make sure that this project is private (see screenshot below), otherwise when you submit your App an error occurs: Error: Request failed with status code 500

  • Inputs

    • possible to add several inputs

    • ID: this field will be deprecated soon, usually we put ‘0' or 'fif1’…

    • if you have several identical inputs (e.g. several meg/fif), it’s best to enter one input and select the parameter “multi” for this input than create several inputs

    • in this case, when you test locally your App, the config.json.example must be written as follow:

      { fif": [ "/path/to/rest1-raw.fif", "/path/to/rest1-raw.fif", "/path/to/rest1-raw.fif", "/path/to/rest1-raw.fif" ] }

    • choose carefully the datatype used by the App. For instance if we choose neuro/meg/fif, the file mapping field will contain files specific to this datatype (meg.fif, channels.tsv, headshape.pos, coordsystem.json, … see https://brainlife.io/datatypes/6000737faacf9ee51fa691cb)

    • In the config.json.example file used to test locally the App, the keys of the input files must be the names of the files specified in the datatype (keys are linked to datatypes). For instance, for neuro/meg/fif, the inputs in config.json.example will be written as follow:

{ "fif": "/path/to/fif/file/file.fif", "channels": "/path/to/channels", "headshape": "/path/to/headshape", "coordsystem": "/path/to/coordsystem", "crosstalk": "/path/to/crosstalk/" }

The channels.tsv, headshape.pos, coordsystem.json, and the crosstalk.fif are optional, so the user of the App doesn’t have to add them. But, even if he doesn’t add them, they appear in the config.json file (the config file created when registering an App on Brainlife), see Error when an optional file is not available in a dataset.

  • Parameters

    • don’t hesitate to set parameters by default

    • it’s possible to put parameters in read only

    • parameters that can be changed but that is best to keep their default values can be moved in the “Advanced option” section

    • it’s not possible to pass a list as parameters: the list will be considered as a string by Brainlife, so it needs to be converted in the Python code (see Parameters conversion to make an App run on BL. If the list is empty enter [].

    • when you enter a string no need to surround it with ““

    • the lesser parameters, the better

    • parameters are listed in config.json.example (when the App is run locally) and then in config.json (after the App was registered on Brainlife)

    • you can enter various types of parameters (ENUM, STRING, NUMBER, BOOLEAN)

    • parameters can be optional, for more details see Error when running a pipeline with optional files and Create a helper.py file

    • in the config.json.example don’t use nested objects structures such as:

{ "params_maxwell_filter": { "origin": "auto", "int_order": 8 } }

It’s possible to create a mne_config.json that stores all parameters for the mne functions used in the App. These parameters are set to default while registering the App.

In BL, there is no distinction between float and int, so it’s good practice to specify in the parameter description if an integer or a float is expected.

  • Output

    • output will be saved in the working directory

    • but it’s preferable to put it in a different folder

    • for each datatype output, you must define one output directory

    • the folder containing the output directory must be created by the main file with mkdir -p <name of output directory>

Before releasing an App, test it on Brainlife, datasets are available on Brainlife to do so. The information to provide when registering an App can be updated at any moment.

Once you release your App, it’s better not to change it.