Risk indicators — catalog & behaviour (offline)¶

Inspect the bundled dataset catalogue and the backend's design rules without touching the network: which datasets ship, their provider and output kind, the per-instance OUTPUT_KIND (tabular vs vector), the did-you-mean hint on a bad id, and why aggregate= is rejected. This is the no-network companion to the live quickstart.

In [ ]:

import tempfile

import pandas as pd

from earthlens.core import EarthLens

import tempfile import pandas as pd from earthlens.core import EarthLens

The shipped datasets¶

EarthLens.list_datasets("risk-indicators") lists every dataset id the backend accepts in variables= — no construction, no network.

In [ ]:

EarthLens.list_datasets("risk-indicators")

EarthLens.list_datasets("risk-indicators")

Catalogue rows — provider and output kind¶

EarthLens.catalog("risk-indicators") returns the bundled Catalog. Each row is a frozen pydantic Dataset carrying its provider, output_kind, and human label. The ids group cleanly by source — thinkhazard:*, inform:*, gfw:*.

In [ ]:

catalog = EarthLens.catalog("risk-indicators")
pd.DataFrame(
    [
        {
            "id": i,
            "provider": catalog.get(i).provider,
            "output_kind": catalog.get(i).output_kind,
            "long_name": catalog.get(i).long_name,
        }
        for i in catalog.available()
    ]
).set_index("id")

catalog = EarthLens.catalog("risk-indicators") pd.DataFrame( [ { "id": i, "provider": catalog.get(i).provider, "output_kind": catalog.get(i).output_kind, "long_name": catalog.get(i).long_name, } for i in catalog.available() ] ).set_index("id")

Per-instance OUTPUT_KIND¶

The backend's return shape is decided per dataset, not fixed for the whole backend. A thinkhazard:* / inform:* / gfw:tree_cover_loss row is tabular → it returns a pandas.DataFrame; gfw:admin_boundary is vector → it returns a pyramids FeatureCollection. The facade reads the resolved dataset's output_kind onto the instance OUTPUT_KIND to know the return shape (and to gate aggregate=).

In [ ]:

pd.DataFrame(
    [
        {"id": i, "output_kind": catalog.get(i).output_kind}
        for i in [
            "thinkhazard:flood_river",
            "inform:risk",
            "gfw:tree_cover_loss",
            "gfw:admin_boundary",
        ]
    ]
).set_index("id")

pd.DataFrame( [ {"id": i, "output_kind": catalog.get(i).output_kind} for i in [ "thinkhazard:flood_river", "inform:risk", "gfw:tree_cover_loss", "gfw:admin_boundary", ] ] ).set_index("id")

Resolving ids — with a did-you-mean hint¶

An unknown id raises a ValueError that suggests the closest match, rather than failing silently. (The cell below is expected to raise — it carries the raises-exception tag so notebook execution still passes.)

In [ ]:

raises-exception

EarthLens.catalog("risk-indicators").get("inform:rsk")

EarthLens.catalog("risk-indicators").get("inform:rsk")

aggregate= is rejected¶

These are pre-computed country-indexed indices, not gridded rasters, so there is no meaningful gridded reduction: passing a non-None aggregate= raises NotImplementedError. The guard fires in the facade before any network call (the inform:risk backend constructs without touching the network). Again shown via a raises-exception-tagged cell.

In [ ]:

raises-exception

EarthLens(
    data_source="inform",
    variables=["inform:risk"],
    country="KEN",
    path=tempfile.mkdtemp(),
).download(aggregate=object())

EarthLens( data_source="inform", variables=["inform:risk"], country="KEN", path=tempfile.mkdtemp(), ).download(aggregate=object())

Takeaway¶

• EarthLens.list_datasets("risk-indicators") and EarthLens.catalog(...) enumerate the shipped datasets and their metadata with no network.
• OUTPUT_KIND is per dataset: tabular ids return a DataFrame, gfw:admin_boundary returns a FeatureCollection.
• A bad id raises with a did-you-mean hint; aggregate= is rejected by design. See the quickstart and GFW notebook for the live calls.