How RiskScape models work

Before we start

This tutorial is aimed at new users who want an introduction to how risk models work in RiskScape. We expect that you:

  • Have been through the Getting started modelling in RiskScape guide and have a basic idea of what RiskScape is about.

  • Are comfortable running shell commands from a command prompt. If you are inexperienced at using the command-line, try reading How to navigate the RiskScape CLI first.

  • Have a basic understanding of geospatial data and risk analysis.

  • Have a GIS application (e.g. QGIS) installed that you can use to view shapefile and GeoTIFF files.

The aim of this tutorial is to introduce the underlying concepts behind running models in RiskScape, and familiarize new users with the RiskScape Command-Line Interface (CLI).

For simplicity, this tutorial will not delve into much detail around creating bookmarks, writing your own functions, or building your own models or pipelines from scratch. These topics will all be covered in later tutorials.


Ensure that you have the latest copy of RiskScape installed on your system. For directions on how to install RiskScape, see Installation and setup

Getting started


Click here to download the input data we will use in these examples. Unzip the file into a new directory, e.g. C:\RiskScape_Projects\.

Open a command prompt and use cd to change directory to where you unzipped the files, e.g.

cd C:\RiskScape_Projects\models-intro

You will use this command prompt to run the RiskScape commands in this tutorial.

The input data files this tutorial will use are all in the models-intro\data sub-directory.


This input data was provided by NIWA and is based on published research papers. The regional map of Samoa was sourced from the PCRAFI (Pacific Risk Information System) website. The data files have been adapted slightly for this tutorial.

Input data

In this tutorial you will run several RiskScape models that determine tsunami exposure in Samoa. We will use similar source data to the getting started guide, modelled on the 2009 South Pacific Tsunami (SPT) event.

A RiskScape model involves combining geospatial layers together, and then performing risk analysis. The name of each layer reflects how RiskScape will use the layer in the model. The RiskScape models in this tutorial involve the following layers:

  • Exposure-layer: This contains the elements-at-risk, which is our building dataset, Buildings_SE_Upolu.shp. This shapefile was based on Open Street Map data for south-eastern Upolu.

  • Hazard-layer: This contains the hazard being modelled, which is a tsunami inundation map based on the 2009 SPT. We are using two different hazard layers, MaxEnv_All_Scenarios_10m.tif and MaxEnv_All_Scenarios_50m.tif, which use a 10-metre and 50-metre grid-size respectively. You can read more about how these hazard layers were produced here.

  • Area-layer: This contains regional boundaries, which can be optionally used to collate the model results, such as reporting the number of exposed buildings in each region. We will use the boundaries of the Samoa electoral constituencies (Samoa_constituencies.shp) in this example, which was sourced from the PCRAFI website.


RiskScape models also support an optional Resource-layer, which contains any other supplementary information required for risk analysis. For example, a resource-layer containing the soil type or water table depth might be used in a liquefaction model. This tutorial will not cover resource-layers at all.

RiskScape Projects

Alongside the data sub-directory, you should notice there is also a project.ini file in your unzipped directory. This file is called the RiskScape project file, and it contains all the instructions that RiskScape needs to run your models.

Projects are a way to organize your RiskScape models, a bit like a work-space. You can use separate projects when you want to model different things.

The project file is a plain-text file in the INI format. INI files simply contain sets of key = value pairs that store configuration settings and values.

Open the project.ini file in a text editor, such as Notepad or gedit.

We have pre-populated this project file with all the models we will use in this tutorial. In later tutorials we will explain how to build your own models and project files from scratch.


RiskScape defaults to using the project.ini file in the current working directory that you run the riskscape command from. If you want RiskScape to load a different project file, you can specify the file to use on the command-line. Refer to Specifying your project file for more details.

Running a model

RiskScape models provide a flexible framework that let you customize aspects of the risk analysis workflow, such as using different input data, changing the analysis that is performed, or varying other assumptions that your model might make.

RiskScape provides a command-line wizard that can help you to build a risk analysis model by answering a few questions. You can save the wizard answers in an INI file, which lets you re-run your model later. We will look more at building models in the wizard in the next tutorial.

The customizable aspects of a model are called the model’s parameters. Changing the model parameters lets you change the behaviour of the model on the fly.

Conceptually, what we will be doing in this tutorial will look like this:

