Projecta: Worksheet -

Section : 5. Advanced InaSAFE Customisation

Module : 5.7. Defining a new hazard and hazard classification in InaSAFE

Defining a new hazard and hazard classification in InaSAFE

“InaSAFE is delivered to you with a number of pre-defined hazards. In this lesson we look at how you go about adding new hazard definitions.”

A large part of InaSAFE functionality is driven by a simple metadata system that defines the available hazard, exposure and other conceptual behaviours. This system is referred to as 'definitions' and is implemented through a collection of simple python files containing dictionaries (tree-like data structures). In this lesson, we will walk through the steps needed to create a new hazard type, and contribute it back to InaSAFE.

Note that although this lesson requires some basic editing of Python source code, it is not necessary to be a skilled software developer in order to add a new hazard to InaSAFE.

In this exercise, we are going to use chemical spills as an example of a new type of hazard we would like to add to InaSAFE. We are going to be changing the source code of InaSAFE but do not be afraid of breaking anything - if it all goes wrong you can simply re-install InaSAFE from the plugin manager. Any changes made to source files should be made using a text editor such as Notepad++ or Sublime Edit.

You try:

Goal: To add a new hazard type for chemical spills to InaSAFE

To start, open the Impact Function Centric Wizard and take note of the available hazard types catered for on the first screen.
Next open the sample project provided. In that project, you will see a fictitious chemical spill incident.
Note that for all instructions, ~ refers to your home directory.
Note also that whenever making changes to your hazard definitions, you will need to restart QGIS in order to test the changes.
Navigate to your working directory using your file manager.
Edit the file containing hazard definitions using your text editor.
Locate the definition of hazard_generic in the hazard file and copy the entire block (look for the closing } which ends the block).
Paste the block in after the end of the hazard_generic block effectively giving you two identical blocks.
In the new block edit the contents as per the specification table below for 'hazard block'.
Once you have finished editing the hazard block, add a new entry to the hazard_all block at the bottom of hazard.py as per the All hazards block specification below.
Save your edits to hazard.py and restart QGIS.
Open the Impact Function Centric Wizard. Do you see the new hazard type listed there?
Currently the chemical spill hazard is using the same classification as the generic hazard (I.e. high, medium, low hazard). In the next steps, we will create a new classification specification.
Open the file called hazard_classification.py.
Look for the block called generic_hazard_classes and make a copy of it.
In the copied block, replace all items as listed in the Hazard classification block items below.
Add your new hazard classification to the 'hazard_classification' list at the bottom of the file in the 'types' section.
You need to tell your hazard definition that it supports this new hazard classification. Do this by editing hazard.py again and changing your 'classifications': [generic_hazard_classes, chemical_spill_hazard_classes],
Save your edits and restart QGIS and add the layers from the sample data provided as per the Input layers listed in the specification below.
Now run the keywords wizard and see if you can define the hazard class and hazard classification for the chemical spill layer, then run the analysis.
Lastly run the analysis as per the Analysis question in the specification below.

Name	Expectation
Working directory	`~/.qgis2/python/plugins/inasafe/safe/definitions`
Hazard definitions	`hazard.py`
Hazard block	replace hazard_chemical_spill with hazard_chemical_spill
Hazard block	replace 'key' value from hazard_generic to hazard_chemical_spill
Hazard block	replace 'name' value from 'Generic Hazard' to 'Chemical Spill'
Hazard block	replace 'description' value with 'Example chemical spill hazard'
All hazards block	Insert a new item 'hazard_chemical_spill' into the list
Hazard definitions	Add `from safe.definitions.hazard_classifications import chemical_spill_hazard_classes` to the top of hazard.py
Hazard classification block	replace all references to 'generic_hazard_classes' with 'chemical_spill_hazard_classes'.
Hazard classification block	set the 'name' value to 'Chemical spill classes'
Hazard classification block	set the 'description' value to 'A chemical spill example classification'
Hazard classification block	set the 'citations' value to 'This example classification is not cited'.
Hazard classification block	change key 'high' to key: 'evacuation_zone'.
Hazard classification block:	change name 'high' to key 'Evacuation zone'.
Hazard classification block	change key 'medium' to key: 'danger_zone'.
Hazard classification block	change name 'medium' to key: 'Danger zone'.
Hazard classification block	change key 'low' to key: 'use_caution_zone'.
Hazard classification block	change name 'high' to key: 'Use caution zone'.
Types block	add a new line : chemical_spill_hazard_classes,
Input layers	Chemical spill, wards, worldpop_25
Analysis question	In the event of Chemical spill, how many People will be affected? Summarise the results by Wards.

More about defining your own hazard types

In the process we followed in the exercise above, we followed simple process of extending the InaSAFE definitions. There are many more tweaks you can make to customise your hazard definition. For example, you can define specific actions for the action list in the report, you can define additional classifications (and they do not need to be limited to 3 classes). When compiling a hazard classification, you should pay special attention to displacement rates and affected properties of each class since they determine the logic that determines how many people will be affected or displaced when the analysis runs.

If you plan to do more serious modifications to the InaSAFE definitions, you make want to consider using a proper Python code editor rather than a simple text editor. Doing that will make it easier to follow the logic of haw hazards are defined.

In the same way that custom hazards can be defined, custom exposures can also be defined - though in our experience this is a less common requirement.

Be careful about updating your InaSAFE plugin if you have made local changes - it will overwrite your work.

We encourage you to contribute any new hazard definitions you create back to the InaSAFE project. If you do this they will automatically be available to any user who installs InaSAFE . It will also ensure that you can upgrade your copy easily and still use your contributed definitions. You will only see your hazard in English only until it is translated - translations will be managed once the code has been contributed to the main InaSAFE project.

The simplest way to share our changes is by making a ticket on GitHub and attaching your changed files.

Check your knowledge:

InaSAFE can be modified easily by editing a few python metadata files:

yes

It is possible to use this approach to also add new exposure types to InaSAFE:

yes