Skip to content

Writing data

Info

This guide is only relevant if you intend to deploy calculations to Nexus for operational use.

When preparing your calculation to run operationally within Nexus, it is important that all calculation output is written to Nexus, so that it can be integrated in the digital world and be used for visualization, distribution through the API, or used as input for other calculations. This guide describes how you should store your calculation output so that Nexus can interpret it.

Vector features

When your calculation outputs property values for existing feature types, or when your calculation generates completely new features (for example object detection algorithms), its output will be a table with the feature type as name.

In case your calculation adds properties to existing features, the table should have the following columns:

  • id - primary key of the feature in Nexus
  • name_of_calculated_property - property that your algorithm calculates

In case your calculation creates new features entirely, there is no Nexus primary key yet. Your calculation simply creates one row for each generated feature. Nexus will later automatically generate all IDs. If desired, you may also generate your own source ID (id_src), so that in subsequent calculation runs you only need to append those features that do not yet exist in the database.

Example

Suppose we have a calculation that calculates the heat stress in each neighbourhood of a city. Neighbourhoods in Nexus are of feature type administrative_area, hence we should generate an output table with name administrative_area. The table should contain 2 columns: the id column, linking to the primary key of each neighbourhood in Nexus, and a column that contains the computed heat stress, which we can give any name we want, say for example heat_stress_index.

Timeseries

If your calculation outputs timeseries, you should create one output table for each parameter. The table name should equal the Nexus parameter name. Each output table has three columns:

  • {name_of_parent_feature_type}__id - ID of the feature type to which the timeseries 'belongs' (note the double underscore)
  • timestamp - timestamp in PostgreSQL timestamp with timezone format
  • value - the simulated value

Example

Imagine a calculation simulating the water level in a lake. For each simulated hour, it calculates the water level in m+MSL. The calculation should write its output to a table called water_level_m_msl (the Nexus parameter name for the simulated quantity). The timeseries is linked to the lake for which the water levels are measured. Since lakes are of feature type waterbody, the first column of the output table is therefore named waterbody__id and contains the primary key values of the lake for which we simulate.

Rasters

Upload the raster to the Datastore. When storing rasters in the Nexus Rasterbase, keep the following aspects in mind:

  • Store only one parameter per raster (each geotiff will contain one band)
  • Be consistent in the spatial projection that you use for the output rasters. For this, there are two options. Ideally the projection should equal the projection of the input rasters that your calculation uses. Remember, each world in Nexus uses its own projection, so in this flavor you should program the projection dynamically. You can also decide to always output in a fixed projection. In that case, Nexus will automatically reproject it to the end user's native projection when integrating the calculation result into the Nexus database.
  • Mention the timestamp and the parameter name in the filename. The timestamp should be in ISO 8601 format, with UTC time, without additional formatting (only a T to separate date and time components). Parameter name should be in lowercase with underscores. Be sure to match the parameter name with the list of supported Nexus parameters, as can be found in the table raster_parameter. The file formatting is then as follows for rasters with both a date and time: {yyyy}{mm}{dd}T{hh}{mm}{ss}-{parameter}.tif. For a raster valid for a specific date, the format may be shortened to: {yyyy}{mm}{dd}-{parameter}.tif
  • Ensure that the official 'no data' placeholder of the geotiff file (file tag TIFFTAG_GDAL_NODATA) is consistent with the 'nodata' value of your numerical array. Use your tool (GDAL/Rasterio or other) to set the 'nodata' value explicitly when writing a numerical output array to the file.

Example

As an example, the filename could look like 20190920T105503-prec_mm_d.tif, indicating that the raster contains precipitation, in millimeters per day, for the 20th of September 2019, on 10:55:03 (local time).