graph LR WIZ("Wizard answers"); MODEL("Risk Model"); WIZ -- Saved config --> MODEL; PARAMS("Parameters<br/>to vary") -.-> MODEL; MODEL --> RUN("Model run<br/>command"); RUN --> EIT("Event Impact<br/>results"); %% Styling class PARAMS rs-box-optional class WIZ,MODEL,PARAMS, rs-box class RUN rs-box-navy class EIT rs-box-green style RUN color:#FFF

We will take saved wizard answers, optionally modify the model’s parameters, and then use a riskscape command to ‘run’ the risk model. Running the risk model will produce results file(s), which tell us the impact of the hazard event.

A simple RiskScape model

In the project.ini file, there is a basic-exposure model that looks something like this:

[model basic-exposure]
description = Simple example of a RiskScape model
framework = wizard
input-exposures.layer = data/Buildings_SE_Upolu.shp
input-hazards.layer = data/MaxEnv_All_Scenarios_50m.tif
sample.hazards-by = CLOSEST
analysis.function = is_exposed

This model was produced by using the RiskScape wizard, so it contains the saved answers to wizard questions. Each line is an INI file key-value, pair separated by an =. The left-hand-side (i.e. the key) is the name of the model parameter, and the right-hand-side is the value that will be used in the risk analysis model.


This "PARAMETER_NAME = VALUE" format is important because it determines how your risk model will behave. Changing the value of the model’s parameters will change the results that the model produces, which we will look at soon.

The model parameters correspond to decisions that RiskScape needs to make at various points during the model processing. A high-level overview of the processing behind our RiskScape model looks like this:

graph LR EL("Exposure-layer<br/>(building data)"); HL("Hazard-layer<br/>(tsunami inundation)"); GS("Geospatial matching<br/>(sampling)"); EL --> GS; HL --> GS; PY("Python function"); GS --> CA("Consequence Analysis"); PY -.-> CA; CA --> REP("Report Event<br/>Impact results"); %% Styling class EL,HL rs-box-navy style EL color:#FFF style HL color:#FFF class CA,GS rs-box class REP rs-box-green class PY rs-box-optional

So for example, the input-exposures.layer parameter specifies the input data that we will use for our exposure-layer (our buildings shapefile). Similarly, the input-hazards.layer parameter specifies the hazard-layer input data for our model (our tsunami inundation GeoTIFF).

The sample.hazards-by parameter specifies how to spatially sample the hazard-layer. This determines how RiskScape geospatially matches elements-at-risk in your exposure-layer to the hazard-layer.

We will look at spatial sampling in more detail in subsequent tutorials. For now, ‘closest’ just means that RiskScape will match any hazard value that intersects an element-at-risk.

Finally, the analysis.function parameter specifies a function that will determine the impact, or consequence, that the hazard has on each element-at-risk.

In general, you will want to use your own Python function to do the analysis. For now, we are using a built-in RiskScape function called is_exposed, which simply determines whether or not a building is exposed to the hazard. The resulting consequence will be 1 (representing true) if the building is exposed, and 0 (representing false) if not.

This basic-exposure model does not change how the event impact results are reported, but we will look at that more later.

Running the model

To run this basic-exposure model, enter the following command into your terminal prompt.

riskscape model run basic-exposure

The model should take a few seconds to run. RiskScape prints out a progress meter as it runs your model. The numbers displayed correspond to rows of data processed. For more detail on what these numbers mean, refer to Progress statistics.


If the RiskScape command produced an error, try checking that riskscape -V runs without any errors, and that the current directory in your command prompt is in the unzipped models-intro directory that contains the project.ini file.

When RiskScape has finished it will display the output file produced, which contains the results of the model. By default, RiskScape saves its results to an output/MODEL_NAME/TIMESTAMP/ sub-directory within the current working directory, e.g. ./output/basic-exposure/2021-11-10T15_09_25/event_impact_table.shp

Open the event_impact_table.shp in your preferred GIS application, e.g. QGIS. At first glance, this data looks exactly the same as the exposure-layer we started with. However, if you open the attribute table, you will see each element-at-risk now has a hazard value, which is the tsunami inundation height, and a consequence, which is 0 or 1 depending on whether the building was exposed to the tsunami.

Changing the model outputs

