WorldPop, University of Southampton
10 June 2021
wopr is an R package that provides API access to the WorldPop Open Population Repository. This gives users the ability to:
- Download WorldPop population data sets directly from the R console,
- Submit spatial queries (points or polygons) to the WorldPop server to retrieve population estimates within user-defined geographic areas,
- Get estimates of population sizes for specific demographic groups (i.e. age and sex), and
- Get probabilistic estimates of uncertainty for all population estimates.
- Run the woprVision web application locally from the R console.
Code for the wopr package is openly available on GitHub: https://github.com/wpgp/wopr.
First, start a new R session. Then, install the wopr R package from WorldPop on GitHub:
You may be prompted to update some of your existing R packages. This is
not required unless the wopr installation fails. You can avoid
checking for package updates by adding the argument
If needed, you can update individual packages that may be responsible
for any wopr installation errors using
install.packages('package_name'). Or, you can use
devtools::install_github('wpgp/wopr', upgrade='ask') to update all of
the packages that wopr depends on. In R Studio, you can also update
all of your R packages by clicking “Tools > Check for Package Updates”.
Note: When updating multiple packages, it may be necessary to restart your R session before each installation to ensure that packages being updated are not currently loaded in your R environment.
Demo code is provided in
demo/wopr_demo.R that follows the examples in
You can list vignettes that are available using:
web application is an interactive web map that allows you to query
population estimates from the
Population Repository. See the vignette for woprVision with:
If you are intersted in developing your own front end applications that
query the WOPR API, please read the vignette that describes the API
backend for developers:
woprVision is an R shiny application that allows you to browse an interactive map to get population estimates for specific locations and demographic groups. woprVision is available on the web at https://apps.worldpop.org/woprVision. You can also run woprVision locally from your R console using:
We suggest installing Michael Harper’s fix to the leaflet.extras draw toolbar:
This is not required, but it fixes a bug that prevents the draw toolbar from being removed from the map when it is inactive.
One way to access data from WOPR is to simply download the files directly to your computer from the R console. This can be done with three easy steps:
# Retrieve the WOPR data catalogue catalogue <- getCatalogue() # Select files from the catalogue by subsetting the data frame selection <- subset(catalogue, country == 'NGA' & category == 'Population' & version == 'v1.2') # Download selected files downloadData(selection)
'NGA' refers to Nigeria. WOPR uses
country codes to abbreviate country names.
downloadData() will not download files larger than 100 MB
unless you change the
maxsize argument (see
the default settings, a folder named
./wopr will be created in your R
working directory for downloaded files. A spreadsheet listing all WOPR
files currently saved to your hard drive can be found in
./wopr/wopr_catalogue.csv. To list the files that have been downloaded
to your working directory from within the R console, use
list.files('wopr', recursive=T). In multiple calls to downloadData(),
files that you have previously downloaded will be overwritten if your
local files do not match the server files (based on an md5sums check).
This allows you to keep up-to-date local copies of every file.
You can download the entire WOPR data catalogue using:
downloadData(getCatalogue(), maxsize=Inf). Note: Some files in the
WOPR data catalogue are very large (e.g. 140 GB), so please ensure that
you have enough disk space. If disk space is limited, you can restrict
the maximum file size that you woud like to download using the
argument (default = 100 MB).
Population estimates can also be obtained from WOPR using spatial queries (geographic points or polygons) for user-defined geographic area(s) and demographic group(s).
Spatial queries must be submitted using objects of class
sf. You can
explore this functionality using example data from Nigeria that are
included with the
wopr package. Plot the example data using:
data(wopr_points) plot(wopr_points, pch=16) data(wopr_polys) plot(wopr_polys)
Note: ESRI shapefiles (and other file types) can be read into R as
sf_feature <- sf::st_read('shapefile.shp')
To submit a spatial query, you must first identify which WOPR databases support spatial queries:
This will return a
These results indicate that there are currently two WOPR databases for Nigeria (NGA) that support spatial queries and one database for Democratic Republic of Congo (COD).
Query total population at a single point
To get the total population for a single point location from the NGA v1.2 population estimates use:
N <- getPop(feature=wopr_points[1,], country='NGA', version='v1.2')
Notice that the population estimate is returned as a vector of samples from the Bayesian posterior distribution:
This can be summarized using:
summaryPop(N, confidence=0.95, tails=2, abovethresh=1e5, belowthresh=5e4)
confidence argument controls the width of the confidence
tails argument controls whether the confidence
intervals are calculated as one-tailed or two-tailed probabilities. If
tails=2, then there is a 95% probability that
the true population falls within the confidence intervals, given the
model structure and the data used to fit the model. If
tails=1, then there is a 95% chance that the true population
exceeds the lower confidence interval and a 95% chance that the true
population is less than the upper confidence interval.
abovethresh argument defines the threshold used to calculate the
probability that the population will exceed this threshold. For example,
abovethresh=1e5, then the
abovethresh result from
is the probability that the population exceeds 100,000 people. The
belowthresh argument is similar except it will return the probability
that the population is less than this threshold.
Query total population within a single polygon
To query WOPR using a single polygon works exactly the same as a point-based query:
N <- getPop(feature=wopr_polygons[1,], country='NGA', version='v1.2') summaryPop(N, confidence=0.95, tails=2, abovethresh=1e2, belowthresh=50)
Query population for specific demographic groups
To query population estimates for specific demographic groups, you can
agesex_select argument (see
?getPop). This argument accepts
a character vector of age-sex groups.
'f0' represents females less
than one year old;
'f1' represents females from age one to four;
'f5' represents females from five to nine;
'f10' represents females
from 10 to 14; and so on.
'm0' represents males less than one, etc.
Query the population of children under the age of five within a single polygon:
N <- getPop(feature=wopr_polygons[1,], country='NGA', version='v1.2', agesex_select=c('f0','f1','m0','m1')) summaryPop(N, confidence=0.95, tails=2, abovethresh=10, belowthresh=1)
agesex argument is not included, the
getPop() function will
return estimates of the total population (as above).
Query multiple point or polygon features
We can query multiple point or polygon features using the
N_table <- woprize(features=wopr_polys, country='NGA', version='1.2', agesex_select=c('m0','m1','f0','f1'), confidence=0.95, tails=2, abovethresh=2e4, belowthresh=1e4 )
You can save these results in a number of ways:
# save results as shapefile sf::st_write(N_table, 'example_shapefile.shp') # save results as csv write.csv(sf::st_drop_geometry(N_table), file='example_spreadsheet.csv', row.names=F) # save image of mapped results jpeg('example_map.jpg') tmap::tm_shape(N_table) + tmap::tm_fill('mean', palette='Reds', legend.reverse=T) dev.off()
The WorldPop Open Population Repository (WOPR) was developed by the WorldPop Research Group within the Department of Geography and Environmental Science at the University of Southampton. Funding was provided by the Bill and Melinda Gates Foundation and the United Kingdom Foreign, Commonwealth & Development Office (OPP1182408, OPP1182425, INV-002697). Professor Andy Tatem provides oversight of the WorldPop Research Group. The wopr R package was developed by Doug Leasure. Maksym Bondarenko and Niko Ves developed the API backend server. Edith Darin added multi-lingual functionality to the Shiny app and the French translation. Natalia Tejedor Garavito proofread the Spanish translation. Gianluca Boo created the WOPR logo. Population data have been contributed to WOPR by many different researchers within the WorldPop Research Group.
Leasure DR, Bondarenko M, Darin E, Tatem AJ. 2021. wopr: An R package to query the WorldPop Open Population Repository, version 1.0.7. WorldPop, University of Southampton. doi: 10.5258/SOTON/WP00716. https://github.com/wpgp/wopr
GNU General Public License v3.0 (GNU GPLv3)]