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)

Instantaneous GRIB message

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.

Statistically processed GRIB message

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.

Instantaneous GRIB message

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_get -p step in.grib2
0m
grib_set -s step=59m in out.grib2
grib_get -p step out.grib2
59m
grib_set -s step=60m in.grib2 out.grib2
grib_get -p step out.grib2
1
grib_set -s step=3600s in.grib2 out.grib2
grib_get -p step out.grib2
1
grib_set -s step=61m in.grib2 out.grib2
grib_get -p step out.grib2
61m
grib_set -s step=3660s in.grib2 out.grib2
grib_get -p step out.grib2
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.grib2 out.grib2
grib_get -p step out.grib2
60m
grib_set -s stepunits=s,step=3600 in.grib2 out.grib2
grib_get -p step out.grib2
3600s
grib_set -s stepunits=s,step=3660 in.grib2 out.grib2
grib_get -p step out.grib2
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.

Statistically processed GRIB message

In a statistically processed example, we have the unit of the start of the interval, as well as the unit of the time interval over which the processing is performed. Therefore, in this case, we preserve the largest possible unit in which both the startStep and endStep can be represented.
Let's return to the statistically processed example we had above, and change the processing interval via stepRange to see this behaviour:

ecCodes sub-hourly

grib_get -p startStep,endStep,stepRange in.grib2
45m 60m 45m-60m
grib_set -s stepRange=1-75m in.grib2 out.grib2 # <-------- could equivalently specify 60m-75m , 60m-4500s , ...
grib_get -p startStep,endStep,stepRange out.grib2
60m 75m 60m-75m
grib_set -s stepRange=3600s-120m in.grib2 out.grib2 # <-------- could equivalently specify 1-2 , 60m-120m , 60m-7200s , ...
grib_get -p startStep,endStep,stepRange out.grib2
1 2 1-2

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

ecCodes sub-hourly

grib_get -p startStep,endStep,stepRange in.grib2
45m 60m 45m-60m
grib_set -s stepunits=m,stepRange=60-120 in.grib2 out.grib2
grib_get -p startStep,endStep,stepRange out.grib2
60m 120m 60m-120m  # <----------------------------- Has not changed to 1 2 1-2
grib_set -s stepunits=s,stepRange=3600-4500 in.grib2 out.grib2
grib_get -p startStep,endStep,stepRange out.grib2
3600s 4500s 3600s-4500s  # <----------------------------- Has not changed to 60m 75m 60m-75m