Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

place

Nearest country and municipality, from Natural Earth countries and, optionally, Eurostat GISCO LAU municipalities.

seastamp place <INPUT> --countries <NE> [--municipalities <GISCO>] [OPTIONS]

Appends three columns, or four when --municipalities is given:

ColumnMeaning
countryCountry name
country_codeISO alpha-3 code (the Natural Earth -99 placeholder becomes null)
municipalityMunicipality name (empty unless --municipalities is given)
municipality_distDistance to that municipality, 0 when the point is inside it. Only with --municipalities

How it works

Both the country and the municipality lookups resolve a point by containment first (an even-odd point-in-polygon test over R-tree candidates) and fall back to the nearest boundary otherwise, so an offshore point still gets the closest land unit. Attribute fields are auto-detected from candidate name lists, so minor schema drift between dataset versions needs no flags.

--municipalities is optional: without it the municipality column is left empty, no municipality_dist column is added, and a note says so.

Bounding the municipality match

The municipality fallback is unbounded, and GISCO LAU covers Europe only, so a site outside that coverage still resolves to whatever municipality is nearest, however far away. A point a few hundred km offshore picks up a coastal municipality that it is in no sense part of.

municipality_dist makes that visible: 0 means the point really is inside the polygon, and a large value means the fallback reached a long way. --max-municipality-dist turns it into a filter, discarding matches beyond the limit. The name and the distance are cleared together, so a row never carries one without the other. Both are read in --unit, kilometres by default.

country needs none of this, since Natural Earth is global.

Both lookups fall back to the nearest boundary in a plane, and municipality_dist is measured there too, so a projection that does not suit your points can return the wrong place entirely rather than a slightly wrong number. On 540 globally spread points, a single projection assigned a different nearest country to 91 of them than --partition did, and spot checks went to --partition every time.

Options

Beyond the shared options and the region options:

OptionDefaultMeaning
--countries <PATH>requiredNatural Earth countries shapefile
--municipalities <PATH>noneGISCO LAU municipalities shapefile
--max-municipality-dist <N>noneDiscard a municipality match further than this, in --unit
--unit km|mkmUnit for municipality_dist and the cutoff

Example

seastamp place cores.parquet \
  --countries ./data/naturalearth/ne_10m_admin_0_countries.shp \
  --municipalities ./data/gisco/lau.shp \
  --max-municipality-dist 50

See Reference datasets for how to obtain Natural Earth and GISCO.