Technical documentation

Introduction

CellWarn is KNMI's system for detecting, tracking and forecasting significant convective cells, such as thunderstorms. The system follows radar-based storm cells in near real time and estimates their movement, intensity and potential impact. The output is intended to support operational warning workflows and map-based visualisation of convective hazards.

CellWarn uses real-time weather radar data from Dutch, Belgian and German radar stations, together with numerical weather prediction (NWP) data for phenomenon detection. The system is designed to support more localised and timely warning information, reducing false alarms and improving the trustworthiness of warnings.

At present, CellWarn is an experimental system with limited operational support. Availability and data quality are not guaranteed. CellWarn output should therefore be interpreted as expert nowcasting guidance and not as an official KNMI warning. For actual issued warnings, use KNMI's public warning channels.

CellWarn products describe where convective cells are located, how they are moving and what level of hazard is associated with them. Depending on the product, this can include forecast polygons for the expected path of a cell and attributes related to hail, reflectivity, vertically integrated liquid water, vertically integrated ice, echo top height and wind gusts.

The data is provided as geospatial data in WGS 84 coordinates (EPSG:4326), so longitude and latitude values can be used directly in common GIS tools and web map clients.

How to pick a dataset

Use the CellWarn datasets when you need information about detected or forecast convective cells rather than gridded model output or raw radar imagery.

  • Use CellWarn tracking datasets to show current and forecast storm-cell areas on a map.
  • Use the warning code information to distinguish between different hazard levels.
  • Use the lead-time information to separate the current or near-future cell area from the forecast cell path.
  • Use radar-derived attributes, such as reflectivity, VIL, VII, MEHS and POSH, to interpret the intensity and hail potential of a tracked cell.

CellWarn datasets are most suitable for real-time applications, operational monitoring and visualisation of convective risk. They are not a replacement for raw radar data, numerical weather prediction model fields or official warning texts.

Feedback, observations and questions about CellWarn products can be sent to opendata@knmi.nl.

Dataset description

The cell-tracking version 2.0 dataset contains GeoJSON output from KNMI's CellWarn system. It provides real-time detection, tracking and path forecasts for significant convective cells. The forecast path can extend up to one hour ahead and is represented with polygon geometries.

The dataset is published as time-stamped GeoJSON files. Recent files use names such as adaguc_polygons_hail_YYYYMMDDHHMM.geojson and adaguc_polygons_combined_hail_YYYYMMDDHHMM.geojson. The timestamp in the filename indicates the analysis or product time in UTC.

The spatial reference system is EPSG:4326. Coordinates are stored as longitude-latitude pairs.

The current product focuses on hail-related risk levels. A polygon indicates the current cell area and the estimated future path of that cell over the next hour. The risk assessment in this dataset does not replace or supersede official KNMI warnings.

How to use this dataset

The dataset can be used to display convective cells and their forecast path on a map. Each GeoJSON file contains a FeatureCollection. Individual features contain a geometry and a set of properties describing the warning level, forecast lead time and cell characteristics.

Two common file types are:

  • adaguc_polygons_hail_YYYYMMDDHHMM.geojson: contains individual polygon features for hail-related cell tracking and forecast lead times.
  • adaguc_polygons_combined_hail_YYYYMMDDHHMM.geojson: contains combined MultiPolygon layers grouped by warning_code.
  • adaguc_max_reflectivity_track_YYYYMMDDHHMM.nc: contains aggregated maximum reflectivity over the past hour. This product can be used retrospectively to validate earlier CellWarn forecasts.

The individual-cell polygon product keeps separate polygons and includes additional radar-derived attributes for each cell. The combined polygon product merges overlapping cells with the same risk level into a single MultiPolygon; it only contains the warning-code grouping and not the full set of cell properties.

Empty geometries can occur. For example, a combined warning-code file can contain features for warning codes 1 to 4, while only one warning-code layer contains active polygon coordinates for a specific timestamp.

