Customizing the model run form
This document specifies how an expert user would setup their project.ini
file so that it’s easier for non-expert users to configure and run models in the RiskScape Platform.
Currently we define a parameter and its default value in the project.ini.
Defining parameters is currently only supported for pipeline models.
For example, to define a parameter called perils, we can use:
param.perils = ['EQ', 'TS', 'TC']
Labels and help descriptions
By default the parameter name will be displayed in the UI.
This will be improved somewhat, e.g. by default, the loss-type parameter would be displayed
in the web UI as Loss type.
To display a nicer label for a parameter in the UI, you could add something like the following
line to your project.ini file:
param.perils.label = Select which perils to include in the analysis.
You could also specify more detailed help text that would be available, e.g.
param.perils.description = \
Tropical Cyclone includes wind and storm surge \
losses produced by tropical cyclones. \
Earthquake includes losses from ground shaking...
This will appear as a 
help icon in the RiskScape Platform.
When the user clicks on the icon, it will bring up the description as a pop-up modal.
Note
The help text gets rendered in the web UI as one big unformatted text block currently. No bold or italics formatting is supported, nor are paragraph breaks.
When the description spans multiple-lines you will need a \ backslash at the end of
each line, except for the last line. The \ is a line-continuation character that is
part of the standard INI file format. It can be simpler to specify the description
across multiple lines like this:
param.perils.description = Tropical Cyclone includes wind and storm surge
param.perils.description = losses produced by tropical cyclones.
param.perils.description = Earthquake includes losses from ground shaking...
Properties
Properties give you a flexible way to control the input fields on the UI. For example, you could use the parameter properties to hide a parameter you don’t really want users to know about:
param.return_periods.properties = hidden
Or you could mark the field as read-only, so users can see the setting, but cannot change the value by default.
param.return_periods.properties = readonly
Tip
Properties can also convey information about the type of value we expect, which we will look at next.
Numeric values
Currently pipeline parameters can be any expression, e.g. they could be exposure.foo, 'bar', or
3.14. There is no checking that the parameter is the correct type, which means the user could specify
a text string where a numeric value is expected.
To improve this, you can specify the type of value that you want the expression to be. For example, where you require something to be a numeric value, you can specify:
param.shaking_percentile.properties = numeric
Note
These type-based properties do not 100% match the RiskScape types.
For example, many RiskScape expressions would accept either an integer or a floating,
but the RiskScape type system forces you to explicitly pick one, rather than instead just
saying it should be a numeric value.
Tip
Type-based properties like this only work for constant or fixed values (also known as literal
values in programming languages). This means that for a properties = numeric
parameter, the constant value 10 would be accepted, but an expression that results in an integer,
such as exposure.road_length, would be rejected.
Tip
In some situations, RiskScape will display large numbers with commas for readability (e.g. 1,024). If you wish to disable this behaviour, you can simply add the unformatted property to the parameter. This is useful for displaying years - 2024 rather than 2,024.
Select/drop-down parameters
In the perils example, there is a predefined list of possible choices that the user can enter.
Instead of the user having to type out 'EQ' manually and getting it exactly right,
it’d be nicer to give them a drop-down list of choices.
Adding the following would turn the UI parameter into a drop-down/select box:
param.perils.choices = 'TC'
param.perils.choices = 'EQ'
param.perils.choices = 'TS'
The choices would be displayed to the user with the 's stripped off, i.e. TC, EQ, or TS.
However, to make this more meaningful, you can specify a more user-friendly label for each option, E.g.
param.perils.choices = "Tropical Cyclone": 'TC'
param.perils.choices = Earthquake: 'EQ'
param.perils.choices = Tsunami: 'TS'
Here, the UI user will see the Tropical Cyclone label instead of TC in the drop-down.
Note
Labels containing spaces will need "" double-quotes around them.
The label "Tropical Cyclone" is valid, but specifying the same thing without quotes
(i.e. Tropical Cyclone) would be rejected.
You can alternatively specify all the choices together on the same line. Just make sure a comma separates each choice, e.g.
param.perils.choices = "Tropical Cyclone": 'TC', Earthquake: 'EQ', Tsunami: 'TS'
Generally, it is simpler and clearer to specify each choice on a separate line.
Note
Specifying the choices is similar syntax to RiskScape struct and list expressions,
however, it is not exactly the same.
Do not use { } or [ ] characters when specifying choices in the project.ini file,
unless the underlying pipeline specifically requires the expressions to be in that form.
Multi-select parameters
In this case the perils parameter can have a list of values.
So we want the user to be able to make multiple selections in the UI, i.e. a set of check-boxes instead of a drop-down.
We could control this behaviour via a property, e.g.
# for a multiselect input:
param.perils.properties = multiselect
# or for checkbox inputs:
param.perils.properties = checkbox
Note
Your pipeline code always needs to accept a list type when multiselect or checkbox is used for a parameter.
Inferring properties from default values
If you do not specify any properties for a parameter, RiskScape will sometimes infer properties from the default value. For example, take the following parameter:
param.return_periods = [ 50, 100, 500 ]
RiskScape can infer this is a list and numeric, and therefore it should probably be a multiselect
input field in the Platform UI.
Currently these inferred properties are used in the Platform UI, but they will not result in
model run errors if you enter a different value. For example, you can still enter something like
-p "return_periods=exposure.return_periods", where the value is not a numeric list, without any errors.
If you do not like the inferred properties, you can override them by specifying any property for a parameter. For example:
param.foo.properties = expression
# or alternatively just use a plain text-box input field in the Platform UI:
param.foo.properties = textbox
Parameter templates
In order to avoid repetition in your project.ini file, you can define a parameter template
separately that then gets reused for multiple parameters in your models. For example:
[parameter percentile]
properties = integer, min: 1, max: 99
label = Enter a percentile
description = This should be a whole number between 1 and 99
Everywhere a model takes a percentile parameter, you can simply refer to this template, e.g.
param.shaking_percentile.template = percentile
This means we only had to enter one line of configuration for this parameter instead of three lines.
Tip
If your parameter has the same name as a parameter template, it will automatically use that template,
i.e. any $percentile model parameters will automatically use the percentile template.
You can also override parts of the template with more specific details for a parameter. This lets you refine the label or description used for a parameter, e.g.
param.shaking_percentile.template = percentile
# this next line overrides the parameter's label with a more specific one
param.shaking_percentile.label = Enter the percentile of shaking to model
You can also give templates a default value. This will be used if the parameter does not provide a value. If the value
is a file path (i.e. has the property bookmark or file), and begins with ./, then it will be resolved relative to the
file it was defined in. This means you can have your shared parameter template and default data in a different location
to the models that use it.
Bookmark parameters
By specifying a parameter is a ‘bookmark’ type, it means you no longer need to specify single-quotes for the file-path. For example:
param.portfolio = buildings.csv
param.portfolio.properties = bookmark
The validation of the portfolio parameter now behaves the same way as
specifying an input file for a wizard model - RiskScape checks that the specified
value is a valid file that can be successfully read as input data.
The main benefit to using the bookmark property is that it will give you an
‘input file chooser’ widget on the model run form. For example, when opened,
the file chooser will look like this:
The other thing to note is the value inserted into your model pipeline
will always be a bookmark expression when this property is used,
e.g. bookmark('buildings.csv') will be inserted into the pipeline code in this case.
This will generally result in your pipeline code being slightly simpler,
as it means one less bookmark() function call you have to write yourself.
For example, instead of writing:
select({ *, sample_one(exposure, to_coverage(bookmark($regions))) as region })
You can now instead simply use:
select({ *, sample_one(exposure, to_coverage($regions)) as region })
Note
The file parameter property will also give you the file input chooser widget,
but it won’t try to turn the given value into a bookmark expression. This can be
handy if you want to build the bookmark expression in your pipeline - for example,
you might also want to use other model parameters in the same bookmark expression.
Bookmark templates
You can also specify a template bookmark that represents the format that you expect the input data to be in. This is useful when the input data always follows the exact same layout, but the values within the file may differ.
For example, if you had a building portfolio that gets updated yearly,
then you might have several different files that all contain very similar data.
These files may share common qualities, such as
CSV files that contain well-known-text (WKT) in EPSG:4326 long,lat format,
as well as a Replacement_Cost column name that contains integer values.
You could define this using the following bookmark:
[bookmark building_data]
location = placeholder.csv
crs-name = EPSG:4326
crs-longitude-first = true
set-attribute.geom = geom_from_wkt(WKT)
set-attribute.Replacement_Cost = int(Replacement_Cost)
You could then add the following model parameter, which will expect a
CSV file-path that conforms to the building_data bookmark:
param.portfolio = buildings.csv
param.portfolio.properties = bookmark-template: building_data
In this case, the location of the building_data bookmark will be swapped out
for the file-path specified. For example, the default parameter value of buildings.csv
will be inserted into the pipeline code as bookmark('building_data', { location: 'buildings.csv' }).
Bookmark types
The bookmark-template approach is useful in some cases, but can be limiting in others.
For example, say you had alternative building data, but it was a shapefile rather than a CSV file,
or say the data contained a replacement cost, but the attribute was called Rateable_Value.
In these cases, your model would be incompatible with the alternative building data.
In this case, we want to support uploading bookmark data, but also map the data format to what we expect.
We can do this by using a RiskScape type that describes the data we expect, e.g.
[type building]
type.geom = geometry
type.Replacement_Cost = integer
In the parameter properties, you then specify the type that you expect the bookmark data to have, e.g.
param.portfolio = building_data
param.portfolio.properties = bookmark, type: building
If the user uploads a data source with different attributes, they will be presented with UI widgets for mapping the attributes in the input data to the type that is expected. For example:
This is useful for dealing with geospatial data (GeoPackage, GeoJSON, etc) where the names used for the input data attributes can vary.
However, it is less useful for CSV-based data, as it does not support WKT or lat,long conversion into geometry currently.
Available properties
Below is a list of the properties that you can configure for parameters.
Properties for constant values
These properties are useful when you want the user to specify a constant or fixed value of a particular type (e.g. they should always enter a numeric value). Typically you only want to pick one property from the table below.
Property |
Description |
|---|---|
expression |
The parameter accepts any expression. RiskScape can sometimes infer what type of values should be accepted (e.g. numeric values). Specifying |
integer |
The parameter only accepts whole numbers, e.g. year of construction. |
list |
The parameter only accepts list expressions, e.g. |
numeric |
The parameter only accepts constant numeric values (can be |
text |
The parameter only accepts constant text strings. RiskScape will automatically add single-quotes so that it is a valid expression, e.g. entering |
Note
Using these parameter properties will result in model run errors if the user enters an incorrect value,
such as text instead of a numeric value, or if a non-constant expression is used,
such as exposure.road_length or 3.14 * 2.
Input field properties
These properties describe what sort of input field the user should get in the web UI form
for a given parameter, e.g. textbox, dropdown, etc. Typically you only want to pick one property from the table below.
Property |
Description |
|---|---|
|
Adds a file input chooser to the UI. The user-specified value will be turned into a |
|
Requires that |
|
Requires that |
|
Adds a file input chooser to the UI. The user-specified value will be turned into a text string |
|
Hide the parameter by default, so it does not appear in the web UI form |
|
The user can enter multiple values. These either come from a set of pre-defined choices, or as free-form numeric values |
|
The user can see this parameter by default, but cannot change its value in the web UI |
|
A simple |
Tip
To get the ‘attribute mapping’ widget for an input data file, use the type property in the next section below.
Key-value properties
These properties help validate that the user has provided an appropriate input value.
For example, when specifying a percentile parameter, -1 is a valid integer, but not an appropriate value to use.
These properties are typically specified as a key-value pair, e.g. min: 1 or max: 99.
You can generally specify multiple properties from the table below.
However, some properties are incompatible with other type-based properties, e.g. min and bookmark cannot be used together.
Property |
Description |
|---|---|
bookmark-template |
Specifies the ID of an existing bookmark. The value specified for the parameter must conform to (i.e. be compatible with) that bookmark |
type |
Specifies the ID of an existing type. The bookmark value specified for the parameter must conform to (i.e. be compatible with) that type |
min |
Only supported for numeric parameters. Checks that the user enters a value that is greater than or equal to a specified minimum |
max |
Only supported for numeric parameters. Checks that the user enters a value that is less than or equal to a specified maximum |
step |
Only supported for numeric parameters, when |
Note
Some of these properties, like min and max, will result in model run errors
if the user enters a value that falls outside that range.
.