Glaciers — catalog & behaviour (no network)¶

This notebook explores the glaciers catalog and the backend's behaviour without downloading any data. You'll learn the five datasets, how a bounding box maps to a GTN-G region, why the output shape is per instance, and why aggregate= is rejected.

The catalog¶

Catalog loads the bundled dataset definitions. available() lists the shipped dataset ids across the three sources.

In [ ]:

from earthlens.glaciers import Catalog

cat = Catalog()
cat.available()

from earthlens.glaciers import Catalog cat = Catalog() cat.available()

Each id resolves to a typed row carrying its source and output kind — vector for the RGI/GLIMS outlines, tabular for the WGMS fluctuations. This is the field the backend copies onto its OUTPUT_KIND per instance.

In [ ]:

import pandas as pd

rows = [
    {
        'id': d,
        'source': cat.get(d).source,
        'output_kind': cat.get(d).output_kind,
        'long_name': cat.get(d).long_name,
    }
    for d in cat.available()
]
pd.DataFrame(rows)

import pandas as pd rows = [ { 'id': d, 'source': cat.get(d).source, 'output_kind': cat.get(d).output_kind, 'long_name': cat.get(d).long_name, } for d in cat.available() ] pd.DataFrame(rows)

The GTN-G region table¶

RGI ships one shapefile per GTN-G first-order region. The catalog carries each region's bounding box(es) and download URL, and the backend uses them to turn your bbox into the region(s) to fetch. Region 10 (North Asia) crosses the antimeridian, so it has two boxes.

In [ ]:

region_rows = [
    {'id': r, 'name': cat.regions[r].name, 'n_boxes': len(cat.regions[r].bboxes)}
    for r in sorted(cat.regions)
]
pd.DataFrame(region_rows)

region_rows = [ {'id': r, 'name': cat.regions[r].name, 'n_boxes': len(cat.regions[r].bboxes)} for r in sorted(cat.regions) ] pd.DataFrame(region_rows)

regions_for_bbox is the helper that maps an area of interest ([west, south, east, north]) to the overlapping region id(s). An Alpine box lands in region 11; an East-Siberian box lands in region 10 via its second sub-box.

In [ ]:

from earthlens.glaciers import regions_for_bbox

alps = regions_for_bbox([6.8, 45.8, 7.2, 46.05], cat.regions)
siberia = regions_for_bbox([150.0, 60.0, 160.0, 65.0], cat.regions)
alps, siberia

from earthlens.glaciers import regions_for_bbox alps = regions_for_bbox([6.8, 45.8, 7.2, 46.05], cat.regions) siberia = regions_for_bbox([150.0, 60.0, 160.0, 65.0], cat.regions) alps, siberia

Per-instance output shape¶

Because the catalog mixes vector and tabular datasets, the backend sets OUTPUT_KIND from the dataset you choose. A construction with an RGI dataset is vector; one with a WGMS dataset is tabular. (We construct the backends here — no download happens until .download().)

In [ ]:

from earthlens.core import EarthLens

rgi = EarthLens(data_source='glaciers', variables=['rgi:outlines'], region='11')
wgms = EarthLens(data_source='glaciers', variables=['wgms:mass_balance'])
rgi.datasource.OUTPUT_KIND, wgms.datasource.OUTPUT_KIND

from earthlens.core import EarthLens rgi = EarthLens(data_source='glaciers', variables=['rgi:outlines'], region='11') wgms = EarthLens(data_source='glaciers', variables=['wgms:mass_balance']) rgi.datasource.OUTPUT_KIND, wgms.datasource.OUTPUT_KIND

Why aggregate= is rejected¶

Outlines and fluctuations are pre-computed inventories / measurements, not gridded fields, so there is no meaningful time-window or spatial reduction. Passing aggregate= raises NotImplementedError — a clear signal rather than a silent no-op.

In [ ]:

try:
    rgi.datasource.download(aggregate=object())
except NotImplementedError as exc:
    print('rejected:', str(exc).split(':')[0])

try: rgi.datasource.download(aggregate=object()) except NotImplementedError as exc: print('rejected:', str(exc).split(':')[0])

Takeaway¶

The catalog tells you the source, the output shape, and (for RGI) the region layout before you download a byte. Continue with GLIMS & WGMS for the time-series outlines and the mass-balance record.