RiskScape commands can also accept additional CLI options that change the way the command behaves.

For the riskscape model run command, CLI options can change the way results are generated. The CLI options always have dashes (i.e. - or --) in front of them, and are always specified on the end of the riskscape model run command.

For example, if you want to change the default output location that RiskScape uses, you can use the --output, or -o command-line option. Try running the following command, which will save the output files directly to a results_dir sub-directory.

riskscape model run basic-exposure --output results_dir

By default, RiskScape will never overwrite any existing results files when you use the --output option. Try running the same command again - this time, the filename gets a number appended, i.e. analysis-1.shp.

You can use the --replace, or -r option to always overwrite the previous results from a model. For example:

riskscape model run basic-exposure --output results_dir --replace

Because the results for the basic-exposure model contain geometry, RiskScape will default to saving the results in shapefile format.

To change the default file format that results get saved in, use the --format, or -f option. For example, to save the results as Comma-Separated Values (CSV) file, use:

riskscape model run basic-exposure --format csv

You can use --help on the end of a RiskScape command to find out more about what CLI options are supported. See if you can work out what other formats RiskScape can save your results in.

riskscape model run --help


Many RiskScape CLI options have both a long option (e.g. --format) and a short alternative (e.g. -f). The short option is always a single character and always has a single dash. Whereas the long option will always be full words and always has two dashes.

Reporting the model results

The basic-exposure model produces an Event Impact Table, which simply contains the consequence, if any, that the hazard had on each element-at-risk.

We can customize how the event impact table is saved, which lets us report the effects of the hazard in a range of useful ways.

Now let’s look at the exposure-reporting model in the project.ini file. This is exactly the same as the basic-exposure model we ran previously, except it has extra parameters to report the event impact table in different ways.

[model exposure-reporting]
description = Model with additional reporting options that alter how the results are saved
framework = wizard
input-exposures.layer = data/Buildings_SE_Upolu.shp
input-hazards.layer = data/MaxEnv_All_Scenarios_50m.tif
sample.hazards-by = CLOSEST
analysis.function = is_exposed
report-event-impact.filter = consequence = 1[0] = summary[0] = 'Total' as Results
report-summary.aggregate[0] = count(hazard) as Number_Exposed
report-summary.aggregate[1] = count(exposure) as Total_buildings
report-summary.aggregate[2] = max(hazard) as Max_hazard
report-summary.aggregate[3] = mean(hazard) as Average_hazard
report-summary.format = csv

Try running the exposure-reporting model using the following command:

riskscape model run exposure-reporting

This model produces two results files in a output/exposure-reporting/TIMESTAMP/ sub-directory:

  • event-impact.shp: This contains only the elements-at-risk that were exposed to the hazard. Try opening the file in QGIS. It makes it a bit easier to visualize which buildings in the original exposure-layer were affected by the tsunami.

  • summary.csv: This summarizes the effects of the tsunami, reporting the total number of buildings that were exposed. The maximum and average tsunami inundation depths for affected buildings has also been included.

Try opening the summary.csv file, either in a spreadsheet application or use the more "FILENAME" command to display the file contents from the command prompt. It should look like this:

more "output/exposure-reporting/2021-11-11T11_35_02/summary.csv"


Forward slashes in file-paths generally work OK in the Windows Command Prompt, as long as you surround them in double-quotes, e.g. "output/some-file.csv". This means you can copy-paste the results filename from the URI that RiskScape displays. Simply select the text and use Ctrl + c and Ctrl + v to copy-paste in the Windows Command Prompt.

Model parameters

So far we have been customizing the model’s behaviour using parameters saved in the INI file. However, you can also change the model’s parameters on the fly, using the command line.

To change a parameter in a model we use the --parameter CLI option, or -p for short.


You can view all the parameters that are available in a model using the riskscape model list command.

Changing the input data

As we saw in the Getting started modelling in RiskScape guide, we can change the hazard-layer that our model uses from a 50-metre grid to a 10-metre grid.

When changing a parameter, you specify the parameter’s value in the format -p "PARAMETER_NAME=VALUE". In this case, the hazard-layer input parameter is called input-hazards.layer, and the value is the 10m grid file we want to use, data/MaxEnv_All_Scenarios_10m.tif.

Try entering the following command to use the 10m grid hazard-layer in our model instead.

