wopr

An R package and Shiny application to provide API access to the WorldPop Open Population Repository.
https://github.com/wpgp/wopr

Category: Sustainable Development
Sub Category: Population and Poverty

Keywords

bayesian-methods population-model r-package shiny-apps

Last synced: about 22 hours ago
JSON representation

Repository metadata

An R package and Shiny application to provide API access to the WorldPop Open Population Repository (WOPR)

• Host: GitHub
• URL: https://github.com/wpgp/wopr
• Owner: wpgp
• License: gpl-3.0
• Created: 2019-11-07T22:34:44.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2025-04-04T10:01:30.000Z (23 days ago)
• Last Synced: 2025-04-20T06:09:25.742Z (7 days ago)
• Topics: bayesian-methods, population-model, r-package, shiny-apps
• Language: HTML
• Homepage: https://apps.worldpop.org/woprVision
• Size: 17.8 MB
• Stars: 38
• Watchers: 5
• Forks: 8
• Open Issues: 4
• Releases: 8
• Metadata Files:
  • Readme: README.html
  • License: COPYING

README.html

          




















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





WorldPop, University of Southampton
10 June 2021
Introduction
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.
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. 2021. wopr: An R package
to query the WorldPop Open Population Repository, version 1.3.3.
WorldPop, University of Southampton. doi: 10.5258/SOTON/WP00716. https://github.com/wpgp/wopr
License
GNU General Public License v3.0 (GNU GPLv3)]




        

---

Owner metadata

• Name: WorldPop
• Login: wpgp
• Email: [email protected]
• Kind: organization
• Description: Open Spatial Demographic Data and Research
• Website: https://www.worldpop.org
• Location: University of Southampton
• Twitter: WorldPopProject
• Company:
• Icon url: https://avatars.githubusercontent.com/u/33325143?v=4
• Repositories: 12
• Last ynced at: 2023-03-07T11:15:48.536Z
• Profile URL: https://github.com/wpgp

---

GitHub Events

Total

• Watch event: 4
• Issue comment event: 2
• Pull request review event: 1
• Pull request event: 2
• Fork event: 1

Last Year

• Watch event: 4
• Issue comment event: 2
• Pull request review event: 1
• Pull request event: 2
• Fork event: 1

---

Committers metadata

Last synced: 5 days ago

Name	Email	Commits
Doug Leasure	d****e@g****m	337
edarin	e****n@s****k	66
Gianluca Boo	g****a@i****t	9
Alina Cherkas	5****s	5
Maksym Bondarenko	m****o@g****m	1

Committer domains:

• idiosyncraticmapper.net: 1
• soton.ac.uk: 1

---

Issue and Pull Request metadata

Last synced: 2 days ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/wpgp/wopr

---

---

---

Dependencies

Score: 5.3471075307174685