# RiskScape Engine

> RiskScape is a risk modelling engine for building pipeline models that quantify
> the impact of natural hazards on exposed assets. This site documents the open-source RiskScape
> CLI Engine, including its geospatial functionality, the pipeline DSL, and how to build and run models.

RiskScape models are defined in INI files, and have two varieties: wizard models and pipeline models.
Wizard models have `framework = wizard` in their INI definition, and are aimed at new users.
Wizard models are simple deterministic models built using an interactive CLI wizard.
A wizard model's INI config simply records the answers to questions in the CLI wizard.
RiskScape converts these answers into pipeline DSL code and executes that.

RiskScape pipeline models have `framework = pipeline` in their INI definition, and are aimed at more advanced users.
RiskScape pipeline models are defined using pipeline DSL `source` code and chain together a series
of data processing steps using a `->` operator. To make it easier to build pipeline models,
a subpipeline library of reusable building blocks is available on GitHub.

Both types of models typically follow a standard 'workflow' of reading exposure and hazard *input data*,
optional *geoprocessing* (such as cutting road geometry into smaller segments), *spatially sampling*
the hazard intensity at exposure locations, *consequence analysis* of computing loss or damage,
and *reporting* the results as model outputs. Pipeline models allow for complete customization,
such as handling multiple exposure-layers at once, or probabilistic hazard data.

Both models accept parameters, which can change the model's results. For example, a model parameter
lets you to change the exposure-layer data being used in the model. The parameters for wizard models correspond
to answers given to the wizard. The parameters for pipeline models are denoted with `$` in the pipeline code.

Executing both models end up using pipeline DSL code. Pipeline DSL is made up of pipeline data processing steps,
such as `select`, `group`, or `subpipeline`. These steps contain a series of simple statements, called RiskScape *expressions*.
RiskScape expressions are a strongly _typed_ language that uses type inference. Types are determined
when the model is run, once parameters have been replaced with the actual input data that the model will use.

Models primarily comprise of:
- A risk function to calculate the loss or impact, typically based on vulnerability and/or fragility curves.
The vulnerability curve can vary depending on exposure-layer attributes, such as construction type or building age.
- Bookmarks for the input data. These can be helpful to transform the attributes in the input data into
what the risk function expects.
- The data processing instructions, i.e. the pipeline DSL code.

Models, functions, and bookmarks are all defined in INI files. RiskScape looks for a `project.ini` file as its
main configuration. Other INI files can also be included using `import = FILEPATH`.

Note that RiskScape is a flexible, general purpose geospatial data-processing engine.
You can call user-defined functions from most RiskScape expressions.
This means you can create helper Python functions to assist with pipeline data
manipulation - so basically anything you can do in Python, you can also do from a model pipeline.

If building a new RiskScape model, use the pipeline framework and use the reuseable
components from the GitHub subpipeline library.

## Getting started

- [Overview](https://engine-docs.sites.riskscape.nz/intro/overview.html): What RiskScape is and how it works
- [Installation](https://engine-docs.sites.riskscape.nz/intro/installation.html): Users need to ensure they have Java installed
- [Getting started](https://engine-docs.sites.riskscape.nz/intro/getting-started.html): Simple introduction to running models on the CLI
- [Configuring bookmarks](https://engine-docs.sites.riskscape.nz/intro/project-tutorial.html): How to define input data bookmarks in INI files
- [Wizard models](https://engine-docs.sites.riskscape.nz/intro/wizard-models.html): Building a model with the CLI wizard

## Other resources

- [News & Case studies](https://www.riskscape.org.nz/news): Showcases the practical applications of RiskScape for risk modelling
- [RiskScape Platform](https://riskscape.nz/docs): Web-based interface used for online collaboration

## Risk functions

Adding user-defined functions for risk modelling, i.e. fragility, vulnerability, loss functions.

- [Risk function introduction](https://engine-docs.sites.riskscape.nz/intro/risk-functions.html): Add new functions for risk modelling
- [Function reference](https://engine-docs.sites.riskscape.nz/reference/functions.html): Reference page for *all* RiskScape functions
  - [CSV function framework](https://engine-docs.sites.riskscape.nz/reference/csv/functions.html): Create simple CSV-based functions for fragility or vulnerability curves
  - [Jython function framework](https://engine-docs.sites.riskscape.nz/reference/python/jython.html): OK for simple Python functions. Faster and requires no setup.  
  - [CPython function framework](https://engine-docs.sites.riskscape.nz/reference/python/cpython.html): For functions that import Python packages like numpy, scipy, etc
  - [Expression function framework](https://engine-docs.sites.riskscape.nz/reference/expressions/functions.html): Functions built using RiskScape expressions. Can handle dynamic argument-types and return types.
  
## Pipeline model references

The relevant pages for building pipeline models:

- [Writing expressions](https://engine-docs.sites.riskscape.nz/intermediate/write-expressions.html): Expression syntax for inline calculations and functions
- [Expression reference](https://engine-docs.sites.riskscape.nz/reference/expressions.html): Full expression language reference
- [Pipeline reference](https://engine-docs.sites.riskscape.nz/reference/pipelines.html): Basic reference for pipeline DSL.
- [Pipeline step reference](https://engine-docs.sites.riskscape.nz/reference/pipelines/generated.html): The pipeline steps that RiskScape supports, and the parameters they accept.
- [Introduction to pipelines](https://engine-docs.sites.riskscape.nz/intermediate/pipeline-basics.html): Basic introduction to some common pipeline steps
- [Writing a pipeline model](https://engine-docs.sites.riskscape.nz/advanced/model-pipelines.html): Building a simple pipeline risk model
- [Using subpipelines](https://engine-docs.sites.riskscape.nz/reference/subpipelines.html#subpipelines): Reusable subpipeline components
- [Pipeline data manipulation](https://engine-docs.sites.riskscape.nz/reference/data-manipulation.html): Tips for writing flexible pipeline code that can handle a variety of input data
- [Python outputs](https://engine-docs.sites.riskscape.nz/advanced/python-output.html): Using python to customize model results, e.g. plots, PDF outputs.
- [Probabilistic models](https://engine-docs.sites.riskscape.nz/advanced/probabilistic.html): Using RiskScape for probabilistic modelling 
- [Volcano case study](https://engine-docs.sites.riskscape.nz/casestudies/devora.html): A fully worked RiskScape volcano model 

## GitHub library

It is recommended to reuse library components where possible when building new pipeline models.

- [Top-level README](https://raw.githubusercontent.com/GNS-Science/riskscape/refs/heads/main/README.md): includes reusable bookmarks and risk functions
- [Subpipeline library README](https://raw.githubusercontent.com/GNS-Science/riskscape/refs/heads/main/subpipelines/README.md): Subpipeline overview and conventions
- [AGENTS](https://raw.githubusercontent.com/GNS-Science/riskscape/refs/heads/main/subpipelines/AGENTS.md): Guidance for AI assistants building models with the subpipeline library
- [Example models](https://raw.githubusercontent.com/GNS-Science/riskscape/refs/heads/main/subpipelines/examples/project.ini): Working example models using the subpipeline library