riskscape model run exposure-reporting -p "input-hazards.layer=data/MaxEnv_All_Scenarios_10m.tif"

Now open the summary.csv file that was produced. It should look like this:


The same number of buildings were run through the model (i.e. Total_buildings), but now fewer buildings are reported as being exposed to the tsunami (i.e. Number_exposed) compared with previously.

Input data attributes

You can think of the data in a RiskScape model as being a bit like a big spreadsheet - each row of data represents an element-at-risk from the exposure-layer, and the columns represent attributes associated with the element-at-risk. As the input data moves through the model, the rows and columns can change.

The model data starts off with the exposure-layer input data. So any building attribute that is present in the input data can be used later in the model.

You can use the following command to display more information about our buildings database file, data/Buildings_SE_Upolu.shp:

riskscape bookmark info "data/Buildings_SE_Upolu.shp"

The attributes that are present in the file will be displayed at the top of the output, e.g.

Location : file:///C:/RiskScape_Projects/models-intro/data/Buildings_SE_Upolu.shp
  Attributes  :
  Axis-order  : long,lat / X,Y / Easting,Northing
  CRS code    : EPSG:32702
  CRS (full)  : PROJCS["WGS_1984_UTM_Zone_2S",
      SPHEROID["WGS_1984", 6378137.0, 298.257223563]],
    PRIMEM["Greenwich", 0.0],
    UNIT["degree", 0.017453292519943295],
    AXIS["Longitude", EAST],
    AXIS["Latitude", NORTH]],
  PARAMETER["central_meridian", -171.0],
  PARAMETER["latitude_of_origin", 0.0],
  PARAMETER["scale_factor", 0.9996],
  PARAMETER["false_easting", 500000.0],
  PARAMETER["false_northing", 10000000.0],
  UNIT["m", 1.0],
  AXIS["x", EAST],
  AXIS["y", NORTH]]
  Row count   : 6260
  Bounds      : EPSG:32702 [410019.3061 : 454991.3475 East, 8445166.5924 : 8464016.1628 North] (original)
  Bounds      : EPSG:4326 [-171.8334 : -171.4166 East, -14.0639 : -13.8924 North]

We can see the building database has the attributes the_geom, Use_Cat, Cons_Frame, area, and perimeter.

RiskScape groups together attributes that come from the same input layer. You can refer to an attribute from a given input layer in your RiskScape model using the format LAYER_NAME.ATTRIBUTE_NAME. For example, to refer to the Use_Cat exposure-layer attribute you would use exposure.Use_Cat.

Changing the output data

By changing model parameters, we can also change how the model results are reported.

For example, currently our model is aggregating (i.e. collating or summarizing) the results across all buildings exposed. Instead, we can group the results by the building attribute we are interested in, such as its use category (i.e. exposure.Use_Cat) or its construction type (i.e. exposure.Cons_Frame).

The model parameter that groups the results for the summary.csv report is[0]. The [0] part of the parameter just means you can group the results by multiple things.

Try running the following command, which groups against the building’s use-category attribute (exposure.Use_Cat).

riskscape model run exposure-reporting -p "[0]=exposure.Use_Cat"

Now look at the summary.csv file that was produced. It should contain the following:

Religious - not verified,0,2,,
Commercial - not verified,1,3,1.5244611501693726,1.5244611501693726
Hotel - not verified,0,1,,
Community - not verified,2,6,5.375617504119873,5.0066187381744385
Tourist Fale,107,157,6.352619171142578,3.8892281768477965
Commericial - not verified,1,1,5.397562026977539,5.397562026977539

We now get a breakdown of the buildings exposed to the tsunami based on what the building is used for.

Changing other model assumptions

The model’s summary.csv report currently includes buildings that were exposed to any tsunami inundation. We could filter the results so that only buildings that were exposed to a certain hazard threshold are counted in the summary.

The model parameter that filters the results for the summary.csv report is report-summary.filter. The inundation depth appears in the model data as the hazard attribute, so hazard >= 0.5 would only include results that have a minimum inundation depth of 0.5m.

Try running the following command, to filter the results based on the inundation depth.

riskscape model run exposure-reporting -p "report-summary.filter=hazard >= 0.5"

Now look at the summary.csv file that was produced.


