4.2.3.1. Using the ESA CCI Toolbox with the xcube Viewer

The xcube viewer is an easy way to display gridded data. In this notebook, we show how the viewer can be started from a notebook and how cci datasets can be added to it.

To run this Notebook, make sure the ESA CCI Toolbox is setup correctly.

The viewer requires datasets. For this notebook, we will access them from the Zarr store and the regular store.

from xcube.core.store import new_data_store

zarr_store = new_data_store('esa-cci-zarr')
cci_store = new_data_store('esa-cci')

If you want, you can execute the following lines to see which datasets are available. For now, this part is in a comment as we do not want to print all the datasets for reasons of readability.

# zarr_store.list_data_ids()

# cci_store.list_data_ids()

From the Zarr store, we pick a snow dataset.

snow_ds = zarr_store.open_data('ESACCI-L3C_SNOW-SWE-1979-2020-fv2.0.zarr')
snow_ds

<xarray.Dataset> Size: 823GB
Dimensions:   (lat: 1800, nv: 2, lon: 3600, time: 7934)
Coordinates:
  * lat       (lat) float64 14kB -89.95 -89.85 -89.75 ... 89.75 89.85 89.95
    lat_bnds  (lat, nv) float64 29kB dask.array<chunksize=(900, 2), meta=np.ndarray>
  * lon       (lon) float64 29kB -179.9 -179.8 -179.8 ... 179.7 179.8 179.9
    lon_bnds  (lon, nv) float64 58kB dask.array<chunksize=(900, 2), meta=np.ndarray>
  * time      (time) datetime64[ns] 63kB 1979-01-02 1979-01-04 ... 2020-05-24
Dimensions without coordinates: nv
Data variables:
    swe       (time, lat, lon) float64 411GB dask.array<chunksize=(10, 900, 900), meta=np.ndarray>
    swe_std   (time, lat, lon) float64 411GB dask.array<chunksize=(10, 900, 900), meta=np.ndarray>
