Using custom shapefiles

By default, DART uses GADM shapefiles as the geometry input to the pipeline. While this is a good default, you may want to supply your own shapefiles, in case the country has updated administrative boundaries since the last GADM update, or you only want to run DART on a sub-region of a country, such as a single province.

The custom shapefile configuration is located at ~/.local/share/dart-pipeline/regions.toml for Linux and macOS or at C:\Users\{username}\AppData\Local\dart-pipeline\regions.toml on Windows. The TOML file has keys, each of which is the name of a region (usually uppercase by convention, no hyphens allowed), with key value pairs denoting the configuration.

The following keys should be present for each region defined in the file:

bbox

Bounding box of the region, specified as [minx, miny, maxx, maxy] where x is longitude and y is latitude

url

URL where region data was downloaded from

iso3

If specified refers to the ISO3 code this region refers to, or is a sub-region of. For example if the region key is CA representing California, iso3 should be set to USA. Optional, leave blank if region covers multiple countries.

tz

Time zone of the region, specified as +HH:MM or -HH:MM as shift from UTC

admin_files

Mapping from administrative levels (1, 2, 3) to shapefiles (.shp extension)

pk

Mapping from administrative levels to a primary key column that uniquely identifies an administrative unit within the shapefile. If all administrative levels share the same primary key column, can be specified as a string.

All values, unless numbers or booleans must be quoted in TOML. An example TOML file is shown below:

[VNM]
bbox = [102,7,118,24]
url = "https://www.geoboundaries.org/api/current/gbOpen/VNM/"
iso3 = "VNM"
tz = "+07:00"
admin_files = {2 = "data/VNM/geoboundaries/geoBoundaries-VNM-ADM2.shp"}
pk = {2 = "shapeID"}