wopr: An R package to query the
WorldPop Open Population Repository


WorldPop, University of Southampton

17 November 2020

Introduction

wopr is an R package that provides API access to the WorldPop Open Population Repository. This gives users the ability to:

  1. Download WorldPop population data sets directly from the R console,
  2. Submit spatial queries (points or polygons) to the WorldPop server to retrieve population estimates within user-defined geographic areas,
  3. Get estimates of population sizes for specific demographic groups (i.e. age and sex), and
  4. Get probabilistic estimates of uncertainty for all population estimates.
  5. 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.

Installation

First, start a new R session. Then, install the wopr R package from WorldPop on GitHub:

devtools::install_github('wpgp/wopr')
library(wopr)

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 upgrade='never'. 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.

Usage

Demo code is provided in demo/wopr_demo.R that follows the examples in this README.

You can list vignettes that are available using: vignette(package='wopr')

The woprVision web application is an interactive web map that allows you to query population estimates from the WorldPop Open Population Repository. See the vignette for woprVision with: vignette('woprVision', package='wopr')

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: vignette('woprAPI', package='wopr')

woprVision

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:

wopr::woprVision()

We suggest installing Michael Harper's fix to the leaflet.extras draw toolbar:

devtools::install_github("dr-harper/leaflet.extras")

This is not required, but it fixes a bug that prevents the draw toolbar from being removed from the map when it is inactive.

Data Download

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)

Note: 'NGA' refers to Nigeria. WOPR uses ISO country codes to abbreviate country names.

By default, downloadData() will not download files larger than 100 MB unless you change the maxsize argument (see ?downloadData). Using 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 maxsize argument (default = 100 MB).

Spatial Query

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 objects using:

sf_feature <- sf::st_read('shapefile.shp')

To submit a spatial query, you must first identify which WOPR databases support spatial queries:

getCatalogue(spatial_query=T)

This will return a data.frame:

country version
NGA v1.2
NGA v1.1
COD v1.0

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:

print(N)
hist(N)

This can be summarized using:

summaryPop(N, confidence=0.95, tails=2, abovethresh=1e5, belowthresh=5e4)

The confidence argument controls the width of the confidence intervals. The tails argument controls whether the confidence intervals are calculated as one-tailed or two-tailed probabilities. If confidence=0.95 and 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 confidence=0.95 and 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.

The abovethresh argument defines the threshold used to calculate the probability that the population will exceed this threshold. For example, if abovethresh=1e5, then the abovethresh result from summaryPop() 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 use the 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)

If the 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 woprize() function:

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()

Contributing

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.

Suggested Citation

Leasure DR, Bondarenko M, Darin E, Tatem AJ. 2020. wopr: An R package to query the WorldPop Open Population Repository, version 0.4.0. WorldPop, University of Southampton. doi:10.5258/SOTON/WP00688

License

GNU General Public License v3.0 (GNU GPLv3)]