Getting started

Open the site

Go to notebook.oceanum.io. JupyterLab and the Python kernel are downloaded on your first visit, which takes a moment; the browser caches them afterwards.

The file browser lists getting-started.ipynb, a short notebook shipped with the site that queries the Datamesh and plots the result. It is the quickest way to check that everything works.

Sign in

Use the sign-in button at the top right of the page — the same Oceanum.io sign-in used across the platform. It opens in a popup, so the page and any running kernels are left alone. If you are already signed in to Oceanum.io in the same browser, the notebook picks that session up as it loads.

Signing in does three things:

• sets DATAMESH_TOKEN in every kernel, and updates it whenever the credential is refreshed;

• points the kernel at the Datamesh service through DATAMESH_SERVICE;

• enables opening, saving and sharing notebooks on Oceanum.io.

Sign in to Oceanum.io and Sign out of Oceanum.io are also in the command palette, under the Oceanum category.

Query the Datamesh

from oceanum.datamesh import Connector

datamesh = Connector()
datamesh.get_catalog(search="era5", limit=5)

Connector() picks up the credentials the sign-in placed in the kernel, so there is nothing to configure. Those credentials are short-lived and refreshed in the background while the notebook is open, so create a connector when you need one rather than holding on to it for hours.

Queries return the objects you would expect from the Python library, and you work with them as you would locally:

wind = datamesh.query(
    datasource="era5_wind10m_demo",
    variables=["u10", "v10"],
    timefilter={"times": ["2020-01-01T00:00:00Z", "2020-01-01T06:00:00Z"]},
    geofilter={"type": "bbox", "geom": [172.0, -42.0, 176.0, -38.0]},
)
speed = (wind.u10**2 + wind.v10**2) ** 0.5
speed.isel(time=0).plot()

Working without signing in

You can use a Datamesh token instead of signing in. Set it in a cell before you create a connector:

import os

os.environ["DATAMESH_TOKEN"] = "your-token-here"

A token you set yourself is left alone — signing in later does not overwrite it. Never save or share a notebook with a token written into a cell; see Saving and sharing.

Where your work is kept

Notebooks and files in the JupyterLab file browser are stored in the browser you are using. They survive a reload, but they are not synced anywhere: another browser or machine will not see them, and clearing site data for notebook.oceanum.io removes them. Use File → Save to Oceanum to keep a copy in your Oceanum.io account.

Browser support

The kernel fetches packages as they are imported, including packages that a library imports while it is running — xarray’s .plot() pulling in matplotlib, for example. That relies on JavaScript Promise Integration, which Chrome supports. In a browser without it, import the package yourself in a cell first:

import matplotlib