MARS requests for some parameters will also be affected by the migration to GRIB2.

Changes to param keyword

For GRIB1 parameters, the param keyword in the mars request can be set to param=indicatorOfParameter.table2Version. Requests with this structure will not work for GRIB2 as these two keys do not exist in this edition. The paramId must be used for GRIB2 parameters. This is the recommended way of specifying parameters in MARS requests.

An example is the retrieval of the U-component of the 10 metre wind, which is in GRIB1 in the indicatorOfParameter.table2Version representation param=165.128, but in GRIB2 param=165.

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2. If this request is run at the moment, it will return data encoded in GRIB1.

Retrieval of U-component of 10m wind in GRIB1

Retrieval of U-component of 10m wind in GRIB2

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=165.128,
  target="output_10u.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=165,
  target="output_10u.grib2"

Changes for parameters archived with levtype=sol

Parameters on surface levels will be archived with levtype=sol (surface other levels).

For example, in GRIB1, a separate param is used to retrieve Volumetric soil water layer 1 and a different param o retrieve Volumetric soil water layer 2, etc with levtype=sfc . In GRIB2, only a single paramId is used for Volumetric soil water, with the layer being selected by the levelist keyword and using levtype=sol .

Instead of specifying a single parameter Id in the request, for some parameters additional keys will need to be added, for example for snow layer parameters the layer. These parameters will be archived with the new MARS keyword levtype=sol which has to be specified in the request together with the MARS keyword levelist .

Example of a retrieval of snow depth parameters with levtype=sol .

The levtype=sol keyword for multi-layer snow depth parameters in GRIB2 has been introduced with the Implementation of IFS Cycle 48r1.

Retrieval of snow depth in GRIB1

Retrieval of snow depth in GRIB2

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=141.128,
  target="output_sd.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sol,
  levelist=1/2/3/4/5,
  param=228141,
  target="output_sd.grib2"

Changes for parameters archived with levtype=hl

Parameters with typeOfLevel=heightAboveGround and with level set to a value greater than 10m (for example, 100u, 100v, 100si, 200u, 200v, 200si) which were previously archived in MARS with levtype=sfc with will be archived with levtype=hl (height levels). Consequently, the paramId (and shortName) for these parameters will also change.

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2.

Retrieval of 100m wind components and speed in GRIB1

Retrieval of 100m wind components and speed in GRIB2

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=228246/228247/228249,   # 100u/100v/100si
  target="output_100m_winds.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=hl,      # Height level
  levelist=100,   # Level 100
  param=131/132/10,   # u/v/ws 
  target="output_100m_winds.grib2"

Addition of new MARS keyword timespan for parameters processed statistically over a time interval

In GRIB1, parameters processed statistically over a time interval, such as maximum or minimum temperature in the last 3 hours or last 6 hours or since previous post-processing, have their own distinct paramIds. In GRIB2, there will be a single paramId to identify, e.g., maximum 2m temperature and a new MARS keyword, timespan, to specify the period over which the maximum or minimum or average, etc, has been taken. Typically, timespan=1h for "previous hour", timespan=3h for "previous 3 hours" and timespan=6h for "previous 6 hours", etc.

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2.

There is no need to re-specify the param keyword in the second and third retrieve blocks as it will be inherited from the first retrieve block. It is included here only to illustrate the changes needed. All that needs to change is the value of the timespan keyword.

Retrieval of maximum and minimum 2m temperature in GRIB1

Retrieval of maximum and minimum 2m temperature in GRIB2

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  levtype=sfc,
  param=201/202,       # mx2t/mn2t
  step=1/2/3/4/5/6,
  target="output_max_min_2t_1h.grib1"
retrieve,
  param=228026/228027, # mx2t3/mn2t3
  step=3/6,
  target="output_max_min_2t_3h.grib1"
retrieve,
  param=121/122,       # mx2t6/mn2t6
  step=6,
  target="output_max_min_2t_6h.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  levtype=sfc,
  param=237167/238167, # max_2t/min_2t 
  timespan=1h,         # previous hour 
  step=1/2/3/4/5/6,
  target="output_max_min_2t_1h_3h.grib2"