You can see that the Number_Exposed is now less than it was previously (2059). It has now excluded 345 buildings that were exposed to an inundation depth of 0.5m or less.


The Total_buildings used to be 6260, but now it is 1714, the same as Number_Exposed. This is because the filter condition applies before the Total_buildings count is calculated. There are 4546 buildings that do not meet the filter condition, i.e. that are unexposed or exposed to less than 0.5m of inundation. These unexposed buildings are now excluded from the summary results, and so no longer included in the Total_buildings count.

Aggregating by area-layer

A useful way to view your model results is to aggregate them by a regional boundary of interest, i.e. an area-layer. For example, you might be interested in how the impact from a hazard affects a specific district or particular towns.

We will look at how our tsunami hazard affects the different regions of south-eastern Upolu by using an area-layer of the Samoan electoral constituencies (Samoa_constituencies.shp).

Try running the exposure-by-region model using the following command.

riskscape model run exposure-by-region

This model produces an event-impact.csv results file in the output/exposure-by-region/TIMESTAMP/ sub-directory. This event-impact.csv contains our event impact table aggregated by region, which looks like this:

Aleipata Itupa i Lalo,0,332
Aleipata Itupa i Lalo,1,531
Aleipata Itupa i Luga,0,210
Aleipata Itupa i Luga,1,345
Anoamaa East,0,322
Anoamaa West,0,32
Vaa o Fonoti,0,405
Vaimauga West,0,101

This time there are up to two rows for each region - one row for exposed buildings (i.e. Exposed_Status == 1) and another row for unexposed buildings (i.e. Exposed_Status == 0)


Many of the electoral constituencies from the area-layer are not included in the results - only regions that overlapped with our exposure-layer’s elements-at-risk were included, and our exposure-layer only covers south-eastern Upolu.

Specifying an analysis function

So far we have been using a built-in RiskScape function called is_exposed to analyse the consequence that the hazard-layer has on each element-at-risk (which is simply 1 if the building is exposed, 0 if not).

You can define your own Python function that RiskScape will use to analyse the impact of the hazard. This means your RiskScape model can do whatever risk analysis you want it to.

In your project directory there is a functions/ file that contains the following Python code:

def function(building, hazard_depth):
    if hazard_depth is None or hazard_depth <= 0:
        return 'Not exposed'

    if hazard_depth > 3.0:
        status = 'Exposure >3.0m'
    elif hazard_depth > 2.0:
        status = 'Exposure >2.0m to <=3.0m'
    elif hazard_depth > 1.0:
        status = 'Exposure >1.0m to <=2.0m'
        status = 'Exposure >0.0m to <=1.0m'

    return status

This is a simple Python function that assigns a status to each element-at-risk based on the depth of inundation that the building was exposed to.

Note that in order to use a Python function in your model, we have to first tell RiskScape about the function. In the project.ini file, we have the following entry that adds the Python function to RiskScape:

[function exposure_status]
description = A simple function to evaluate a building's exposure status to tsunami inundation
location = functions/
argument-types = [ building: anything, hazard_depth: nullable(floating) ]
return-type = text

This tells RiskScape things like the function’s name (exposure_status) and the Python file to use. You will learn more about what this INI definition means, and how to add your own functions, in a later tutorial.

Now try using this exposure_status function in a model by running the following command:

riskscape model run exposure-by-region -p "analysis.function=exposure_status"

Open the event-impact.csv file produced. You can now see a more detailed breakdown of how many buildings in each region were exposed to different tsunami inundation depths.