Attributes: (12/43)
    Conventions:                CF-1.9
    cdm_data_type:              grid
    comment:                    The following auxiliary datasets are used for...
    creator_email:              kari.luojus@fmi.fi (Scientific and Production...
    creator_name:               Finnish Meteorological Institute
    creator_url:                www.fmi.fi
    ...                         ...
    time_coverage_duration:     P1D
    time_coverage_end:          20200524T000000Z
    time_coverage_resolution:   P1D
    time_coverage_start:        19790102T000000Z
    title:                      ESA CCI snow SWE product level L3C daily, Dyn...
    tracking_id:                25063fb5-47ad-424a-8f26-29bdf35efb78

xarray.Dataset

• Dimensions:
  • lat: 1800
  • nv: 2
  • lon: 3600
  • time: 7934
• Coordinates: (5)
  • lat
    (lat)
    float64
    -89.95 -89.85 ... 89.85 89.95

    axis :

    Y

    bounds :

    lat_bnds

    long_name :

    WGS84 latitude coordinates, center of pixel

    standard_name :

    latitude

    units :

    degree_north

    array([-89.95, -89.85, -89.75, ...,  89.75,  89.85,  89.95])

  • lat_bnds
    (lat, nv)
    float64
    dask.array<chunksize=(900, 2), meta=np.ndarray>

    Array Chunk Bytes 28.12 kiB 14.06 kiB Shape (1800, 2) (900, 2) Dask graph 2 chunks in 2 graph layers Data type float64 numpy.ndarray

  • lon
    (lon)
    float64
    -179.9 -179.8 ... 179.8 179.9

    axis :

    X

    bounds :

    lon_bnds

    long_name :

    WGS84 longitude coordinates, center of pixel

    standard_name :

    longitude

    units :

    degree_east

    array([-179.95, -179.85, -179.75, ...,  179.75,  179.85,  179.95])

  • lon_bnds
    (lon, nv)
    float64
    dask.array<chunksize=(900, 2), meta=np.ndarray>

    Array Chunk Bytes 56.25 kiB 14.06 kiB Shape (3600, 2) (900, 2) Dask graph 4 chunks in 2 graph layers Data type float64 numpy.ndarray

  • time
    (time)
    datetime64[ns]
    1979-01-02 ... 2020-05-24

    axis :

    T

    long_name :

    time

    standard_name :

    time

    array(['1979-01-02T00:00:00.000000000', '1979-01-04T00:00:00.000000000',
           '1979-01-06T00:00:00.000000000', ..., '2020-05-15T00:00:00.000000000',
           '2020-05-20T00:00:00.000000000', '2020-05-24T00:00:00.000000000'],
          dtype='datetime64[ns]')

• Data variables: (2)
  • swe
    (time, lat, lon)
    float64
    dask.array<chunksize=(10, 900, 900), meta=np.ndarray>

    actual_range :

    [1, 187]

    ancillary_variables :

    swe_std

    flag_meanings :

    Glacier Mountain Water no_data no_snow

    flag_values :

    [-30, -20, -10, -1, 0]

    grid_mapping :

    spatial_ref

    long_name :

    Snow Water Equivalent

    units :

    mm

    valid_range :

    [1, 500]

    Array Chunk Bytes 383.05 GiB 61.80 MiB Shape (7934, 1800, 3600) (10, 900, 900) Dask graph 6352 chunks in 2 graph layers Data type float64 numpy.ndarray

  • swe_std
    (time, lat, lon)
    float64
    dask.array<chunksize=(10, 900, 900), meta=np.ndarray>

    actual_range :

    [0, 72]

    flag_meanings :

    Glacier Mountain Water no_data no_snow

    flag_values :

    [-30, -20, -10, -1, 0]

    grid_mapping :

    spatial_ref

    long_name :

    statistical standard deviation of estimate

    units :

    mm

    valid_range :

    [1, 250]

    Array Chunk Bytes 383.05 GiB 61.80 MiB Shape (7934, 1800, 3600) (10, 900, 900) Dask graph 6352 chunks in 2 graph layers Data type float64 numpy.ndarray

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([            -89.95, -89.85000000000001, -89.75000000000001,
           -89.65000000000002, -89.55000000000003, -89.45000000000003,
           -89.35000000000004, -89.25000000000004, -89.15000000000005,
           -89.05000000000005,
           ...
            89.04999999998982,  89.14999999998982,  89.24999999998981,
             89.3499999999898,   89.4499999999898,   89.5499999999898,
            89.64999999998979,  89.74999999998978,  89.84999999998978,
            89.94999999998977],
          dtype='float64', name='lat', length=1800))

  • lon
    PandasIndex

    PandasIndex(Index([            -179.95,             -179.85,             -179.75,
                       -179.65,             -179.55, -179.45000000000002,
           -179.35000000000002, -179.25000000000003, -179.15000000000003,
           -179.05000000000004,
           ...
             179.0499999999796,  179.14999999997957,   179.2499999999796,
            179.34999999997962,  179.44999999997958,  179.54999999997955,
            179.64999999997957,   179.7499999999796,  179.84999999997956,
            179.94999999997953],
          dtype='float64', name='lon', length=3600))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['1979-01-02', '1979-01-04', '1979-01-06', '1979-01-08',
                   '1979-01-10', '1979-01-12', '1979-01-14', '1979-01-16',
                   '1979-01-18', '1979-01-20',
                   ...
                   '2020-05-05', '2020-05-06', '2020-05-07', '2020-05-08',
                   '2020-05-09', '2020-05-12', '2020-05-14', '2020-05-15',
                   '2020-05-20', '2020-05-24'],
                  dtype='datetime64[ns]', name='time', length=7934, freq=None))

