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 GIS software (e.g. QGIS) installed that you can use to view shapefile and GeoTIFF files.
ArcGIS users should read Workarounds for ArcGIS before proceeding. It lists tips to ensure that geospatial data is projected correctly in ArcGIS.
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
Click here to download the input data we will use in these examples.
Unzip the file into a new directory, e.g.
Open a command prompt and use
cd to change directory to where you unzipped the files, e.g.
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
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_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.
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.
project.ini file in a text editor, such as Notepad or
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:
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
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.
"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:
So for example, the
input-exposures.layer parameter specifies the input data that we will use for our exposure-layer (our buildings shapefile).
input-hazards.layer parameter specifies the hazard-layer input data for our model (our tsunami inundation GeoTIFF).
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.
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.
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
directory that contains the
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
within the current working directory, e.g.
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
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.
riskscape model run command, CLI options can change the way results are generated.
The CLI options always have dashes (i.e.
--) 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
-o command-line option.
Try running the following command, which will save the output files directly to a
riskscape model run basic-exposure --output results_dir
By default, RiskScape will never overwrite any existing results files when you use the
Try running the same command again - this time, the filename gets a number appended, i.e.
You can use the
-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
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.
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
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
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 reports.name = summary report-summary.group-by = 'Total' as Results report-summary.aggregate = count(hazard) as Number_Exposed report-summary.aggregate = count(exposure) as Total_buildings report-summary.aggregate = max(hazard) as Max_hazard report-summary.aggregate = 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
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
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" Results,Number_Exposed,Total_buildings,Max_hazard,Average_hazard Total,2059,6260,8.218506813049316,2.5090660887936354
Forward slashes in file-paths generally work OK in the Windows Command Prompt, as long as
you surround them in double-quotes, e.g.
This means you can copy-paste the results filename from the URI that RiskScape displays.
Simply select the text and use
v to copy-paste in the Windows
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
In this case, the hazard-layer input parameter is called
and the value is the 10m grid file we want to use,
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,
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 : the_geom[MultiPolygon[crs=EPSG:32702]] Use_Cat[Text] Cons_Frame[Text] area[Floating] perimeter[Floating] Axis-order : long,lat / X,Y / Easting,Northing CRS code : EPSG:32702 CRS (full) : PROJCS["WGS_1984_UTM_Zone_2S", GEOGCS["GCS_WGS_1984", DATUM["D_WGS_1984", SPHEROID["WGS_1984", 6378137.0, 298.257223563]], PRIMEM["Greenwich", 0.0], UNIT["degree", 0.017453292519943295], AXIS["Longitude", EAST], AXIS["Latitude", NORTH]], PROJECTION["Transverse_Mercator"], 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]] Summarizing... 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
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
For example, to refer to the
Use_Cat exposure-layer attribute you would use
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.
The model parameter that groups the results for the
summary.csv report is
 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 (
riskscape model run exposure-reporting -p "report-summary.group-by=exposure.Use_Cat"
Now look at the
summary.csv file that was produced. It should contain the following:
Use_Cat,Number_Exposed,Total_buildings,Max_hazard,Average_hazard Outbuilding,623,1343,7.879426002502441,2.331427180173883 Residential,930,1862,7.718549728393555,2.2250018423603426 Industrial,6,8,3.821390390396118,2.7654923796653748 Religious - not verified,0,2,, Fale,111,146,8.096136093139648,2.7053862896051495 Commercial,14,51,7.13636589050293,3.719742706843785 Commercial - not verified,1,3,1.5244611501693726,1.5244611501693726 Religious,28,60,5.8724517822265625,1.8323415092059545 Hotel - not verified,0,1,, Community - not verified,2,6,5.375617504119873,5.0066187381744385 Hotel,198,226,8.218506813049316,3.390313490472659 Education,12,12,5.941905975341797,3.395870625972748 Tourist Fale,107,157,6.352619171142578,3.8892281768477965 Commericial - not verified,1,1,5.397562026977539,5.397562026977539 Community,23,26,6.209683418273926,3.2658567169438237 ,3,2356,1.9251530170440674,1.3111796379089355
We now get a breakdown of the buildings exposed to the tsunami based on what the building is used for.
Changing other model assumptions
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
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.
Total_buildings used to be
6260, but now it is
1714, the same as
This is because the filter condition applies before the
Total_buildings count is calculated.
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
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 (
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
event-impact.csv contains our event impact table aggregated by region, which looks like this:
Region,Exposed_Status,Total_buildings 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 Falealili,0,1013 Falealili,1,749 Lepa,0,232 Lepa,1,288 Lotofaga,0,277 Lotofaga,1,146 Safata,0,595 Siumu,0,682 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/exposure.py 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' else: 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.
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/exposure.py 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"
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.
Region,Exposed_Status,Total_buildings 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
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
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-exposuremodel so that the results are produced in GeoJSON format.
Try grouping the
exposure-reportingresults by the
Cons_Frameexposure-layer attribute (i.e.
exposure.Cons_Frame). Open the
summary.csvfile that gets produced and see what difference this makes to the results.
Try running the
exposure-reportingwith a filter parameter so that the
event-impact.shpresults 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.shpresults in QGIS and compare it with the original building database layer.
riskscape bookmark infoto work out what attributes are present in the
data/Samoa_constituencies.shpfile. Open the shapefile’s attribute table in QGIS and check that the attributes match RiskScape’s output.
Try running the
-p "report-event-impact.group-by=exposure.Cons_Frame". This groups the results by the building construction type, as well as the region and consequence. Look at the
event-impact.csvresults file that gets produced. What are most affected buildings constructed from? Does it vary at all by region?
Try modifying the
project.inifile so that the
exposure-by-regionalways uses the
exposure_statusfunction by default, rather than the
is_exposedfunction. Run the
exposure-by-regionmodel again (without specifying any model parameters on the command-line), and check the
event-impact.csvresults file now contains the
functions/exposure.pyfile in a text editor and try modifying it. Add an extra
elifstatements so that the
>0.0m to <=1.0mstatus is split into two:
>0.5m to <=1.0mand
>0.0m to <=0.5m. Run the
exposure-by-regionmodel again and check that you see the new status in the results file.
riskscape model listand look at the parameters for the
exposure-by-regionmodel. 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_buildingsvalue instead. Open the
event-impact.csvfile that gets produced and check what order the results are in.
Try running the
exposure-by-regionmodel 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
report-event-impact.group-byparameter to group by constant value, e.g.
'Upolu' as Region. See what this does to the
event-impact.csvresults that get produced.