Aleipata Itupa i Lalo,Exposure >0.0m to <=1.0m,89
Aleipata Itupa i Lalo,Exposure >1.0m to <=2.0m,154
Aleipata Itupa i Lalo,Exposure >2.0m to <=3.0m,166
Aleipata Itupa i Lalo,Exposure >3.0m,122
Aleipata Itupa i Lalo,Not exposed,332
Aleipata Itupa i Luga,Exposure >0.0m to <=1.0m,74
Aleipata Itupa i Luga,Exposure >1.0m to <=2.0m,21
Aleipata Itupa i Luga,Exposure >2.0m to <=3.0m,42
Aleipata Itupa i Luga,Exposure >3.0m,208
Aleipata Itupa i Luga,Not exposed,210
Anoamaa East,Not exposed,322
Anoamaa West,Not exposed,32
Falealili,Exposure >0.0m to <=1.0m,225
Falealili,Exposure >1.0m to <=2.0m,166
Falealili,Exposure >2.0m to <=3.0m,150
Falealili,Exposure >3.0m,208
Falealili,Not exposed,1013
Lepa,Exposure >0.0m to <=1.0m,41
Lepa,Exposure >1.0m to <=2.0m,31
Lepa,Exposure >2.0m to <=3.0m,76
Lepa,Exposure >3.0m,140
Lepa,Not exposed,232
Lotofaga,Exposure >0.0m to <=1.0m,44
Lotofaga,Exposure >1.0m to <=2.0m,22
Lotofaga,Exposure >2.0m to <=3.0m,38
Lotofaga,Exposure >3.0m,42
Lotofaga,Not exposed,277
Safata,Not exposed,595
Siumu,Not exposed,682
Vaa o Fonoti,Not exposed,405
Vaimauga West,Not exposed,101


Let’s review some of the key points we have covered so far:

  • All the instructions RiskScape needs to run a model are stored in a plain-text project.ini INI file.

  • A RiskScape model combines together various geospatial layers and performs some risk analysis.

  • RiskScape models are run from the command line. You can run a saved model multiple times, and change the file format or location where the model results are saved.

  • You can vary a model’s parameters in order to change the input data files used, or other aspects of how the model works.

  • A RiskScape model produces an event impact table. You can customize how the event-impact table is reported, or save the same model results in multiple different ways.

  • Aggregation is a useful way to report the model results in a meaningful way. The model’s area-layer lets you aggregate results by a regional boundary.

  • The RiskScape model uses a function to analyse the consequence the hazard has on the exposure-layer. You can specify your own Python function to perform this consequence analysis.


The models used in this tutorial are generally applicable for reuse. By changing the exposure-layer and hazard-layer, you can use them to model how any elements-at-risk are exposed to a hazard, particularly a hazard-layer in .asc or .tif format.

Once you feel comfortable with running models, you could try the next tutorial on How to build RiskScape models.

Extra for experts

If you want to play around with running models a little more, you could try the following:

  • Try running the basic-exposure model so that the results are produced in GeoJSON format.

  • Try grouping the exposure-reporting results by the Cons_Frame exposure-layer attribute (i.e. exposure.Cons_Frame). Open the summary.csv file that gets produced and see what difference this makes to the results.

  • Try running the exposure-reporting with a filter parameter so that the event-impact.shp results only includes buildings that were exposed to 1m of inundation or greater. Hint: the filter will apply to the event-impact report (i.e. report-event-impact.filter) rather than the summary report (i.e. report-summary.filter). Open the event-impact.shp results in QGIS and compare it with the original building database layer.

  • Use the riskscape bookmark info to work out what attributes are present in the data/Samoa_constituencies.shp file. Open the shapefile’s attribute table in QGIS and check that the attributes match RiskScape’s output.

  • Try running the exposure-by-region model with -p "[2]=exposure.Cons_Frame". This groups the results by the building construction type, as well as the region and consequence. Look at the event-impact.csv results file that gets produced. What are most affected buildings constructed from? Does it vary at all by region?

  • Try modifying the project.ini file so that the exposure-by-region always uses the exposure_status function by default, rather than the is_exposed function. Run the exposure-by-region model again (without specifying any model parameters on the command-line), and check the event-impact.csv results file now contains the Exposure >X.0m consequences.

  • Open the functions/ file in a text editor and try modifying it. Add an extra elif statements so that the >0.0m to <=1.0m status is split into two: >0.5m to <=1.0m and >0.0m to <=0.5m. Run the exposure-by-region model again and check that you see the new status in the results file.

  • Enter riskscape model list and look at the parameters for the exposure-by-region model. Currently the model sorts the output by region name. See if you can work out the model parameter that sorts the results. Try running the model so that it sorts the output by the Total_buildings value instead. Open the event-impact.csv file that gets produced and check what order the results are in.

  • Try running the exposure-by-region model so it reports the exposure status for all of Upolu, rather than by region. This is a little awkward to do currently with wizard models, but try changing the[0] parameter to group by constant value, e.g. 'Upolu' as Region. See what this does to the event-impact.csv results that get produced.