data.readers.grib.codes ======================= .. py:module:: data.readers.grib.codes Classes ------- .. autoapisummary:: data.readers.grib.codes.GribField Module Contents --------------- .. py:class:: GribField(path, offset, length, handle_manager=None, use_metadata_cache=False) Bases: :py:obj:`earthkit.data.core.fieldlist.Field` Represent a GRIB message in a GRIB file. :param path: Path to the GRIB file :type path: :class:`str` :param offset: File offset of the message (in bytes) :type offset: :class:`number` :param length: Size of the message (in bytes) :type length: :class:`number` .. py:method:: an_datetime() .. py:property:: array_backend Return the array namespace of the field. :type: :obj:`ArrayBackend` .. py:property:: array_namespace Return the array namespace of the field. :type: :obj:`ArrayBackend` .. py:method:: base_datetime() .. py:method:: batched(*args) Return iterator for batches of data .. py:method:: bounding_box() Return the bounding box of the field. :rtype: :obj:`BoundingBox ` .. py:method:: clone(**kwargs) Create a new :class:`ClonedField` the with updated values and/or metadata. :param values: The values to be stored in the new :class:`ClonedField`. When it is ``None`` the resulting :class:`ClonedField` will access the values from the original field. :type values: :class:`array-like` or :obj:`None` :param metadata: If it is a dictionary, it is merged with ``**kwargs`` and interpreted in the same way as ``**kwargs``. If it is a :class:`Metadata` object, it is used as the new metadata. In this case ``**kwargs`` cannot be used. :type metadata: :class:`dict`, :class:`Metadata` or :obj:`None` :param \*\*kwargs: Keys and values to update the metadata with. Metadata values can also be ``callables`` with the following positional arguments: original_field, key, original_metadata. The new :class:`ClonedField` will contain a reference to the original metadata object and keys not present in ``kwargs`` will be accessed from the original field. :type \*\*kwargs: :class:`dict`, *optional* :returns: The new field with updated values and/or metadata keeping a reference to the original field. :rtype: :class:`ClonedField` :raises ValueError: If ``metadata`` is a :class:`Metadata` object and ``**kwargs`` is not empty. .. py:method:: copy(*, values=None, flatten=False, dtype=None, array_backend=None, array_namespace=None, device=None, metadata=None) Create a new :class:`ArrayField` by copying the values and metadata. :param values: The values to be stored in the new :class:`Field`. When it is ``None`` the values extracted from the original field by using :obj:`to_array` with ``flatten``, ``dtype`` and ``array_backend`` and copied to the new field. :type values: :class:`array-like` or :obj:`None` :param flatten: Control the shape of the values when they are extracted from the original field. When ``True``, flatten the array, otherwise the field's shape is kept. Only used when ``values`` is not provided. :type flatten: :class:`bool` :param dtype: Control the typecode or data-type of the values when they are extracted from the original field. If :obj:`None`, the default type used by the underlying data accessor is used. For GRIB it is ``float64``. Only used when ``values`` is not provided. :type dtype: :class:`str`, :class:`array.dtype` or :obj:`None` :param array_backend: Control the array namespace of the values when they are extracted from the original field. If :obj:`None`, the underlying array format of the field is used. Only used when ``values`` is not provided. **Deprecated since version 0.19.0**. Use ``array_namespace`` instead. In versions before 0.19.0 an :obj:`ArrayBackend` was also accepted here, which is no longer the case. :type array_backend: :class:`str`, :class:`array_namespace` or :obj:`None` :param array_namespace: Control the array namespace of the values when they are extracted from the original field. When it is :obj:`None` the underlying array format of the field is used. **New in version 0.19.0**. :type array_namespace: :class:`str`, :class:`array_namespace` or :obj:`None` :param device: The device where the array will be allocated. When it is :obj:`None` the default device is used. :type device: :class:`str` or :obj:`None` :param metadata: The metadata to be stored in the new :class:`Field`. When it is :obj:`None` a copy of the metadata of the original field is used. :type metadata: :class:`Metadata` or :obj:`None` :rtype: :class:`ArrayField` .. py:method:: data(keys=('lat', 'lon', 'value'), flatten=False, dtype=None, index=None) Return the values and/or the geographical coordinates for each grid point. :param keys: Specifies the type of data to be returned. Any combination of "lat", "lon" and "value" is allowed here. :type keys: :obj:`str`, :obj:`list` or :obj:`tuple` :param flatten: When it is True a flat array per key is returned. Otherwise an array with the field's :obj:`shape` is returned for each key. :type flatten: :class:`bool` :param dtype: Typecode or data-type of the arrays. When it is :obj:`None` the default type used by the underlying data accessor is used. For GRIB it is ``float64``. :type dtype: :class:`str`, :class:`array.dtype` or :obj:`None` :param index: The index of the values and or the latitudes/longitudes to be extracted. When it is None all the values and/or coordinates are extracted. :type index: :class:`array indexing object`, *optional* :returns: An multi-dimensional array containing one array per key is returned (following the order in ``keys``). The underlying array format of the field is used. When ``keys`` is a single value only the array belonging to the key is returned. :rtype: :class:`array-like` .. rubric:: Examples - :ref:`/examples/grib_lat_lon_value.ipynb` >>> import earthkit.data >>> ds = earthkit.data.from_source("file", "docs/examples/test6.grib") >>> d = ds[0].data() >>> d.shape (3, 7, 12) >>> d[0, 0, 0] # first latitude 90.0 >>> d[1, 0, 0] # first longitude 0.0 >>> d[2, 0, 0] # first value 272.56417847 >>> d = ds[0].data(keys="lon") >>> d.shape (7, 12) >>> d[0, 0] # first longitude 0.0 .. seealso:: :obj:`to_latlon`, :obj:`to_points`, :obj:`to_numpy`, :obj:`values` .. py:method:: datetime() Return the date and time of the field. :returns: Dict with items "base_time" and "valid_time". :rtype: :class:`dict` of :class:`datatime.datetime` .. rubric:: Examples >>> import earthkit.data >>> ds = earthkit.data.from_source("file", "tests/data/t_time_series.grib") >>> ds[4].datetime() {'base_time': datetime.datetime(2020, 12, 21, 12, 0), 'valid_time': datetime.datetime(2020, 12, 21, 18, 0)} .. py:method:: default_encoder() .. py:method:: describe(*args, **kwargs) Generate a summary of the Field. .. py:method:: dump(namespace=all, **kwargs) Generate dump with all the metadata keys belonging to ``namespace``. In a Jupyter notebook it is represented as a tabbed interface. :param namespace: The namespace to dump. The following `namespace` values have a special meaning: - :obj:`all`: all the available namespaces will be used. - None or empty str: all the available keys will be used (without a namespace qualifier) :type namespace: :obj:`str`, :obj:`list`, :obj:`tuple`, :obj:`None` or :obj:`all` :param \*\*kwargs: Other keyword arguments used for testing only :type \*\*kwargs: :class:`dict`, *optional* :returns: Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents. :rtype: :class:`NamespaceDump` .. rubric:: Examples :ref:`/examples/grib_metadata.ipynb` .. py:method:: grid_points() .. py:method:: grid_points_unrotated() .. py:method:: group_by(*args) Return iterator for batches of data grouped by metadata keys .. py:method:: h_datetime() .. py:property:: handle Get an object providing access to the low level GRIB message structure. :type: :class:`CodesHandle` .. py:method:: indexing_datetime() .. py:method:: isel(*args, **kwargs) :abstractmethod: .. py:method:: ls(*args, **kwargs) Generate a list like summary using a set of metadata keys. :param \*args: Positional arguments passed to :obj:`FieldList.ls`. :type \*args: :class:`tuple` :param \*\*kwargs: Other keyword arguments passed to :obj:`FieldList.ls`. :type \*\*kwargs: :class:`dict`, *optional* :returns: DataFrame with one row. :rtype: :class:`Pandas DataFrame` .. py:property:: mars_area .. py:property:: mars_grid .. py:method:: message() Return a buffer containing the encoded message. :rtype: :class:`bytes` .. py:method:: metadata(*keys, astype=None, remapping=None, patches=None, **kwargs) Return metadata values from the field. When called without any arguments returns a :obj:`Metadata` object. :param \*keys: Positional arguments specifying metadata keys. Can be empty, in this case all the keys from the specified ``namespace`` will be used. (See examples below). :type \*keys: :class:`tuple` :param astype: Return types for ``keys``. A single value is accepted and applied to all the ``keys``. Otherwise, must have same the number of elements as ``keys``. Only used when ``keys`` is not empty. :type astype: :class:`type name`, :obj:`list` or :obj:`tuple` :param remapping: Creates new metadata keys from existing ones that we can refer to in ``*args`` and ``**kwargs``. E.g. to define a new key "param_level" as the concatenated value of the "param" and "level" keys use:: remapping={"param_level": "{param}{level}"} :type remapping: :class:`dict`, *optional* :param \*\*kwargs: Other keyword arguments: * namespace: :obj:`str`, :obj:`list`, :obj:`tuple`, :obj:`None` or :obj:`all` The namespace to choose the ``keys`` from. When ``keys`` is empty and ``namespace`` is :obj:`all` all the available namespaces will be used. When ``keys`` is non empty ``namespace`` cannot specify multiple values and it cannot be :obj:`all`. When ``namespace`` is None or empty str all the available keys will be used (without a namespace qualifier). * default: value, optional Specifies the same default value for all the ``keys`` specified. When ``default`` is **not present** and a key is not found or its value is a missing value :obj:`metadata` will raise KeyError. :type \*\*kwargs: :class:`dict`, *optional* :returns: - when called without any arguments returns a :obj:`Metadata` object - when ``keys`` is not empty: - returns single value when ``keys`` is a str - otherwise returns the same type as that of ``keys`` (:obj:`list` or :obj:`tuple`) - when ``keys`` is empty: - when ``namespace`` is None or an empty str returns a :obj:`dict` with all the available keys and values - when ``namespace`` is :obj:`str` returns a :obj:`dict` with the keys and values in that namespace - otherwise returns a :obj:`dict` with one item per namespace (dict of dict) :rtype: :class:`single value`, :obj:`list`, :obj:`tuple`, :obj:`dict` or :obj:`Metadata` :raises KeyError: If no ``default`` is set and a key is not found in the message or it has a missing value. .. rubric:: Examples >>> import earthkit.data >>> ds = earthkit.data.from_source("file", "docs/examples/test.grib") Calling without arguments: >>> r = ds[0].metadata() >>> r >>> r["name"] '2 metre temperature' Getting keys with their native type: >>> ds[0].metadata("param") '2t' >>> ds[0].metadata("param", "units") ('2t', 'K') >>> ds[0].metadata(("param", "units")) ('2t', 'K') >>> ds[0].metadata(["param", "units"]) ['2t', 'K'] >>> ds[0].metadata(["param"]) ['2t'] >>> ds[0].metadata("badkey") KeyError: 'badkey' >>> ds[0].metadata("badkey", default=None) Prescribing key types: >>> ds[0].metadata("centre", astype=int) 98 >>> ds[0].metadata(["paramId", "centre"], astype=int) [167, 98] >>> ds[0].metadata(["centre", "centre"], astype=[int, str]) [98, 'ecmf'] Using namespaces: >>> ds[0].metadata(namespace="parameter") {'centre': 'ecmf', 'paramId': 167, 'units': 'K', 'name': '2 metre temperature', 'shortName': '2t'} >>> ds[0].metadata(namespace=["parameter", "vertical"]) {'parameter': {'centre': 'ecmf', 'paramId': 167, 'units': 'K', 'name': '2 metre temperature', 'shortName': '2t'}, 'vertical': {'typeOfLevel': 'surface', 'level': 0}} >>> r = ds[0].metadata(namespace=all) >>> r.keys() dict_keys(['default', 'ls', 'geography', 'mars', 'parameter', 'statistics', 'time', 'vertical']) >>> r = ds[0].metadata(namespace=None) >>> len(r) 186 >>> r["name"] '2 metre temperature' .. py:property:: offset Gets the offset (in bytes) of the GRIB field within the GRIB file. :type: number .. py:method:: order_by(*args, **kwargs) :abstractmethod: Reorder the elements of the object. .. py:method:: projection() Return information about the projection. :rtype: :obj:`Projection` .. rubric:: Examples >>> import earthkit.data >>> ds = earthkit.data.from_source("file", "docs/examples/test.grib") >>> ds.projection() Name: unknown Axis Info [cartesian]: - E[east]: Easting (unknown) - N[north]: Northing (unknown) - h[up]: Ellipsoidal height (metre) Area of Use: - undefined Coordinate Operation: - name: unknown - method: Equidistant Cylindrical Datum: Unknown based on WGS 84 ellipsoid - Ellipsoid: WGS 84 - Prime Meridian: Greenwich >>> ds.projection().to_proj_string() '+proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to_meter=111319.4907932736 +no_defs +type=crs' .. py:property:: resolution .. py:property:: rotation .. py:method:: save(filename, append=False, **kwargs) Write the field into a file. :param filename: The target file path, if not defined attempts will be made to detect the filename :type filename: :class:`str`, *optional* :param append: When it is true append data to the target file. Otherwise the target file be overwritten if already exists. Default is False :type append: :class:`bool`, *optional* :param \*\*kwargs: Other keyword arguments passed to :obj:`write`. :type \*\*kwargs: :class:`dict`, *optional* .. py:method:: sel(*args, **kwargs) :abstractmethod: Filter the object based on metadata. .. py:property:: shape Get the shape of the field. For structured grids the shape is a tuple in the form of (Nj, Ni) where: - ni: the number of gridpoints in i direction (longitude for a regular latitude-longitude grid) - nj: the number of gridpoints in j direction (latitude for a regular latitude-longitude grid) For other grid types the number of gridpoints is returned as ``(num,)`` :type: tuple .. py:method:: to_array(flatten=False, dtype=None, array_backend=None, array_namespace=None, device=None, index=None) Return the values stored in the field. :param flatten: When it is True a flat array is returned. Otherwise an array with the field's :obj:`shape` is returned. :type flatten: :class:`bool` :param dtype: Typecode or data-type of the array. When it is :obj:`None` the default type used by the underlying data accessor is used. For GRIB it is ``float64``. :type dtype: :class:`str`, :class:`array.dtype` or :obj:`None` :param array_backend: The array namespace to be used. When it is :obj:`None` the underlying array format of the field is used. **Deprecated since version 0.19.0**. Use ``array_namespace`` instead. In versions before 0.19.0 an :obj:`ArrayBackend` was also accepted here, which is no longer the case. :type array_backend: :class:`str`, :class:`array_namespace` or :obj:`None` :param array_namespace: The array namespace to be used. When it is :obj:`None` the underlying array format of the field is used. **New in version 0.19.0**. :type array_namespace: :class:`str`, :class:`array_namespace` or :obj:`None` :param device: The device where the array will be allocated. When it is :obj:`None` the default device is used. :type device: :class:`str` or :obj:`None` :param index: The index of the values and to be extracted. When it is None all the values are extracted :type index: :class:`array indexing object`, *optional* :returns: Field values. :rtype: :class:`array-array` .. py:method:: to_latlon(flatten=False, dtype=None, index=None) Return the latitudes/longitudes of all the gridpoints in the field. :param flatten: When it is True 1D arrays are returned. Otherwise arrays with the field's :obj:`shape` are returned. :type flatten: :class:`bool` :param dtype: Typecode or data-type of the arrays. When it is :obj:`None` the default type used by the underlying data accessor is used. For GRIB it is ``float64``. :type dtype: :class:`str`, :class:`array.dtype` or :obj:`None` :param index: The index of the latitudes/longitudes to be extracted. When it is None all the values are extracted. :type index: :class:`array indexing object`, *optional* :returns: Dictionary with items "lat" and "lon", containing the arrays of the latitudes and longitudes, respectively. The underlying array format of the field is used. :rtype: :class:`dict` .. seealso:: :obj:`to_points` .. py:method:: to_numpy(flatten=False, dtype=None, index=None) Return the values stored in the field as an ndarray. :param flatten: When it is True a flat ndarray is returned. Otherwise an ndarray with the field's :obj:`shape` is returned. :type flatten: :class:`bool` :param dtype: Typecode or data-type of the array. When it is :obj:`None` the default type used by the underlying data accessor is used. For GRIB it is ``float64``. :type dtype: :class:`str`, :class:`numpy.dtype` or :obj:`None` :param index: The index of the values and to be extracted. When it is None all the values are extracted :type index: :class:`ndarray indexing object`, *optional* :returns: Field values :rtype: :class:`ndarray` .. py:method:: to_pandas(**kwargs) :abstractmethod: Convert into a pandas dataframe .. py:method:: to_points(flatten=False, dtype=None, index=None) Return the geographical coordinates in the data's original Coordinate Reference System (CRS). :param flatten: When it is True 1D arrays are returned. Otherwise arrays with the field's :obj:`shape` are returned. :type flatten: :class:`bool` :param dtype: Typecode or data-type of the arrays. When it is :obj:`None` the default type used by the underlying data accessor is used. For GRIB it is ``float64``. :type dtype: :class:`str`, :class:`array.dtype` or :obj:`None` :param index: The index of the coordinates to be extracted. When it is None all the values are extracted. :type index: :class:`array indexing object`, *optional* :returns: Dictionary with items "x" and "y", containing the arrays of the x and y coordinates, respectively. The underlying array format of the field is used. :rtype: :class:`dict` :raises ValueError: When the coordinates in the data's original CRS are not available. .. seealso:: :obj:`to_latlon` .. py:method:: to_target(target, *args, **kwargs) Write the field into a target object. :param target: The target object to write the field into. :type target: :class:`object` :param \*args: Positional arguments used to specify the target object. :type \*args: :class:`tuple` :param \*\*kwargs: Other keyword arguments used to write the field into the target object. :type \*\*kwargs: :class:`dict`, *optional* .. py:method:: to_xarray(*args, **kwargs) Convert the Field into an Xarray Dataset. :param \*args: Positional arguments passed to :obj:`FieldList.to_xarray`. :type \*args: :class:`tuple` :param \*\*kwargs: Other keyword arguments passed to :obj:`FieldList.to_xarray`. :type \*\*kwargs: :class:`dict`, *optional* :rtype: :class:`Xarray Dataset` .. py:method:: unique_values(*coords, remapping=None, patches=None, progress_bar=False) Given a list of metadata attributes, such as date, param, levels, returns the list of unique values for each attributes .. py:method:: valid_datetime() .. py:property:: values Get the values stored in the field as a 1D array. :type: array-like .. py:method:: write(f, **kwargs)