Mauritius Strategic Tool for the Analysis of Risk: mu-star Technical Documentation

This document describes the methodology, data and implementation for the development of the Mauritius Strategic Tool for the Analysis of Risk (mu-star).

The focus of this document is to:

• Provide a detailed overview of the methodology and the component models;
• Record the modelling assumptions made in the analysis;
• Describe the datasets collected and finalised in implementing the methodology;

This is a technical document which is meant to explain the theory and concepts behind the spatial risk analysis and component models being developed in Mauritius.

The main target audience of this report includes climate risk and infrastructure modellers and technical experts who would be interested in understanding the detailed working of mu-star, including researchers and model developers who intend to work on and develop the codebase.

Document control

Developer’s README

This chapter covers installation and setup of the codes to run and reproduce the analysis. It assumes familiarity with the git version control system, the use of the command-line (or “terminal” or “shell”) to run various tools, and the Python programming language.

The repository nismod/mu-star contains project-specific codes and configuration to run climate-related risk and resilience analysis of infrastructure networks in Mauritius.

Outline

The overall technical architecture of the project follows this outline:

• data and results are held separately from code, shared under appropriate licence agreements
• nismod/mu-star holds the modelling and analysis code
  • implements the reproducible modelling and analysis pipeline or “workflow”
  • depends on data collection and preprocessing
  • technologies:
    • programming language of choice is Python, suggest using micromamba to manage environment
    • workflow tool of choice is snakemake
  • the workflow rules in ./workflow define the processing steps to run the full analysis, from source data inputs
    • nested within the workflow, each infrastructure system (energy, transport, water) has a model that calculates metrics of disruption
    • models are developed as separate packages within ./src/<model_name>, exposing a standard interface that can then be called from the workflow rules
      • inputs are:
        • data describing the system (assets, usage)
        • a list of assets to consider “disrupted” or non-functional
      • outputs are metrics of disruption to supply, for example:
        • customers (or demand zones) with loss of service
        • costs of supply or re-routing in disrupted state
        • levels of service
• nismod/irv-standalone holds the web application code
  • implements the results visualisation platform or “viewer”
  • depends on data (results) generated by the workflow
  • technologies:
    • development setup uses docker and docker-compose
    • backend is in Python and FastAPI, Django, with vector and raster tileservers
    • frontend in TypeScript and React, with maplibre-gl-js and d3 among other dependencies
    • database is Postgres with PostGIS

flowchart TB
    User["Application user<br/>Web browser"]
    Admin["Administrator<br/>Web browser"]

    subgraph IRV["Web app: nismod/irv-standalone"]
        UI["User interface<br/>React / TypeScript"]
        AdminUI["Admin user interface<br/>Django Admin"]

        subgraph VM["Server"]
            Proxy["Web server / reverse proxy"]
            Django["Django application<br/>Web API, authentication and metadata"]
        end

        Proxy <-->|"Requests"| Django

        UI -->|"API requests"| Proxy
        AdminUI -->|"Admin requests"| Proxy

        Database[("Application data and metadata<br/>PostgreSQL / PostGIS database<br/>Raster and vector tiles")]

    end

    subgraph MU["Workflow: nismod/mu-star"]
        Snakemake["Modelling and analysis workflow<br/>Snakemake"]
        Models["Damage, disruption, risk and adaptation analysis<br/>Python models"]

        Snakemake -->|"Orchestrate"| Models
    end


    subgraph SharedStore["Shared file store"]
        InputData[("Prepared input data")]
        Results[("Analytical outputs and<br/>visualisation-ready results")]
    end

    User -->|"HTTPS"| UI
    UI -->|"Display maps, charts<br/>and analytical results"| User

    Admin -->|"HTTPS"| AdminUI
    AdminUI -->|"Manage users,<br/>data and metadata"| Admin

    Django <-->|"Queries"| Database

    InputData -->|"Read"| Models
    Models -->|"Write"| Results

    Results -->|"Load data and results"| Database

Setup and installation

Clone or download this repository from GitHub:

git clone git@github.com:nismod/mu-star.git

Next, install required dependencies. We recommend using micromamba to install these into a conda environment.

Create a conda environment once (per machine/user):

micromamba create --file environment.yaml

Activate it any time you pick up work on this repository:

micromamba activate mu-star

Install nbstripout to ensure that no outputs are committed with any jupyter notebooks:

nbstripout --install

Usage

The principal goal of this repository is to analyse risks to infrastructure systems, in terms of direct damages, indirect losses, and the costs and benefits of adaptation options.

These results will be visualised in an online viewer, under development at irv-standalone.

The analysis is comprised of Python scripts wrapped in snakemake rules. Snakemake is a workflow management system that can be used to break up complex modelling chains and improve the reproducibility of analyses. To invoke a rule, call snakemake followed by the file you want to produce.

Some functionality is contained within a helper Python module, located in src/mu_star.

Environment

To make snakemake, the helper Python module and other software dependencies available, activate the environment we previously created.

micromamba activate mu-star

Configuration

Analysis options can be configured using the config/config.yaml file. See it for inline documentation.

Invocation

We use snakemake to drive any analysis. It’s best explained with an example. To invoke the rule (and all necessary predecessor rules) to compute direct damage (rehabiliation) costs to the road network due to fluvial flooding, we’d run the following:

snakemake --dry-run --cores 1 data/out/damage/layer-road/rp/peril-flood/subperil-fluvial/ensemble-0/damage.zarr

Parts of the requested file path are parameterisable, e.g. layer-road, peril-flood, subperil-fluvial. By varying these ‘wildcards’ different outputs can be produced.

Note that the --dry-run flag asks snakemake to report on what work (if any) is necessary. As jobs can be long running, this is useful to check beforehand. To actually run the rules, remove the dry run flag.

The --cores flag indicates how many processors snakemake will use to execute the rules. If rules do not depend on one another and enough processors are available, they may execute simultaneously.

Available rules

See .smk files in workflow/ for available rules and their required input and output files.

While this workflow is in development, some of the rules are placeholders.

Testing

Test the helper library and other included packages by activating the environment and running the following from this directory:

python -m pytest -n 2 src/

Run auto-formatting and check for common minor problems using ruff:

ruff format
ruff check

Documentation

Documentation is written in the ./docs/src directory using markdown and built using mdbook.

Read the latest documentation at: https://nismod.github.io/mu-star/

Contributing

New to the project? Start with CONTRIBUTING.md. It covers setup and a first session, how we work with branches and pull requests, where your work goes and how to write issues. In short: open draft pull requests early, keep changes fairly small, and ask for review often.

Citation

All contributors should be listed in ./CITATION.cff.

Once released, a Zenodo DOI will be available.

Cite this software as follows:

Russell, T., & Thomas, F. Mauritius STAR [Computer software]. https://github.com/nismod/mu-star

@software{Russell_Mauritius_STAR,
author = {Russell, Tom and Thomas, Fred},
license = {MIT},
title = {{Mauritius STAR}},
url = {https://github.com/nismod/mu-star}
}

Acknowledgements

Funded by the Foreign and Commonwealth Development Office (FCDO) of the United Kingdom.

Risk analysis

Hazards

Context

Economic activity and trade

Population

Infrastructure systems models

Water

Energy

Transport

Context

Data

Methods

Direct Damages

Indirect losses

Adaptation

mu_star

mu_star.constant

sample_model

sample_model.model