File format and schema

The GeoJSON files follow JSON Schema draft 2020-12. Both polygon products are GeoJSON FeatureCollection objects with a top-level type, features array and dimensions.time object.

The dimensions.time.value field contains the product timestamp in UTC. The dimensions.time.units field is ISO8601.

File pattern Feature geometry Feature count Feature properties Notes
adaguc_polygons_hail_YYYYMMDDHHMM.geojson Polygon Variable Full cell properties Individual-cell polygons. Each feature has required radar-derived properties and warning information.
adaguc_polygons_combined_hail_YYYYMMDDHHMM.geojson MultiPolygon Exactly 4 features warning_code Combined warning-code layers. Coordinates may be empty for warning levels without active polygons.

For adaguc_polygons_hail files, each feature geometry is a GeoJSON Polygon. The schema allows one polygon ring collection, with coordinate pairs stored as [lon, lat].

For adaguc_polygons_combined_hail files, each feature geometry is a GeoJSON MultiPolygon. The schema describes this as a collection of polygons grouped by warning_code. The combined schema requires exactly four features. This allows clients to render all warning-code layers consistently, even when some layers contain no active coordinates.

The schemas allow additional properties inside the properties object. Applications should therefore ignore unknown feature properties rather than failing when new attributes are added.

How polygons are generated

CellWarn does not base a warning polygon only on the current state of a cell. For the warning level, the system looks back over the cell history of the past three timesteps, corresponding to approximately 15 minutes. This history includes cells that were associated with the current cell in previous timesteps, including cell mergers.

For movement uncertainty, CellWarn uses up to three velocity vectors. These are derived from the current cell and selected history over the past two timesteps, corresponding to approximately 10 minutes. In cell-merging situations, the path with the highest MEHS value is used to avoid adding too much uncertainty from weaker merged cells.

The hail warning criteria use two steps:

  • The warning category is assigned using the highest MEHS value, or maximum reflectivity for the no-hail category, reached in the recent cell history.
  • The warning area is determined from the current cell gridpoints that meet the criteria for the assigned warning category.

The criteria described for the polygon generation process are listed below. The category names describe the hail-size class used in the current visualisation; the display colours are styling choices and can differ between applications.

Hail-size category Criterion for assigning warning category Criterion for warning area
No hail expected Maximum reflectivity >= 50 dBZ Maximum reflectivity >= 40 dBZ
1-2 cm hail size MEHS >= 1 cm MEHS >= 0.5 cm or maximum reflectivity >= 45 dBZ
2-4 cm hail size MEHS >= 2 cm MEHS >= 1 cm or maximum reflectivity >= 50 dBZ
>4 cm hail size MEHS >= 4 cm MEHS >= 1 cm or maximum reflectivity >= 50 dBZ

If the cell history triggers a high warning category, but the current cell has no gridpoints matching the area criterion for that category, the warning can be demoted to the highest lower warning category for which a warning area can be found.

To create the final polygon, the warning area is extrapolated into the future using the velocity vectors. The original and extrapolated gridpoints are then expanded to account for uncertainty. The expansion distance is 3 km for the no-hail category, 4 km for the 1-2 cm hail-size category and 5 km for the 2-4 cm and >4 cm hail-size categories. The extrapolated warning area receives an additional 4 km expansion. A convex hull is then drawn around the expanded point set.

In the combined product, overlapping polygons with the same warning level are merged. Higher warning levels are subtracted from lower warning levels so that each location is covered by at most one warning polygon. The individual-cell product is kept separately because it preserves the additional properties for each cell.

How lead times should be interpreted

The lead-time polygons are intended to distinguish the active cell from the area where the cell may move during the next hour. This distinction is important because the warning category primarily describes the current active cell state, not necessarily the full future path.

The proof-of-concept lead-time visualisation separates one cell into three potential-position polygons:

