This documentation page is intended for developers working on the source code of an indicator in the context of the "Open Mobility Indicators" project.
Each indicator must be defined as a GitLab project and provide a container image.
An indicator can be computed in different scenarios:
- locally on a development machine: in this case the results will be only available locally
- remotely using the "compute indicator" pipeline provided by the Open Mobility Indicators infrastructure: in this case the pipeline will run the container image of the indicator and deploy the results on a public static file server and the frontend application
This documentation specifies the requirements expected by the pipeline for the indicator container image to be successfully called by the pipeline.
## Specifications
A GitLab project containing the source code of an indicator must provide several files and folders as described in the following sections.
### Entry points
A script named `download.sh` must exist for downloading resources needed to compute the indicator. This script can do nothing in the case no data is needed, but it must exist.
This download script receives a directory as a parameter, where to write the downloaded resources. It can access the parameter profile configuration values as environment variables.
A script named `compute.sh` must exist for computing the indicator from downloaded resources.
This compute script receives two directories as parameters, the first one being where to read the downloaded resources, and the second one being where to write the results to. It can access the parameter profile configuration values as environment variables.
Those scripts are called "entry points" because they are called by the pipeline each time the indicator is computed on the Open Mobility Indicators infrastructure. The pipeline expects to find those scripts under `/app/download.sh` and `/app/convert.sh` respectively.
Those scripts can call anything they want as long as it has been installed in the container image via the `Dockerfile` (cf section below). As a consequence, any programming language can be used in theory.
Some templates are defined in [this sub-group](https://gitlab.com/open-mobility-indicators/indicator-templates), for example the [jupyter-notebook](https://gitlab.com/open-mobility-indicators/indicator-templates/jupyter-notebook) which uses Jupyter Notebook with Python to compute a geo indicator.
Please contact the project team if you'd like to create an indicator using a programming language that is not working with this setup.
### Parameter profiles
A folder named `parameter_profiles` containing several **dotenv** files must exist, each one capturing a different parameter set for the same source code. Each pipeline run will provide a value specifying which one to use.
### Container image
A file named `Dockerfile` and another one named `.gitlab-ci.yml` must exist for building the container image automatically.
