Sub-hourly support in ecCodes

A page to detail some of the changes users should expect when sub-hourly data is supported in ecCodes.

Introduction

The sub-hourly version of ecCodes adds support for data encoded in units below hours, namely in minutes (m) or seconds (s).

We will compare the before and after behaviour to illustrate what the sub-hourly version brings to ecCodes.

Decoding data (grib_ls & grib_get)

Let's take an instantaneous example with the following temporal properties:

======================   SECTION_4 ( length=1138, padding=0 )   ======================
...
18        indicatorOfUnitOfTimeRange = 0 [Minute (grib2/tables/28/4.4.table) ]
19-22     forecastTime = 45
...

We can see that this is a field at 45 minutes into the forecast.

Now let's compare the two versions:

You can see that the unit is added to the step, and that within the MARS namespace the new key stepunits is added.

Now let's take a statistically processed example with the following temporal properties:

======================   SECTION_4 ( length=61, padding=0 )    ======================
...
18        indicatorOfUnitOfTimeRange = 0 [Minute (grib2/tables/13/4.4.table) ]
19-22     forecastTime = 45
...
50        typeOfStatisticalProcessing = 2 [Maximum (grib2/tables/13/4.10.table) ]
...
52        indicatorOfUnitForTimeRange = 0 [Minute (grib2/tables/13/4.4.table) ]
53-56     lengthOfTimeRange = 15
...

We can see that this is a maximum starting at 45 minutes into the forecast, taken over a 15 minute interval, and thus ending at 60 minutes into the forecast.

Now let's compare the two versions:

You can see that the unit is added to the startStep/endStep/stepRange, and that within the MARS namespace, where the endStep is used for indexing, the new key stepunits is added.

Encoding data (grib_set)

A key point in the way the sub-hourly encoding works is that:

Note that hourly steps are currently kept without a unit to preserve compatibility with current behaviour. The plan in future will be to unify this, and give, for example, "1h" in the above case.

Let's return to the instantaneous example we had above, and set the step to some different values to see the behaviour:

ecCodes sub-hourly

grib_set -s step=59m in out
grib_get -p step out
59m
grib_set -s step=60m in out
grib_get -p step out
1
grib_set -s step=3600s in out
grib_get -p step out
1
grib_set -s step=61m in out
grib_get -p step out
61m
grib_set -s step=3660s in out
grib_get -p step out
61m

You can see that the representation defaults to the largest possible unit in the above cases, with both 60m and 3600s mapping to 1 and 3660s mapping to 61m.

However, you may wish to fix the unit to prevent this conversion. This is performed by passing the stepunits key in addition to step as follows:

ecCodes sub-hourly

grib_set -s stepunits=m,step=60 in out
grib_get -p step out
60m
grib_set -s stepunits=s,step=3600 in out
grib_get -p step out
3600s
grib_set -s stepunits=s,step=3660 in out
grib_get -p step out
3660s

You can see that the representation has not changed to use the largest possible unit, with both 60m, 3600s and 3660s remaining as specified.