• Attributes: (43)

  Conventions :

  CF-1.9

  cdm_data_type :

  grid

  comment :

  The following auxiliary datasets are used for product generation: ESA CCI Land Cover from 2000: water bodies aggregated to the pixel spacing of the SWE product and, providing percentage (0-100)% of water within pixel, with 50% threshold used for this version of the product. ETOPO5 based mountain mask for northern hemisphere, first produced for needs of ESA_GlobSnow project.

  creator_email :

  kari.luojus@fmi.fi (Scientific and Production contact), mikko.moisander@fmi.fi (file format & metadata issues)

  creator_name :

  Finnish Meteorological Institute

  creator_url :

  www.fmi.fi

  date_created :

  20211129T131437Z

  doi :

  10.5285/4647cc9ad3c044439d6c643208d3c494

  format_version :

  CCI Data Standards v2.3, 2021

  geospatial_lat_max :

  90

  geospatial_lat_min :

  -90

  geospatial_lat_resolution :

  0.1

  geospatial_lat_units :

  degrees north

  geospatial_lon_max :

  180

  geospatial_lon_min :

  -180

  geospatial_lon_resolution :

  0.1

  geospatial_lon_units :

  degrees east

  geospatial_vertical_max :

  0

  geospatial_vertical_min :

  0

  history :

  20220207T140902Z: ESA snow_cci SWE processing line, version CP3 v2.0, Dynamic snow density, PMW-snow melt mask

  id :

  20200524-ESACCI-L3C_SNOW-SWE-SSMIS-DMSP-fv2.0.nc

  institution :

  FMI

  key_variables :

  swe

  keywords :

  SSMIS, snow water equivalent, DMSP

  keywords_vocabulary :

  NASA Global Change Master Directory (GCMD) Science Keywords

  license :

  ESA CCI Data Policy: free and open access; access to prototype products restricted

  naming_authority :

  fi.fmi

  platform :

  DMSP F17

  product_version :

  2.0

  project :

  Climate Change Initiative European Space Agency

  references :

  http://snow-cci.enveo.at/

  sensor :

  SSMI/S

  source :

  SSMIS brightness temperature data from 19 & 37GHz channels. WMO synoptic in-situ snow depth measurements, daily averages

  spatial_ref :

  -2147483647

  spatial_resolution :

  0.10 degree

  standard_name_vocabulary :

  CF Standard Name Table v75

  summary :

  The ESA CCI Snow SWE product provides daily information on mass of the snow cover. Snow water equivalent (swe) is measure of the ammount of water contained within a snow pack and is provided in mm, similar to precipitation information. The product is based on low resolution passive microwave satellite data combined with in-situ snow depth measurements and is provided resampled to 0.10 degree latitude longitude grid. Information is provided on all land areas on Northern hemisphere excluding mountainous regions, glaciers and Greenland that have been masked from the product. The SWE estimates are complemented with statistically derived accuracy estimate accompanying each SWE estimate (on a pixel level).

  time_coverage_duration :

  P1D

  time_coverage_end :

  20200524T000000Z

  time_coverage_resolution :

  P1D

  time_coverage_start :

  19790102T000000Z

  title :

  ESA CCI snow SWE product level L3C daily, Dynamic snow density, PMW-snow melt mask

  tracking_id :

  25063fb5-47ad-424a-8f26-29bdf35efb78

From the cci store, we pick an aerosol dataset. However, let’s just use a subset here, to see how it will look in the viewer.

x1 = -23.40  # degree
y1 = -40.40  # degree
x2 = 57.40  # degree
y2 = 40.40  # degree
bbox = (x1, y1, x2, y2)

aerosol_ds = cci_store.open_data(
    'esacci.AEROSOL.mon.L3.AAI.multi-sensor.multi-platform.MSAAI.1-7.r1',
    variable_names=['absorbing_aerosol_index'],
    bbox=bbox,
    time_range=['2005-01-01', '2005-12-31']
)
aerosol_ds

<xarray.Dataset> Size: 308kB
Dimensions:                  (time: 12, lat: 80, lon: 80, bnds: 2)
Coordinates:
  * lat                      (lat) float32 320B -39.5 -38.5 -37.5 ... 38.5 39.5
  * lon                      (lon) float32 320B -22.5 -21.5 -20.5 ... 55.5 56.5
  * time                     (time) datetime64[ns] 96B 2005-01-16T12:00:00 .....
    time_bnds                (time, bnds) datetime64[ns] 192B dask.array<chunksize=(12, 2), meta=np.ndarray>
Dimensions without coordinates: bnds
Data variables:
    absorbing_aerosol_index  (time, lat, lon) float32 307kB dask.array<chunksize=(1, 80, 80), meta=np.ndarray>
