DiscreteGlobalGrids.jl

DiscreteGlobalGrids.jl lets you analyse data on global grids: move rasters onto cells, select regions, compute with neighbours, and read or write Zarr stores. The same operations work across IGEO7, H3, HEALPix, A5, S2 and ISEA4R.

A discrete global grid divides the Earth's surface into cells. Each cell has an identifier, a boundary and neighbours, so you can work with it much as you would with a raster pixel.

import DiscreteGlobalGrids as DGG
using GeoMakie
using WGLMakie
using DiscreteGlobalGridsVisualization

WGLMakie.activate!()

figure = Figure(size = (640, 640), figure_padding = 2)
axis = GlobeAxis(
    figure[1, 1];
    source = "+proj=longlat +R=1",
    dest = GeoMakie.Geodesy.Ellipsoid(; a = "1", b = "1"),
    camera_longlat = (10, 25), camera_altitude = 1.9,
)
meshimage!(axis, -180 .. 180, -90 .. 90, fill("#f0faea", 1, 1);
    zlevel = -0.05, npoints = 300)
dggpoly!(axis, DGG.levelgrid(DGG.IGeo7System(), 3);
    color = "#dcf5d7", strokecolor = "#2c7a1e", strokewidth = 0.8)
lines!(axis, GeoMakie.coastlines(); color = ("#212529", 0.7), linewidth = 1.0,
    zlevel = 0.002)
figure

The globe shows IGEO7 at level 3. To work with a grid, choose a system and a resolution level:

grid = DGG.levelgrid(DGG.IGeo7System(), 4)

HierarchicalLevelGrid(IGeo7System, level=4, ncells=24012)

DGG.cellat(grid, 8.5, 47.4)     # the cell under Zürich, as a typed id

Z7Cell("000622")

DGG.cellsize(grid)              # a typical cell's width, in metres

145754.77044985184

import Extents
DGG.query(grid, DGG.Intersects(Extents.Extent(X = (5, 12), Y = (45, 50))))

24-element Vector{Z7Cell}:
 Z7Cell("000362")
 Z7Cell("000364")
 Z7Cell("000366")
 Z7Cell("000602")
 Z7Cell("000603")
 Z7Cell("000620")
 Z7Cell("000621")
 Z7Cell("000622")
 Z7Cell("000623")
 Z7Cell("000624")
 ⋮
 Z7Cell("006110")
 Z7Cell("006114")
 Z7Cell("006115")
 Z7Cell("006116")
 Z7Cell("006150")
 Z7Cell("006151")
 Z7Cell("006153")
 Z7Cell("006154")
 Z7Cell("006155")

These calls also work with the other systems. Choosing a grid compares cell shapes, sizes and coordinate conventions.

Grids, cells and data

Term	Meaning
System	A family of grids at different resolutions, such as HEALPix
Grid	A collection of cells at one level, covering the globe or a region
Cell id	A typed identifier for a cell, including its level
Local index	A cell's position in a particular collection or array
Cells dimension	The link between an array's values and its grid cells

Regridding a monthly raster produces an array with Cells and time dimensions. Spatial selectors act on Cells; ordinary Julia indexing and reductions work on the result. See the grid interface for the full reference.

Installation

Install the package and its plotting companion from the repository:

using Pkg
Pkg.add(url = "https://github.com/JuliaGeo/DiscreteGlobalGrids.jl")
Pkg.add(url = "https://github.com/JuliaGeo/DiscreteGlobalGrids.jl",
        subdir = "lib/DiscreteGlobalGridsVisualization")

Julia 1.11 or newer is required. The tutorials import the packages needed for each example. Plotting uses DiscreteGlobalGridsVisualization with a Makie backend; store I/O requires using Zarr to load dggread and dggwrite. Use Pkg.develop(url = ...) for a checkout you intend to edit.

Choose a tutorial

Start with Choosing a grid and Regridding if you are new to DGGS data. Each tutorial includes its own setup, so you can then follow the capability you need:

Task	Tutorial
Choose cell geometry, resolution and latitude convention	Choosing a grid
Bring a monthly raster onto a DGGS and export it back	Regridding
Change grid system or resolution; compare interpolation methods	Moving between DGGS
Select cells by region and calculate regional means	Zonal statistics
Represent a region compactly and regrid onto it	Multi-order coverage
Smooth a field, detect edges and traverse the cell graph	Stencil operations
Use Geomorphometry and write a custom terrain kernel	Hydrology
Save data, reopen it lazily and read a region	DGGS stores
Run a neighbourhood kernel over stored chunks	Out of core
Work with HEALPix vectors, sky masks and cone searches	The sky in HEALPix

The Earth-data examples use simple spherical setups to demonstrate the operations. For work that requires alignment with geodetic data, follow the coordinate guidance when choosing your grid.

Reference and extension

The API pages cover grids, spatial selection, regridding methods, region boundaries, neighbours and stencils, neighbour fields, store I/O, chunked computation, work partitioning and subzone storage.

To add a grid, follow Writing a grid system. The architecture guide explains how grids, cell collections and algorithms fit together.

Optional integrations

The names exist in the core package, but optional packages activate these methods:

Capability	Load	Scope and guide
Zarr store IO	using Zarr	Read and write cell cubes; S3 URLs also require using AWSS3
Makie conversion	using Makie and a backend	Convert grids and cell collections to point or polygon plots
METIS partitioning	using Metis	Assign chunks with MetisPartition
KaHyPar partitioning	using KaHyPar_jll	Assign chunks with KaHyParPartition
Scotch partitioning	using Scotch	Assign chunks with ScotchPartition

The separate DiscreteGlobalGridsVisualization package adds dggpoly, dggsurface, and dggresample. Core Makie conversion does not provide those plot types. Tutorials using them import the companion package explicitly.

For grid, identity, and data-axis concepts, read Grids and cell indices.