.. _generic-bufr-keys:

BUFR keys
++++++++++++++++++++++++++++++++++++++++++++++++

.. note::

    This page describes the BUFR keys that can be used in the various keyword arguments of :func:`read_bufr`.

The actual keyword arguments that support these keys depend on the reader:

    - :ref:`generic <generic-reader>`: ``columns``, ``filters`` and ``required_columns`` support all keys
    - :ref:`flat <flat-reader>`: ``filters`` and ``required_columns`` support all keys
    - :ref:`synop <synop-reader>` and :ref:`temp <temp-reader>`: ``filters`` support all keys. Please note that ``columns`` are limited to the pre-defined parameters for these readers.


.. _eccodes-bufr-keys:

ecCodes BUFR keys
----------------------

ALl the ecCodes keys from both the BUFR header and data sections are supported in the :func:`read_bufr` kwargs :ref:`mentioned above <generic-bufr-keys>`. However, there are some limitations:

    * keys containing the rank e.g. "#1#latitude" cannot be used
    * key attributes e.g. "latitude->code" cannot be used

.. note::

    The "count" key is generated by ecCodes and it refers to the message index. It is also supported but please note that message indexing starts at 1 and not at 0!


.. _computed-bufr-keys:

Computed BUFR keys
-------------------

These keys are not present in the BUFR data but are generated by pdbufr from existing BUFR keys.

.. _key-data-datetime:

data_datetime
//////////////

    Generated from the "year", "month", "day", "hour", "minute", "second" keys in the BUFR data section. The values are converted to a **datetime.datetime** object.


.. _key-typical-datetime:

typical_datetime
/////////////////

    Generated from the "typicalYear", "typicalMonth", "typicalDay", "typicalHour", "typicalMinute", "typicalSecond" keys in the BUFR header section. The values are converted to a **datetime.datetime** object.


.. _key-wmo-station-id:

WMO_station_id
////////////////

    Generated from the "blockNumber" and "stationNumber" keys as::

          blockNumber*1000+stationNumber


.. _key-wigos-station-id:

WIGOS_station_id
////////////////////

    *New in version 0.12.0*

    Generated from the "wigosIdentifierSeries", "wigosIssuerOfIdentifier",  "wigosIssueNumber" and  "wigosLocalIdentifierCharacter" keys as a str in the following format::

          "{wigosIdentifierSeries}-{wigosIssuerOfIdentifier}-{wigosIssueNumber}-{wigosLocalIdentifierCharacter}


    For example: "0-705-0-1931".

    When using "WIGOS_station_id" in ``filters`` the value can be given as a str or as a tuple/list of 4 values. See: :ref:`filters` for details.

    Details about the WIGOS identifiers can be found `here <https://community.wmo.int/en/activity-areas/WIGOS/implementation-WIGOS/FAQ-WSI>`_.

.. _key-geometry:

geometry
///////////

    Values extracted as a list of::

          [longitude,latitude,heightOfStationGroundAboveMeanSeaLevel]

    as required for geopandas.

.. _key-crs:

CRS
//////

    Generated from the "coordinateReferenceSystem" key using the following mapping:

          .. list-table::
             :header-rows: 1

             * - coordinateReferenceSystem
               - CRS

             * - 0
               - EPSG:4326

             * - 1
               - EPSG:4258

             * - 2
               - EPSG:4269

             * - 3
               - EPSG:4314

             * - 4 or 5
               - not supported

             * - missing
               - EPSG:4326



.. note::

    Computed keys do not preserve their position in ``columns`` but are placed to the end of the resulting DataFrame.