Attributes:
    Conventions:             CF-1.7
    title:                   esacci.AEROSOL.mon.L3.AAI.multi-sensor.multi-pla...
    date_created:            2025-12-04T11:52:18.378325
    processing_level:        L3
    time_coverage_start:     2005-01-01T00:00:00
    time_coverage_end:       2006-01-01T00:00:00
    time_coverage_duration:  P365DT0H0M0S
    history:                 [{'program': 'xcube_cci.chunkstore.CciChunkStore...

xarray.Dataset

• Dimensions:
  • time: 12
  • lat: 80
  • lon: 80
  • bnds: 2
• Coordinates: (4)
  • lat
    (lat)
    float32
    -39.5 -38.5 -37.5 ... 38.5 39.5

    long_name :

    Latitudes of the centre of the grid cells

    units :

    degrees

    orig_data_type :

    float32

    fill_value :

    nan

    size :

    80

    shape :

    [80]

    chunk_sizes :

    [80]

    file_chunk_sizes :

    [80]

    data_type :

    float32

    dimensions :

    ['latitude']

    file_dimensions :

    ['latitude']

    array([-39.5, -38.5, -37.5, -36.5, -35.5, -34.5, -33.5, -32.5, -31.5, -30.5,
           -29.5, -28.5, -27.5, -26.5, -25.5, -24.5, -23.5, -22.5, -21.5, -20.5,
           -19.5, -18.5, -17.5, -16.5, -15.5, -14.5, -13.5, -12.5, -11.5, -10.5,
            -9.5,  -8.5,  -7.5,  -6.5,  -5.5,  -4.5,  -3.5,  -2.5,  -1.5,  -0.5,
             0.5,   1.5,   2.5,   3.5,   4.5,   5.5,   6.5,   7.5,   8.5,   9.5,
            10.5,  11.5,  12.5,  13.5,  14.5,  15.5,  16.5,  17.5,  18.5,  19.5,
            20.5,  21.5,  22.5,  23.5,  24.5,  25.5,  26.5,  27.5,  28.5,  29.5,
            30.5,  31.5,  32.5,  33.5,  34.5,  35.5,  36.5,  37.5,  38.5,  39.5],
          dtype=float32)

  • lon
    (lon)
    float32
    -22.5 -21.5 -20.5 ... 55.5 56.5

    long_name :

    Longitudes of the centre of the grid cells

    units :

    degrees

    orig_data_type :

    float32

    fill_value :

    nan

    size :

    80

    shape :

    [80]

    chunk_sizes :

    [80]

    file_chunk_sizes :

    [80]

    data_type :

    float32

    dimensions :

    ['longitude']

    file_dimensions :

    ['longitude']

    array([-22.5, -21.5, -20.5, -19.5, -18.5, -17.5, -16.5, -15.5, -14.5, -13.5,
           -12.5, -11.5, -10.5,  -9.5,  -8.5,  -7.5,  -6.5,  -5.5,  -4.5,  -3.5,
            -2.5,  -1.5,  -0.5,   0.5,   1.5,   2.5,   3.5,   4.5,   5.5,   6.5,
             7.5,   8.5,   9.5,  10.5,  11.5,  12.5,  13.5,  14.5,  15.5,  16.5,
            17.5,  18.5,  19.5,  20.5,  21.5,  22.5,  23.5,  24.5,  25.5,  26.5,
            27.5,  28.5,  29.5,  30.5,  31.5,  32.5,  33.5,  34.5,  35.5,  36.5,
            37.5,  38.5,  39.5,  40.5,  41.5,  42.5,  43.5,  44.5,  45.5,  46.5,
            47.5,  48.5,  49.5,  50.5,  51.5,  52.5,  53.5,  54.5,  55.5,  56.5],
          dtype=float32)

  • time
    (time)
    datetime64[ns]
    2005-01-16T12:00:00 ... 2005-12-...

    standard_name :

    time

    bounds :

    time_bnds

    array(['2005-01-16T12:00:00.000000000', '2005-02-15T00:00:00.000000000',
           '2005-03-16T12:00:00.000000000', '2005-04-16T00:00:00.000000000',
           '2005-05-16T12:00:00.000000000', '2005-06-16T00:00:00.000000000',
           '2005-07-16T12:00:00.000000000', '2005-08-16T12:00:00.000000000',
           '2005-09-16T00:00:00.000000000', '2005-10-16T12:00:00.000000000',
           '2005-11-16T00:00:00.000000000', '2005-12-16T12:00:00.000000000'],
          dtype='datetime64[ns]')

  • time_bnds
    (time, bnds)
    datetime64[ns]
    dask.array<chunksize=(12, 2), meta=np.ndarray>

    standard_name :

    time_bnds

    Array Chunk Bytes 192 B 192 B Shape (12, 2) (12, 2) Dask graph 1 chunks in 2 graph layers Data type datetime64[ns] numpy.ndarray

• Data variables: (1)
  • absorbing_aerosol_index
    (time, lat, lon)
    float32
    dask.array<chunksize=(1, 80, 80), meta=np.ndarray>

    long_name :

    Absorbing aerosol index averaged for each grid cell

    units :

    1

    orig_data_type :

    float32

    fill_value :

    nan

    size :

    76800

    shape :

    [12, 80, 80]

    chunk_sizes :

    [1, 80, 80]

    file_chunk_sizes :

    [80, 80]

    data_type :

    float32

    dimensions :

    ['time', 'latitude', 'longitude']

    file_dimensions :

    ['latitude', 'longitude']

    Array Chunk Bytes 300.00 kiB 25.00 kiB Shape (12, 80, 80) (1, 80, 80) Dask graph 12 chunks in 2 graph layers Data type float32 numpy.ndarray

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([-39.5, -38.5, -37.5, -36.5, -35.5, -34.5, -33.5, -32.5, -31.5, -30.5,
           -29.5, -28.5, -27.5, -26.5, -25.5, -24.5, -23.5, -22.5, -21.5, -20.5,
           -19.5, -18.5, -17.5, -16.5, -15.5, -14.5, -13.5, -12.5, -11.5, -10.5,
            -9.5,  -8.5,  -7.5,  -6.5,  -5.5,  -4.5,  -3.5,  -2.5,  -1.5,  -0.5,
             0.5,   1.5,   2.5,   3.5,   4.5,   5.5,   6.5,   7.5,   8.5,   9.5,
            10.5,  11.5,  12.5,  13.5,  14.5,  15.5,  16.5,  17.5,  18.5,  19.5,
            20.5,  21.5,  22.5,  23.5,  24.5,  25.5,  26.5,  27.5,  28.5,  29.5,
            30.5,  31.5,  32.5,  33.5,  34.5,  35.5,  36.5,  37.5,  38.5,  39.5],
          dtype='float32', name='lat'))

  • lon
    PandasIndex

    PandasIndex(Index([-22.5, -21.5, -20.5, -19.5, -18.5, -17.5, -16.5, -15.5, -14.5, -13.5,
           -12.5, -11.5, -10.5,  -9.5,  -8.5,  -7.5,  -6.5,  -5.5,  -4.5,  -3.5,
            -2.5,  -1.5,  -0.5,   0.5,   1.5,   2.5,   3.5,   4.5,   5.5,   6.5,
             7.5,   8.5,   9.5,  10.5,  11.5,  12.5,  13.5,  14.5,  15.5,  16.5,
            17.5,  18.5,  19.5,  20.5,  21.5,  22.5,  23.5,  24.5,  25.5,  26.5,
            27.5,  28.5,  29.5,  30.5,  31.5,  32.5,  33.5,  34.5,  35.5,  36.5,
            37.5,  38.5,  39.5,  40.5,  41.5,  42.5,  43.5,  44.5,  45.5,  46.5,
            47.5,  48.5,  49.5,  50.5,  51.5,  52.5,  53.5,  54.5,  55.5,  56.5],
          dtype='float32', name='lon'))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['2005-01-16 12:00:00', '2005-02-15 00:00:00',
                   '2005-03-16 12:00:00', '2005-04-16 00:00:00',
                   '2005-05-16 12:00:00', '2005-06-16 00:00:00',
                   '2005-07-16 12:00:00', '2005-08-16 12:00:00',
                   '2005-09-16 00:00:00', '2005-10-16 12:00:00',
                   '2005-11-16 00:00:00', '2005-12-16 12:00:00'],
                  dtype='datetime64[ns]', name='time', freq=None))

