Customising map reports (part 1)

“In this module we will introduce creating template overrides in InaSAFE”

When InaSAFE generates a report, it uses a system of 'overrides' to determine which template should be used to produce the map report. By creating your own template and saving it with a specific name (in the format hazard-exposure.qpt - e.g. flood-population.qpt), which InaSAFE will detect and offer as an alternative report template. These are known as template overrides and provide a powerful way for you to customise the outputs from InaSAFE.

The overrides only alter the map report - other standard reporting products are still generated as usual and are not customisable without coding. When you press the print button in InaSAFE, the print dialog will offer you the option of using an override template if one is found. You can also select a specific template if you prefer. Templates the InaSAFE installation directory (~/.qgis2/python/plugins/inasafe/safe/resources/qgis-composer-templates/ and from your ~/.qgis2/inasafe folder are automatically listed in the ‘specific template from search directories’ combo box. Lastly, you can choose a template from anywhere on the file system if you prefer.

The template itself is a QGIS Map Composer template, saved as a ‘.qpt’ file which you do from within map composer. To develop the template, the normal workflow is to run a sample analysis for the hazard / exposure template that you are interested in and then to either open the standard map template in composer from within the InaSAFE print dialog, or to start a blank template whilst the analysis results layer is active in QGIS.

InaSAFE provides a number of expressions and variables that can be used in your map composer project to produce your report.

You try:

Goal: To create an override template for population affected by flood

In this exercise, we will generate a custom report which will show some simple numeric results for a flood on population scenario. Use the provided flood, wards and population datasets to develop a simple report according to the specifications as listed below. Add a second page to the report and add an HTML frame to that new page. Set the HTML frame contents as shown in the specification below. Once your report template has been saved, rerun the InaSAFE print dialog in QGIS, again using the print options shown in the specification table below and choose ‘Open as PDF’. Confirm that your map report now contains a second page with the analysis summary report.

Experiment with further customisations of your report by adding a third page which includes outputs from other InaSAFE expressions.

Name Expectation

Input layers

tandale_floods, wards, worldpop_25

Analysis question

In the event of Floods, how many People will be affected? Summarise the results by Wards.

Print options (report development)

Uncheck all InaSAFE reports, select the standard portrait and template map reports

Print destination

Open in composer

Print composer number of pages

2

HTML Frame Expression

[% analysis_summary_report() %]

Save template filename

~/.qgis2/inasafe/flood-population.qpt

Print options (report preview)

Uncheck all InaSAFE reports, select the override template

Print destination (report preview)

Open as PDF

More about

The customisation process works the same way for all hazards and exposures but the available expressions may vary. For example, when carrying out an analysis of flood on structures, population-related fields in the impact summary table will not be accessible. The InaSAFE manual includes a list of all the expressions that are provided and what they do.

Sharing your custom reports

If you want to make your composer templates available to other colleagues in your organisation, you should bare a few things in mind:

  • Any paths to images in your template should be independent of your specific computer. There are three good approaches for dealing with this:
    1. Use a URL to an image on a website inside on an HTML element (using an <img> tag).
    2. Use a path to a shared network drive that will be the same for all computers
    3. If you want to include the InaSAFE Logo, use an InaSAFE expression to get the path to it e.g. inasafe_logo_black_path()
  • You need to save the template from within the map composer as a .qpt file
  • Avoid making any specific references to data layers in your composer template. You need to bear in mind that someone else opening your template may not have the same layers available on their machine.

Check your knowledge:

  1. Is. flood-hazard.qpt a valid template override name?:
    1. Yes
    2. No
  2. Why do some expressions include the characters [% and %}?:
    1. These are not needed.
    2. They speed up the expression evaluation.
    3. They separate the expression from surrounding text in a label or HTML item.

Further reading:

Click here to download the sample data for the lesson.