Lead time Interpretation
15 minutes Area where the active cell can be located after approximately 15 minutes.
30 minutes Area where the active cell can be located after approximately 30 minutes.
60 minutes Area where the active cell can be located after approximately 60 minutes.

In files that contain warning_code_leadtime, values such as 1_15, 1_30 and 1_60 combine the warning code with the lead time in minutes.

What variables are in this dataset

The exact set of properties differs between file types. The adaguc_polygons_hail schema defines the full set of individual-cell properties. The adaguc_polygons_combined_hail schema only defines warning_code in the feature properties.

Parameter Description Unit Sampling Interval Comment
type GeoJSON object type - Product timestamp Top-level value is FeatureCollection; feature-level value is Feature.
features Array of GeoJSON features - Product timestamp Variable length for individual-cell files; exactly four features for combined files.
geometry.type GeoJSON geometry type - Product timestamp Polygon for individual-cell files; MultiPolygon for combined files.
geometry.coordinates Polygon or MultiPolygon coordinates of the detected or forecast cell area degrees longitude/latitude Product timestamp Coordinates are [lon, lat] pairs in EPSG:4326. Empty coordinate arrays can occur in combined files.
properties.warning_code Severity classification of the cell or combined warning-code layer, based on reflectivity and MEHS values code Product timestamp Schema range is 1 to 4. The data description defines 1 as slight risk, 2 as moderate risk, 3 as severe risk and 4 as extreme risk.
properties.warning_code_leadtime Combined value showing the warning code concatenated with the lead time in minutes code_minutes Product timestamp Required for individual-cell files. Allowed values are 1_15, 1_30, 1_60, 2_15, 2_30, 2_60, 3_15, 3_30, 3_60, 4_15, 4_30 and 4_60.
properties.Covered area Area covered by the cell km2 Product timestamp Required for individual-cell files. Stored as a formatted string; schema description notes a minimum of 10 km2.
properties.Direction Direction in which the cell moves degrees Product timestamp Required for individual-cell files. Stored as a formatted string.
properties.direction_degrees Computer-friendly version of Direction degrees Product timestamp Required for individual-cell files. Integer from 0 to 359.
properties.Speed Cell movement speed km/h and kt Product timestamp Required for individual-cell files. Stored as a formatted string.
properties.speed_ms Speed of the cell, rounded to one decimal m/s Product timestamp Required for individual-cell files. Numeric value.
properties.Echo Top Height Height of the echo top km and flight level Product timestamp Required for individual-cell files. Stored as a formatted string.
properties.Max. Reflectivity Maximum radar reflectivity in the cell dBZ Product timestamp Required for individual-cell files.
properties.Max. VIL Maximum vertically integrated liquid value in the cell kg/m2 Product timestamp Required for individual-cell files.
properties.Max. VII Maximum vertically integrated ice value in the cell kg/m2 Product timestamp Required for individual-cell files.
properties.Max. MEHS Maximum forecasted value of Maximum Estimated Hail Size in the cell cm Product timestamp Required for individual-cell files.
properties.Max. POSH Maximum Probability of Significant Hail associated with the cell % Product timestamp Required for individual-cell files.
properties.Max. Gust Maximum forecasted wind gusts associated with the cell km/h and kt Product timestamp Required for individual-cell files. Stored as a formatted string.
dimensions.time.value Timestamp of the file in UTC ISO 8601 UTC timestamp Product timestamp Stored at FeatureCollection level.
dimensions.time.units Unit for dimensions.time.value - Product timestamp Value is ISO8601.

Current visualisations use shades of blue for the hail-size categories and grey for areas where no hail is expected. Do not interpret the warning_code values as fixed yellow, orange or red display colours. The schema allows warning_code values 1 to 4, while the CellWarn v2 data description explains risk levels 0 to 3. Treat value 4 as schema-supported but verify its operational meaning with the product owner or consuming application before assigning a public interpretation.

JSON Schema

The JSON Schema for this dataset is provided in separate files.