PRIOGRID is an R package for collecting and standardizing open
spatial data into a common grid format. This tutorial covers the basics:
setting up the package, downloading data, and reading it into R as
tabular data — no terra or sf required.
Initial Setup
PRIOGRID stores raw downloaded data and processed outputs in a single folder on your machine. This path persists across R sessions.
library(priogrid)
# Set the data folder (run once; persists across sessions)
pg_set_rawfolder("/path/to/your/data/folder")Once set, you can retrieve it at any time:
Configuration
PRIOGRID has a session-scoped configuration object that controls the spatial and temporal parameters of the grid. The defaults match the official PRIOGRID release:
pg_current_config()
#> PRIO-GRID config:
#> nrow: 360
#> ncol: 720
#> crs: epsg:4326
#> extent: -180 180 -90 90
#> temporal_resolution: 1 year
#> start_date: 1850-12-31
#> end_date: 2026-08-11
#> verbose: TRUE
#> automatic_download: TRUE| Parameter | Default | Meaning |
|---|---|---|
nrow / ncol
|
360 / 720 | Grid dimensions (0.5° cells) |
crs |
"epsg:4326" |
WGS84 geographic coordinates |
extent |
global | -180 to 180, -90 to 90 |
temporal_resolution |
"1 year" |
Annual time steps |
start_date |
1850-12-31 |
First measurement date |
end_date |
today | Last measurement date |
You can inspect individual fields:
cfg <- pg_current_config()
cfg$nrow
#> [1] 360
cfg$temporal_resolution
#> [1] "1 year"The configuration is only in effect for the current R session. See the Custom Configurations vignette for how to change it.
Downloading the Official Release
Download the current official PRIOGRID release with a single call. This downloads a zip archive and extracts it to your raw data folder:
To see what releases are available:
download_priogrid(list_releases = TRUE)The download only happens once — subsequent calls are skipped unless
you set overwrite = TRUE.
Reading PRIOGRID Data
Once downloaded, load the full dataset as a data.table.
This requires no spatial libraries.
Static Variables
Static variables do not change over time (e.g., terrain elevation, country border distances):
pg_static <- read_pg_static()
head(pg_static)Each row is a PRIOGRID cell identified by pgid. Columns
are variable names.
Time-Varying Variables
Time-varying variables have a measurement_date column in
addition to pgid:
pg_tv <- read_pg_timevarying()
head(pg_tv)These tables can be joined together by pgid, or merged
with your own data.
Subsetting at read time
All six filter arguments default to NULL (no filter —
full dataset). When supplied, filters are pushed down to Arrow before
any data is collected, so only the requested rows and columns touch
memory. Temporal and spatial constraints compose as AND;
pgids and extent compose as union.
| Argument | Type | Effect |
|---|---|---|
years |
integer vector | Keep only the listed calendar years (prunes hive partitions) |
start_date / end_date
|
Date | Inclusive bounds on measurement_date
|
pgids |
integer vector | Keep specific PRIO-GRID cell IDs |
extent |
c(xmin, xmax, ymin, ymax) in lon/lat |
Bounding box resolved to cell IDs (requires terra) |
variables |
character vector | Return only the named variable columns |
# A single year
pg_2020 <- read_pg_timevarying(years = 2020)
# Inclusive date range
pg_decade <- read_pg_timevarying(
start_date = as.Date("2010-01-01"),
end_date = as.Date("2019-12-31")
)
# Spatial bounding box (Sub-Saharan Africa)
pg_africa <- read_pg_timevarying(
extent = c(xmin = -20, xmax = 55, ymin = -35, ymax = 40)
)
# One variable column only
pg_tmp <- read_pg_timevarying(variables = "cru_tmp")
# Combined: two years, one region, two variables
pg_sub <- read_pg_timevarying(
years = c(2010, 2015),
extent = c(xmin = -20, xmax = 55, ymin = -35, ymax = 40),
variables = c("cru_tmp", "ucdp_ged")
)Example: merging static and time-varying data
library(data.table)
# Load a specific year and region with push-down, then merge with static data
pg_tv <- read_pg_timevarying(
years = 2020,
extent = c(xmin = -20, xmax = 55, ymin = -35, ymax = 40)
)
pg_merged <- merge(pg_static, pg_tv, by = "pgid")Browsing Available Variables
The pgvariables data frame lists all variables in
PRIOGRID:
pgvariables
#> name static
#> 1 cru_tmp FALSE
#> 2 cru_pre FALSE
#> 3 cru_pet FALSE
#> 4 cshapes_cover_share FALSE
#> 5 cshapes_gwcode FALSE
#> 6 geoepr_reg_excluded FALSE
#> 7 bdist1 FALSE
#> 8 bdist2 FALSE
#> 9 bdist3 FALSE
#> 10 ghsl_population_grid FALSE
#> 11 hilda_cropland FALSE
#> 12 hilda_forest FALSE
#> 13 hilda_grassland FALSE
#> 14 hilda_ocean FALSE
#> 15 hilda_pasture FALSE
#> 16 hilda_sparse FALSE
#> 17 hilda_urban FALSE
#> 18 hilda_water FALSE
#> 19 linight_mean FALSE
#> 20 naturalearth_cover TRUE
#> 21 naturalearth_cover_share TRUE
#> 22 ruggedterrain_elevation_mean TRUE
#> 23 traveltime_mean TRUE
#> 24 traveltime_min TRUE
#> 25 geopko_troops_count FALSE
#> 26 geopko_operations_count FALSE
#> 27 ne_disputed_area_share TRUE
#> 28 speibase6_mean FALSE
#> 29 ghs_wup_degurba_urban FALSE
#> 30 ucdp_ged FALSE
#> 31 shdi FALSE
#> 32 msch FALSE
#> 33 esch FALSE
#> 34 lifexp FALSE
#> 35 gnic FALSE
#> 36 side_excluded FALSE
#> 37 side_included FALSE
#> 38 side_irrelevant FALSE
#> source_ids
#> 1 ac037134-3567-49d9-a3ba-64f37c1ee698
#> 2 00575260-ad1c-4e87-a575-3922bc151f50
#> 3 95399c70-7db4-47f0-95e5-2e279b6b2054
#> 4 ec3eea2e-6bec-40d5-a09c-e9c6ff2f8b6b
#> 5 ec3eea2e-6bec-40d5-a09c-e9c6ff2f8b6b
#> 6 287bfdf7-2f4f-402a-88df-5fe1f8b7046b, 3900b527-a728-4c26-b0ab-f4441d3ee2e8
#> 7 ec3eea2e-6bec-40d5-a09c-e9c6ff2f8b6b
#> 8 ec3eea2e-6bec-40d5-a09c-e9c6ff2f8b6b
#> 9 ec3eea2e-6bec-40d5-a09c-e9c6ff2f8b6b
#> 10 ae6a7612-4bef-452f-acd6-d2212cf9a7c5
#> 11 82bc4c6f-9904-484f-aa9a-77771d076690
#> 12 82bc4c6f-9904-484f-aa9a-77771d076690
#> 13 82bc4c6f-9904-484f-aa9a-77771d076690
#> 14 82bc4c6f-9904-484f-aa9a-77771d076690
#> 15 82bc4c6f-9904-484f-aa9a-77771d076690
#> 16 82bc4c6f-9904-484f-aa9a-77771d076690
#> 17 82bc4c6f-9904-484f-aa9a-77771d076690
#> 18 82bc4c6f-9904-484f-aa9a-77771d076690
#> 19 d99fbea7-2a01-4221-b900-29a58d33f591
#> 20 92da9800-4520-4e87-a855-b28255452189
#> 21 92da9800-4520-4e87-a855-b28255452189
#> 22 8c8192eb-cc29-4598-8f8a-ec190ba35c2d
#> 23 9aa052f6-4d04-4ed1-9eed-e47e08828d38
#> 24 9aa052f6-4d04-4ed1-9eed-e47e08828d38
#> 25 7dcbfbfb-9667-4684-af34-85f69fa8d0a0
#> 26 7dcbfbfb-9667-4684-af34-85f69fa8d0a0
#> 27 920663ad-d7e7-4528-b36d-4b7266def2b1
#> 28 14839384-623a-4cf7-9241-6166a8ac465b, 95399c70-7db4-47f0-95e5-2e279b6b2054, 00575260-ad1c-4e87-a575-3922bc151f50
#> 29 7f1f60a3-6664-4427-b086-b5359ebf45b7
#> 30 49f79d96-4e4d-4812-9dd1-862bacfca577
#> 31 8aaf6b27-6372-43da-87a9-d4235095bb2c, a8e35e36-9f7e-4194-9cc4-ce8ca59f7b51, 8aaf6b27-6372-43da-87a9-d4235095bb2c
#> 32 8aaf6b27-6372-43da-87a9-d4235095bb2c, a8e35e36-9f7e-4194-9cc4-ce8ca59f7b51, 8aaf6b27-6372-43da-87a9-d4235095bb2c
#> 33 8aaf6b27-6372-43da-87a9-d4235095bb2c, a8e35e36-9f7e-4194-9cc4-ce8ca59f7b51, 8aaf6b27-6372-43da-87a9-d4235095bb2c
#> 34 8aaf6b27-6372-43da-87a9-d4235095bb2c, a8e35e36-9f7e-4194-9cc4-ce8ca59f7b51, 8aaf6b27-6372-43da-87a9-d4235095bb2c
#> 35 8aaf6b27-6372-43da-87a9-d4235095bb2c, a8e35e36-9f7e-4194-9cc4-ce8ca59f7b51, 8aaf6b27-6372-43da-87a9-d4235095bb2c
#> 36 e42b30e3-75da-4dd4-a375-0d6557087804
#> 37 e42b30e3-75da-4dd4-a375-0d6557087804
#> 38 e42b30e3-75da-4dd4-a375-0d6557087804
#> label unit
#> 1 Mean temperature °C
#> 2 Precipitation mm
#> 3 Potential evapotranspiration mm/day
#> 4 State territory coverage (share) <NA>
#> 5 Country (Gleditsch-Ward code) <NA>
#> 6 Excluded ethnic groups (regional, share) <NA>
#> 7 Distance to nearest land border m
#> 8 Distance to nearest international border m
#> 9 Distance to own country border m
#> 10 Population count persons
#> 11 Cropland cover (share) <NA>
#> 12 Forest cover (share) <NA>
#> 13 Grassland cover (share) <NA>
#> 14 Ocean cover (share) <NA>
#> 15 Pasture cover (share) <NA>
#> 16 Sparse vegetation cover (share) <NA>
#> 17 Urban cover (share) <NA>
#> 18 Water cover (share) <NA>
#> 19 Nighttime light (harmonized, mean) <NA>
#> 20 Land cover mask (share) <NA>
#> 21 Land cover (share) <NA>
#> 22 Mean elevation m
#> 23 Travel time to major city (mean) minutes
#> 24 Travel time to major city (minimum) minutes
#> 25 UN peacekeeping troops (count) personnel
#> 26 UN peacekeeping operations (count) <NA>
#> 27 Disputed area coverage (share) <NA>
#> 28 SPEI drought index (6-month, mean) <NA>
#> 29 Urban area (DEGURBA, share) <NA>
#> 30 Battle-related deaths (UCDP GED) deaths
#> 31 Subnational Human Development Index <NA>
#> 32 Mean years of schooling years
#> 33 Expected years of schooling years
#> 34 Life expectancy at birth years
#> 35 GNI per capita 1000 USD (2011 PPP)
#> 36 Excluded ethnic population (share) <NA>
#> 37 Included ethnic population (share) <NA>
#> 38 Politically irrelevant ethnic population (share) <NA>
#> transform plot_type
#> 1 identity continuous
#> 2 identity positive_real
#> 3 identity positive_real
#> 4 identity share
#> 5 identity discrete
#> 6 identity share
#> 7 identity positive_real
#> 8 identity positive_real
#> 9 identity positive_real
#> 10 log10 positive_real
#> 11 identity share
#> 12 identity share
#> 13 identity share
#> 14 identity share
#> 15 identity share
#> 16 identity share
#> 17 identity share
#> 18 identity share
#> 19 identity positive_real
#> 20 identity share
#> 21 identity share
#> 22 identity continuous
#> 23 identity positive_real
#> 24 identity positive_real
#> 25 log1p count
#> 26 log1p count
#> 27 identity share
#> 28 identity continuous
#> 29 identity share
#> 30 log1p count
#> 31 identity positive_real
#> 32 identity positive_real
#> 33 identity positive_real
#> 34 identity positive_real
#> 35 identity positive_real
#> 36 identity share
#> 37 identity share
#> 38 identity shareThe static column indicates whether a variable varies
over time. Use this to filter:
# Static variables
pgvariables[pgvariables$static == TRUE, "name"]
#> [1] "naturalearth_cover" "naturalearth_cover_share"
#> [3] "ruggedterrain_elevation_mean" "traveltime_mean"
#> [5] "traveltime_min" "ne_disputed_area_share"
# Time-varying variables
pgvariables[pgvariables$static == FALSE, "name"]
#> [1] "cru_tmp" "cru_pre"
#> [3] "cru_pet" "cshapes_cover_share"
#> [5] "cshapes_gwcode" "geoepr_reg_excluded"
#> [7] "bdist1" "bdist2"
#> [9] "bdist3" "ghsl_population_grid"
#> [11] "hilda_cropland" "hilda_forest"
#> [13] "hilda_grassland" "hilda_ocean"
#> [15] "hilda_pasture" "hilda_sparse"
#> [17] "hilda_urban" "hilda_water"
#> [19] "linight_mean" "geopko_troops_count"
#> [21] "geopko_operations_count" "speibase6_mean"
#> [23] "ghs_wup_degurba_urban" "ucdp_ged"
#> [25] "shdi" "msch"
#> [27] "esch" "lifexp"
#> [29] "gnic" "side_excluded"
#> [31] "side_included" "side_irrelevant"Rawfolder Structure
After downloading, your data folder has this structure:
{rawfolder}/
├── priogrid/
│ ├── priogrid_3_0_1_05deg_yearly.zip # Downloaded archive
│ └── releases/
│ └── 3.0.1/
│ └── 05deg_yearly/
│ ├── cog/
│ │ └── {varname}.tif # Individual variables as Cloud-Optimized GeoTIFFs
│ ├── timevarying/
│ │ └── year=YYYY/
│ │ └── part-0.parquet # Hive-partitioned time-varying data
│ ├── pg_static.parquet # Static data (wide table)
│ ├── pg_static.csv.gz # Static data (CSV bundle)
│ ├── pg_timevarying.csv.gz # Time-varying data (CSV bundle)
│ ├── pg_config.json # Dataset manifest (grid, layout, variables)
│ └── _checksums.csv # Per-file MD5s
├── {source_name}/{version}/{id}/ # Raw source files
└── tmp/ # Temporary processing filesread_pg_static() reads pg_static.parquet;
read_pg_timevarying() reads the hive-partitioned
timevarying/ dataset, pushing any filters down to Arrow
first. The cog/*.tif files hold individual variables as
Cloud-Optimized GeoTIFFs and are read by load_pgvariable().
The *.csv.gz bundles provide the same tables for non-R
users, and pg_config.json records the grid and layout.
Next Steps
-
Accessing PRIOGRID as
Rasters — using
terrato work with individual variables as spatial rasters - Citations and Bibliography — how to cite data providers
- Custom Configurations — changing resolution, extent, and time period
-
Understanding PRIOGRID Metadata —
exploring
pgsources,pgvariables, andpgsearch()