Designing Reports

Reports are, in simplest terms, created by populating a report template with textual and/or spatial data from one or more jobs. It is important to note that reports are generated at the layer/band level hence the number of reports from a single job will correspond to the number of default bands for the given job.

Designing reports is a two-step process that involves:

Designing templates using the QGIS layout framework;
Specifying the configuration parameters in a report configuration file.

Prerequisites

Before embarking on designing new or customizing existing reports, it is recommended to familiarize with the following topics:

Layout Expression Variables

A report is made up of static content (such as logos, disclaimer text etc.) that does not change from one report to another. It may also include dynamic content (such as maps or attribute information) that is generated at runtime during the execution process.

The Trends.Earth toolbox provides a number of layout expression variables that can be used to insert dynamic content in a layout. Some of these are available at design time while others are only available at runtime. The table below provides a summary of the available variables.

Job Variables

These are characterized by a te_job_ prefix and only available at runtime.

Variable Name	Description	Data Type
te_job_id	Unique identified corresponding to the job’s UUID	String
te_job_input_params	JSON representation of a job’s input parameters	String
te_job_paths	Local path to the job’s dataset(s)	String
te_job_alg_name	Job’s algorithm name	String
te_job_creation_date	Creation date/time of a job	String in %Y-%m-%d %H:%M format
te_job_status	Completion status of a job e.g. DOWNLOADED, GENERATED_LOCALLY etc.	String
te_job_name	Name of the job as inputted by the user.	String
te_job_comments	Comments to a job as provided by the user	String

Layer Variables

These are characterized by a te_current_layer_ prefix and only available at runtime.

Variable Name	Description	Data Type
te_current_layer_name	Name of the layer in the current execution context	String

Report Settings Variables

These are characterized by a te_report_ prefix and are available at both design time and runtime. Refer to the Reports section for a detailed description of the report settings and corresponding variable names.

Template Types

There are two main report template types:

Full Template

This is designed to contain - or provide an allowance to include - more information such as author name. The default template is set on an A4 page and includes a layout title, map, legend, scale bar, north arrow, disclaimer text. and logo.

Simple Template

This is designed to be a lighter version of the template with the default one set on an 83mm by 59mm page size (in landscape mode) or vice versa in portrait mode and contains a map, legend, north arrow, scale bar, disclaimer text and logo.

Note

For each template type, you will need to provide both the portrait and landscape versions as the toolbox will select one of these depending on the dimensions of the map layer being rendered.

Designing Report Templates

You can create templates either by:

Creating A New One

Navigate to Project > New Print Layout….
Specify a user-friendly name for the layout.

Modifying an Existing One

Navigate to Project > Layout Manager….
Select Specific in the drop-down menu under New from Template section.
Click on the browse button (with three dots) to select an existing qpt template. The default templates can be found in [base_data_directory]/reports/templates.
Click on Create… button.
Specify a user-friendly name for the template.

Adding Layout Items

You can add items to the template in a similar fashion as defined in the QGIS manual. Trends.Earth expression variables are available in the Expression Builder dialog and can be inserted in label items as any other QGIS variable.
For instance, to insert a job’s algorithm name in a label item, you can use the following expression: [% @te_job_alg_name %].
For a map item, do not add any layers or specify a map theme as the layers and their ordering will be automatically set during the report generation process.
When using a legend item, ensure the Auto update option is selected. The toolbox will determine which legend items to show/hide depending on the rendering context.
For map items rendering a job’s layers or label items that use the toolbox’s expression variables, please ensure that you define their corresponding item IDs so that they can be flagged for updating during the report generation process. A preferred naming convention - for the item ID - is [item_type.context_name] e.g. label.layer_name, label.job_alg_name, map.main. We will see how these item IDs are used in the item_scope_mapping section.

Configuring Report Parameters

The next step is to define which templates will be used for which algorithms. This is done through a report configuration file -templates.json- that is created in [base_data_directory]/reports/templates on loading the toolbox for the first time.

templates.json is a list of report configuration objects where each configuration object corresponds to one or more scopes. A scope, in this case, refers to an algorithm. A configuration is made up of two parts:

template_info - Contains information about the QGIS report templates associated with one or more algorithm scopes.
output_options - Output options for exporting a report.

See sample below:

 {
   "template_info":{
      "id":"70ca4be7-839e-4248-be14-34ba8665ed98",
      "name":"Land Productivity",
      "description":"Overview of land productivity indicator.",
      "simple_portrait_path":"simple_layout_template_portrait.qpt",
      "simple_landscape_path":"simple_layout_template_landscape.qpt",
      "full_portrait_path":"full_layout_template_portrait.qpt",
      "full_landscape_path":"full_layout_template_landscape.qpt",
      "item_scopes":[
         {
            "name":"productivity",
            "type_id_mapping":{
               "map":["map.main"],
               "label":["label.layer_title"]
            }
         }
      ]
   },
   "output_options":{
      "template_type": "ALL",
      "formats": [
         {
            "format_type": "PDF"
         },
         {
            "format_type": "IMAGE",
            "params": {
               "image_type": "png"
            }
         }
      ]
   }
}

template_info

Contains information about the QGIS report templates associated with one or more algorithm scopes.

Property Name	Description	Required
id	A unique UUID identifier in string format	Yes
name	A friendly name of the template configuration	No
description	A brief description of the template configuration	No
simple_portrait_path	Name of the template file for a simple portrait layout	Yes
simple_landscape_path	Name of the template file for a simple landscape layout	Yes
full_portrait_path	Name of the template file for a full portrait layout	Yes
full_landscape_path	Name of the template file for a full landscape layout	Yes
item_scopes	A list of item scope objects. It should contain at least one scope definition. See item_scope_mapping for more information.	Yes

Note

The paths defined above are basically file names which are relative to the location of the templates.json configuration file.

output_options

Options for exporting an output report.

Property Name

Description

Required

formats

A list of format objects specifying the output format of the report. You can have a report produced in multiple types such as PDF and PNG.

At least one output format needs to be defined.

See output_format for configuration options for an output format object.

Yes

template_type

Report template type in string format.

Supported options include: SIMPLE, FULL or ALL.

Please note that these should be in uppercase as provided above.

Yes

item_scope_mapping

Provides a mechanism for grouping layout items based on a scope (i.e. algorithm).

Property Name

Description

Required

name

Name of the algorithm that will be matched to this configuration e.g. productivity, sdg-15-3-1-sub-indicators etc. Refers to the algorithm names defined in scripts.json in the toolbox’s data folder.

Yes

type_id_mapping

A dictionary containing an enumeration of the layout item type and corresponding list of item IDs defined in the template.

Supported layout item types include: map, label, picture

"type_id_mapping":{
   "map":["map.main"],
   "label":["label.layer_title"]
}

See Adding Layout Items on how to specify item IDs.

Yes

output_format

Format information for the report output.

Property Name

Description

Required

format_type

An enumeration of the file output type.

Supported enumeration options include: PDF and IMAGE.

Please note that these should be in uppercase as provided above.

Yes

params

Depending on the specified output type, this property contains additional information regarding the format.

For instance, if the IMAGE is specified as the output format, then this property can be used to specify the IMAGE type. Does nothing for PDF type and defaults to PNG for an IMAGE type.

No

Resetting to Default Templates and Configuration

To revert back to the default templates and report configuration file that ship with the toolbox, perform the following steps:

Close QGIS then back-up the templates folder in [base_data_directory]/reports/templates.
Proceed to delete the templates folder then restart QGIS.