retrieve,
  param=237167/238167, # max_2t/min_2t
  timespan=3h,         # previous 3 hours 
  step=3/6,
  target="output_max_min_2t.grib2"
retrieve,
  param=237167/238167,  # max_2t/min_2t
  timespan=6h,          # previous 6 hours
  step=6,
  target="output_max_min_2t_6h.grib2"

The timespan keyword is also needed for parameters accumulated from the start of the forecast, such as precipitation or and radiation parameters . For such parameters, set timespan=fs for "accumulated from start of forecast", e.g:

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2.

Retrieval of maximum and minimum 2m temperature in GRIB1

Retrieval of maximum and minimum 2m temperature in GRIB2

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  levtype=sfc,
  param=169,           # ssrd - surface solar radiation downwards
  step=6/to/360/by/6,
  target="output_ssrd.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  levtype=sfc,
  param=169,           # ssrd - surface solar radiation downwards
  timespan=fs,         # from start of forecast 
  step=6/to/360/by/6,
  target="output_ssrd.grib2"

Addition of new MARS keyword chem for retrieval of chemical species

Another example are chemical parameters. Besides using the MARS keyword param in the request to specify the parameter type, e.g., mass mixing ratio, an additional MARS keyword chem will be used to specify the chemical substance(s), e.g., nitrogen dioxide.

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2. The values taken by the chem keyword are not yet finalised.

Retrieval of NO₂ mass-mixing ratio in GRIB2 - current

Retrieval of NO₂ mass-mixing ratio in GRIB2 - new

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=210121,
  target="output_no2.grib2"

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=402000,      # Mass mixing ratio
  chem=17,           # Nitrogen dioxide
  target="output_no2.grib2"

Addition of new MARS keywords chem and wavelength for retrieval of chemical species with optical properties

Other chemical parameters, such as aerosol optical depths and absorption aerosol optical, are available for different wavelengths. Besides using the MARS keywords param and chem in the request to specify the parameter type and chemical substance, e.g., "aerosol optical depth" and "sea salt", an additional MARS keyword wavelength will be used to specify the wavelength.

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2. The values taken by the chem keyword are not yet finalised.

Retrieval of sea salt aerosol optical depth at 550nm in GRIB1

Retrieval of sea salt aerosol optical depth at 550nm in GRIB2

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=208.210,      # sea salt aerosol optical depth at 550nm
  target="output_sea_salt_aerosol_550.grib1"

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=457000,      # Aerosol optical depth
  chem=936,          # Sea salt aerosol
  wavelength=550,    # At 550nm
  target="output_sea_salt_aerosol_550.grib2"

Change of GRIB packing for GRIB2 parameters retrieved from MARS on a grid

GRIB2 parameters retrieved on a grid will be compressed with CCSDS. To decode these parameter, ecCodes must be linked to libaec. Alternatively, the data can be retrieved in another packing type such as grid_simple packing, which was in use for the model level GRIB2 parameters.

The following MARS retrieval is provided only as an example of the sort of change that users will need to make once the data are provided in GRIB2. The values taken by the chem keyword are not yet finalised.

Retrieval of NO₂ mass-mixing ratio in GRIB2 - current

Retrieval of NO₂ mass-mixing ratio in GRIB2 - new with simple packing

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=210121,
  target="output_no2.grib2"

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=402000,      # Mass mixing ratio
  chem=17,           # Nitrogen dioxide
  packing=simple,    # Simple packing
  target="output_no2.grib2"

Page tree

Migration to GRIB2 - changes in the MARS language

Changes to param keyword

Changes for parameters archived with levtype=sol

Changes for parameters archived with levtype=hl

Addition of new MARS keyword timespan for parameters processed statistically over a time interval

Addition of new MARS keyword chem for retrieval of chemical species

Addition of new MARS keywords chem and wavelength for retrieval of chemical species with optical properties

Change of GRIB packing for GRIB2 parameters retrieved from MARS on a grid