• Attributes: (8)

  Conventions :

  CF-1.7

  title :

  esacci.AEROSOL.mon.L3.AAI.multi-sensor.multi-platform.MSAAI.1-7.r1

  date_created :

  2025-12-04T11:52:18.378325

  processing_level :

  L3

  time_coverage_start :

  2005-01-01T00:00:00

  time_coverage_end :

  2006-01-01T00:00:00

  time_coverage_duration :

  P365DT0H0M0S

  history :

  [{'program': 'xcube_cci.chunkstore.CciChunkStore', 'cube_params': {'variable_names': ['absorbing_aerosol_index'], 'time_range': ['2005-01-01T00:00:00', '2005-12-31T00:00:00'], 'bbox': [-23.4, -40.4, 57.4, 40.4]}}]

Now that we have the datasets assembled, we can start the viewer. We import it from xcube like this:

from xcube.webapi.viewer import Viewer

viewer = Viewer()

404 GET /viewer/config/config.json (127.0.0.1): xcube viewer has not been been configured
404 GET /viewer/config/config.json (127.0.0.1) 11.21ms
501 GET /viewer/state?key=sentinel (127.0.0.1) 0.27ms
404 GET /viewer/ext/contributions (127.0.0.1) 0.32ms

Next, we add the datasets.

viewer.add_dataset(snow_ds)

'63622925-cb47-4e27-9346-0d0acc930130'

viewer.add_dataset(aerosol_ds)

'5c042aa5-b2de-47db-b7af-2051191afb16'

Now that the viewer is set up, we can ask for information about it. With the following command, we get the links for the server and the viewer. The server is responsible for serving the datasets. You may take the link and use it with any running viewer. However, it is directly plugged into the viewer instance which you can open from its link.

viewer.info()

Server: http://localhost:8000
Viewer: http://localhost:8000/viewer/?serverUrl=http://localhost:8000

Alternatively, you can open the viewer in a notebook cell:

viewer.show()