As we’ve covered in the Overview, RiskScape combines data sources, functions, and type information into a hazard model. We call these various model inputs RiskScape Resources.
We use INI files to tell RiskScape
about the resources that we want to use in our model.
INI files are simple text files that you can modify with any basic text editor (e.g. Notepad).
Usually the filenames end in
.ini, but they don’t always have to.
A RiskScape Project is the complete set of INI configuration needed to run one or more models. In the same way you use folders or directories to organize the files on your computer, you can use project INI files to organize your RiskScape models.
RiskScape loads your project’s INI configuration from a file that’s usually called
project.ini file can itself load other INI files (e.g.
For a hands-on walk-through on creating your own project.ini, see the Creating a RiskScape project tutorial.
Organizing your resources
The point of RiskScape projects is to sensibly organize the numerous resources required for running multiple different models.
Different models may use different data sources, which may require their own set of corresponding types. You may also need customized functions that suit a specific hazard model. For example, modelling a flood in the Bay of Plenty will require different INI configuration to modelling an earthquake in Indonesia.
In general, we recommend:
Use clearly-named directories to keep related model files together.
Have a single file called
project.iniin each directory. For example:
C:\RiskScape_Projects\Whakatane_flood\project.ini C:\RiskScape_Projects\Sumatra_quake\project.ini ...
Project file format
The INI file sections are marked by square brackets and are in the format
where thing can be
function, and name is whatever you want to call it.
The lines that then follow are its definition. For example, the following section defines a new type called ‘building’.
[type building] type.shape = geometry type.territorial_authority = text
The top of your
project.ini file should have a
This is where you can load configuration from other INI files, if necessary.
You can also include a description here of what the project is for. For example:
[project] description = My cool hazard modelling models = models.ini bookmarks = bookmarks.ini
Default project file
By default, RiskScape will always try to use the
project.ini file in the current directory you are working in.
(i.e. this is the
PWD variable in most terminals).
Many RiskScape commands will not work correctly if no
project.ini file is present.
For example, you cannot run a model unless you have a
project.ini file to tell RiskScape about your models.
If RiskScape cannot find a
project.ini file present, then you will see a warning like this when you run some RiskScape commands:
WARNING: There is no project.ini file present in the current directory. Please either `cd` to the directory containing your RiskScape project.ini file, or use the '--project' or '-P' CLI option to specify the project.ini path, e.g. 'riskscape -P file-path-to-project.ini ...'
This warning serves as a reminder that you may be running the
riskscape command from the wrong directory.
For new projects, this warning can be resolved by using either a text editor or the command line to create a blank
project.ini file in the current working directory.
When creating a new file, Windows Notepad may try to add a
.txt file extension,
project.ini.txt. It can sometimes be hard to notice this has happened.
Note that using
dir from the command prompt will always tell you the real filename.
Specifying your project file
Because RiskScape defaults to using the
project.ini file in the current working directory,
you will not need to worry about specifying a project file in RiskScape commands usually.
However, occasionally you may need to explicitly specify the project file that RiskScape uses. This may be because:
The project file is called something else other than
The project file is in a different directory to where you want to run RiskScape, e.g.
In these cases, you can use one of the following approaches to tell RiskScape which
project.ini file you want to use.
--projectCLI option when running RiskScape. Note that this option must come immediately after the
riskscapeexecutable. For example:
riskscape --project C:\RiskScape_Projects\getting-started\project.ini model run basic-exposure
RISKSCAPE_PROJECTenvironment variable. This approach means you only need to specify the
project.inifile once, when you open a new command prompt, rather than every time you run a
To do this on Linux, use:
On Windows, use:
If you are breaking up your project in to multiple files, e.g.
bookmarks.ini, etc, then it
can be convenient to enable the auto-import feature for your project. You can do this by adding
auto-import = true to the
project section of your
project.ini file, for example
[project] auto-import = true
auto-import to true will cause RiskScape to search the directory that contains your
file and import any
.ini files beginning with
files in any sub-directories.
Project output base location
In RiskScape, many commands accept a
--output parameter which specifies the directory
location where RiskScape should save the output files it generates.
By default, when no
--output is specified, RiskScape uses the directory location of the
project.ini file, and generates the output files in a
MODEL is the model’s name and
TIMESTAMP is the current date/time.
output directory can be changed in your project file like this:
[project] output-base-location = C:\path\to\directory
In this example, RiskScape will now save output files to:
Sometimes the data in a model pipeline may contain Invalid geometry, either from the original input data or because the geometry has been re-projected and that introduced a problem.
RiskScape can be configured to detect and automatically fix invalid geometry via the
This setting has the following options:
OFFDon’t check at all
WARNCheck that the geometry is valid and try to fix invalid geometries. Warn if fixing does not work.
ERROR(the default). This checks that the geometry is valid and tries to fix invalid geometries. An error is produced if fixing does not work. Errors will either stop your model processing from completing, or cause rows of invalid input data to be skipped.
RiskScape will always display a warning whenever invalid geometry is successfully fixed.
What RiskScape does when geometry cannot be fixed is the difference between the
validate-geometry can be set globally for your project:
[project] # fail whenever invalid geometry is read from source or reprojected validate-geometry = ERROR
Checking the validity of the input data can also be configured on a per-bookmark basis:
[bookmark good-data] location = squiggles.shp # disable geometry validation when reading from this shapefile. validate-geometry = OFF
Note that the
ERROR settings involve extra processing overhead and so can decrease performance.
Home directories were the precursor to Project files, but are no longer supported by RiskScape.
If you have an old RiskScape project, but there is no
project.ini file present, then that probably
means you were using home directories.
Converting a home directory to project file
If you have used home directories in the past, it is pretty simple to
convert them to a project file. Just create a
that looks like:
[project] # auto-import will load all .ini files that start with types, bookmarks, models, functions auto-import = true # functions from *.txt or *.py files need to be included manually functions = functions/your-function-file1.txt functions = functions/your-function-file2.py
Just adjust the function file names to match your functions.