New Contributors

• @clarasb made their first contribution in #984

Changes in 1.6.0

Full Changelog: v1.5.1...v1.6.0

Enhancements

• Includes new xcube Viewer 1.2

• Added new statistics API to xcube server. The service computes basic
  statistical values and a histogram for given data variable, time stamp,
  and a GeoJSON geometry. Its endpoint is:
  /statistics/{datasetId}/{varName}?time={time}. Geometry is passed as
  request body in form of a GeoJSON geometry object.

• xcube server's tile API can now handle user-defined colormaps from xcube
  viewer. Custom color bars are still passed using query parameter cmap to
  endpoint /tiles/{datasetId}/{varName}/{z}/{y}/{x},
  but in the case of custom color bars it is a JSON-encoded object with the
  following format: {"name": <str>, "type": <str>, "colors": <list>}. (#975)
  The object properties are

  • name: a unique name.
  • type: optional type of control values.
  • colors: a list of pairs [[<v1>,<c1>], [<v2>,<c2>], [<v3>,<c3>], ...]
    that map a control value to a hexadecimal color value using CSS format
    "#RRGGBBAA".

  The type values are

  • "node": control points are nodes of a continuous color gradient.
  • "bound": control points form bounds that map to a color, which means
    the last color is unused.
  • "key": control points are keys (integers) that identify a color.

• xcube server's tile API now allows specifying the data normalisation step
  before a color mapping is applied to the variable data to be visualized.
  This affects endpoint /tiles/{datasetId}/{varName}/{z}/{y}/{x} and the WMTS
  API. The possible normalisation values are

  • lin: linear mapping of data values between vmin and vmax to range 0 to 1
    (uses matplotlib.colors.Normalize(vmin, vmax)).
  • log: logarithmic mapping of data values between vmin and vmax to range 0 to 1
    (uses matplotlib.colors.LogNorm(vmin, vmax)).
  • cat: categorical mapping of data values to indices into the color mapping.
    (uses matplotlib.colors.BoundaryNorm(categories)). This normalisation
    currently only works with user-defined colormaps of type
    key or bound (see above).

  The normalisation can be specified in three different ways (in order):

  1. As query parameter norm passed to the tile endpoint.
  2. Property Norm in the Styles/ColorMapping element in xcube server configuration.
  3. Data variable attribute color_norm.

• xcube server can now read SNAP color palette definition files (*.cpd) with
  alpha values. (#932)

• The class xcube.webapi.viewer.Viewer now accepts root paths or URLs that
  will each be scanned for datasets. The roots are passed as keyword argument
  roots whose value is a path or URL or an iterable of paths or URLs.
  A new keyword argument max_depth defines the maximum subdirectory depths
  used to search for datasets in case roots is given. It defaults to 1.

• The behaviour of function resample_in_space() of module
  xcube.core.resampling changed in this version. (#1001)

  1. A new keyword argument ref_ds can now be used to provide
     a reference dataset for the reprojection. It can be passed instead
     of target_rm. If ref_ds is given, it also forces the returned target
     dataset to have the same spatial coordinates as ref_ds.
  2. In the case of up-sampling, we no longer recover NaN values by default
     as it may require considerable CPU overhead.
     To enforce the old behaviour, provide the var_configs keyword-argument
     and set recover_nan to True for desired variables.

• The class MaskSet() of module xcube.core.maskset now correctly recognises
  the variable attributes flag_values, flag_masks, flag_meanings when
  their values are lists (ESA CCI LC data encodes them as JSON arrays). (#1002)

• The class MaskSet() now provides a method get_cmap() which creates
  a suitable matplotlib color map for variables that define the
  flag_values CF-attribute and optionally a flag_colors attribute. (#1011)

• The Api.route decorator and ApiRoute constructor in
  xcube.server.api now have a slash argument which lets a route support an
  optional trailing slash.

Fixes

• When using the xcube.webapi.viewer.Viewer class in Jupyter notebooks
  multi-level datasets opened from S3 or from deeper subdirectories into
  the local filesystem are now fully supported. (#1007)

• Fixed an issue with xcube server /timeseries endpoint that returned
  status 500 if a given dataset used a CRS other geographic and the
  geometry was not a point. (#995)

• Fixed broken table of contents links in dataset convention document.

• Web API endpoints with an optional trailing slash are no longer listed
  twice in the automatically generated OpenAPI documentation (#965)

• Several minor updates to make xcube compatible with NumPy 2.0.0 (#1024)

Incompatible API changes

• The get_cmap() method of util.cmaps.ColormapProvider now returns a
  Tuple[matplotlib.colors.Colormap, Colormap] instead of
  Tuple[str, matplotlib.colors.Colormap].

• The signatures of functions resample_in_space(), rectify_dataset(), and
  affine_transform_dataset() of module xcube.core.resampling changed:

  • Source dataset must be provided as 1st positional argument.
  • Introduced keyword argument ref_ds that can be provided instead of
    target_gm. If given, it forces the returned dataset to have the same
    coordinates as ref_ds.

• Removed API deprecated since many releases:

  • Removed keyword argument base from function
    xcube.core.resampling.temporal.resample_in_time().
  • Removed option base from CLI command xcube resample.
  • Removed keyword argument assert_cube from
    xcube.core.timeseries.get_time_series().
  • Removed property xcube.core.xarray.DatasetAccessor.levels.
  • Removed function xcube.core.tile.parse_non_spatial_labels().
  • Removed keyword argument tag from context manager
    xcube.util.perf.measure_time().
  • Removed function xcube.core.geom.convert_geometry().
  • Removed function xcube.core.geom.is_dataset_y_axis_inverted().
  • Removed function xcube.util.assertions.assert_condition().
  • Removed function xcube.util.cmaps.get_cmaps().
  • Removed function xcube.util.cmaps.get_cmap().
  • Removed function xcube.util.cmaps.ensure_cmaps_loaded().
  • Removed endpoint /datasets/{datasetId}/vars/{varName}/tiles2/{z}/{y}/{x}
    from xcube server.

Other changes

• Make tests compatible with PyTest 8.2.0. (#973)

• Addressed all warnings from xarray indicating that Dataset.dims will
  be replaced by Dataset.sizes. (#981)

• NUMBA_DISABLE_JIT set to 0 to enable numba.jit in github workflow. (#946)

• Added GitHub workflow to perform an automatic xcube release on PyPI after a GitHub
  release. To install xcube via the pip tool use pip install xcube-core,
  since the name "xcube" is already taken on PyPI by another software. (#982)

• Added project URLs and classifiers to setup.py, which will be shown in the
  left sidebar on the PyPI xcube-core webpage.

• Refactored xcube workflow to build docker images only on release and deleted the
  update xcube tag job.

• Used pyupgrade to automatically upgrade
  language syntax for Python versions >= 3.9.

• Migrated the xcube project setup from setup.py to the modern pyproject.toml format.

• The functions mask_dataset_by_geometry() and clip_dataset_by_geometry()
  of module xcube.core.geom have a new keyword argument
  update_attrs: bool = True as part of the fix for #995.

• Decreased number of warnings in the xcube workflow step unittest-xcube.

• Added new data store "https" that uses
  fsspec.implementations.http.HTTPFileSystem),
  so that the upcoming xcube STAC data store will be able to access files from URLs.

• The workflow .github/workflows/xcube_publish_pypi.yml changes the line in the pyproject.toml, where
  the package name is defined to name = "xcube-core". This allows to release xcube under
  the package name "xcube-core" on PyPI where the name "xcube" is already taken. #1010

• Updated the 'How do I ...' page in the xcube documentation.