Temp

Warning

This reader is experimental and the API might change in the future. It is not recommended to use it in production code yet.

New in version 0.13.0

read_bufr(path, reader='temp', columns=[], filters=None, stnid_keys=None, geopotential='z', units_system=None, units=None, units_columns=False)

Extract temp-like data from BUFR using pre-defined parameters.

Parameters:

• path (str, bytes, os.PathLike or a message list object) – path to the BUFR file or a message list object

• columns (str, sequence[str]) –

  specify the pre-defined parameters to extract. The possible values are as follows:

  • ”default” or empty list: extract the parameters as in “station” followed by all the upper level parameters. See geopotential for details on extracting the geopotential parameters.

  • ”location”: extract only the “lat” and “lon” parameters (see station parameters for details)

  • ”geometry”: extract only the “lat”, “lon” and “elevation” parameters (see station parameters for details)

  • ”station”: extract only the “stnid”, “time”, “lat”, “lon” and “elevation” parameters (see station parameters for details)

  • ”upper”: extract only the upper level parameters

  • when it is a non-empty list, specifies the parameters to extract. The keys “default”, “location”, “geometry”, “station” and “upper” can all be part of the list and will add all the parameters from the corresponding group. No individual upper level parameters can be specified in the list, only the whole “upper” group can be extracted.

• geopotential (str) –

  define if the geopotential or/and geopotential height parameters should be extracted. The possible values are as follows:

  • ”z”: extract the geopotential parameter. If not available, it is computed from the geopotential height using the formula:

    \[z = zh \cdot g\]

    where \(zh\) is the geopotential height and \(g\) is the standard acceleration of gravity (9.80665 m/s²).

  • ”zh”: extract the geopotential height parameter. If only geopotential is available, it is converted to geopotential height using the formula:

    \[zh = \frac{z}{g}\]

    where \(z\) is the geopotential and \(g\) is the standard acceleration of gravity (9.80665 m/s²).

  • ”both”: extract both the geopotential and geopotential height parameters.

  • ”raw”: extract either the geopotential or geopotential height parameter, depending on which one is available in the BUFR message/subset. If both are available, both are extracted.

• filters (dict) – define the conditions when to extract the data. The individual conditions are combined together with the logical AND operator to form the filter. It can contain both BUFR keys and parameters. See Filters for details.

• stnid_keys (str, sequence[str], None) – BUFR keys to extract data for the stnid param. When None, the default list of BUFR keys are used (see stnid in station parameters). New in version 0.14.0

• unit_system (str, None) – define the unit system to generate the resulting values. The default is None, which means that no conversion is applied but the values/units found in the BUFR are written to the output. The only available unit system is: “pdbufr”. The “pdbufr” system uses the units as defined in the Parameters section.

• units (dict, None) –

  specify custom units conversions as a dictionary. The keys are the parameter names and the values are the units to convert to. For keys not specified the conversion defined by unit_system is applied. E.g.:

  units = {
      "t": "C",
  }
  

• units_columns – if True, a units column is added to the resulting DataFrame for each parameter having a units. The column name is formed by adding the “_units” suffix to the parameter name. The default is False.

TEMP-like data

For this reader the term “TEMP-like data” means data that is similar to classic radiosonde observations, and it contains all messages/subsets with dataCategory=2. See details on the data category here.

The resulting DataFrame

The resulting DataFrame will contain one row for each pressure level and one column per each parameter. The columns are named after the parameter names, e.g. “t”. With the default settings the first columns are always the station/platform identifier, time, latitude, longitude and elevation followed by the observed parameters. E.g.:

    stnid    lat    lon  elevation                 time  pressure        z   t
0   71907  58.47 -78.08       26   2008-12-08 12:00:00  100300.0    250.0  258.3  ...
1   71907  58.47 -78.08       26   2008-12-08 12:00:00  100000.0    430.0  259.7  ...

Units

When units_columns=True and a parameter has an associated units a separate column is created for the units. The column name is formed by adding the “_units” suffix to the parameter name:

              t       t_units
0   ...     273.15       K
1   ...     274.15       K

Parameters

A parameter is a high-level concept in pdbufr. It was introduced to overcome the problem that the same quantity can be encoded in BUFR in multiple ways. When using parameters we do not need to know the actual encoding, but the desired value is automatically extracted.

SYNOP parameters can be divided into three groups:

• station/platform related parameters,

• upper parameters,

Station/platform params

Name	Units/Object	Description
stnid		Station/platform identifier as a str. The following keys are tried in order to generate the value (the first one with a valid value is used): “ident” WMO station id WIGOS station id “shipOrMobileLandStationIdentifier” “station_id” “icaoLocationIndicator” “stationOrSiteName” “longStationName”
time	datatime.datetime	Time of the observation
lat	deg	Latitude
lon	deg	Longitude
elevation	m	Elevation
name	str	Name of the station/platform. The following keys are tried in order to generate the value: “stationOrSiteName” and “icaoLocationIndicator”.

Upper level parameters

Name	Units	Description
pressure	Pa	Pressure
z	m2 s-2	Geopotential
zh	gpm	Geopotential height
t	K	Temperature
td	K	Dew point temperature
wind_speed	m/s	Wind speed
wind_dir	deg	Wind direction

Parameter filters

Parameter names and levels can be used in filters. For the filter syntax see Filters.

Warning

The individual conditions in filters are combined together with the logical AND operator. So if any condition fails to match then the whole station/platform will be omitted from the results.

Filtering parameter values

# accepting pressure levels where t temperature > 243.15 K
filters = {"t": slice(243.15, None)}

Examples

• Temp: overview

• Temp: geopotential