--- title: "Basic malariaAtlas usage." author: "Dan Pfeffer, Tim Lucas" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Basic malariaAtlas usage} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r globalKnitrOptions, include = FALSE} library(malariaAtlas) knitr::opts_chunk$set(fig.width=12, fig.height=8) ``` ```{r echo=FALSE} # Helper function for ensuring functions don't ever throw errors for CRAN tryOrLog <- function(...) { tryCatch({ eval(...) }, error = function(e) { print(e) return(NULL) }) } ``` # Overview This package allows you to download parasite rate data (*Plasmodium falciparum* and *P. vivax*) and modelled raster outputs from the [Malaria Atlas Project](https://malariaatlas.org/). ## Available Data The data can be interactively explored at [https://data.malariaatlas.org/maps](https://data.malariaatlas.org/maps). This is also useful for finding information on the raster data available and checking the extents of different rasters (some are Africa only for example). ### List Versions Functions The list version functions are used to list the available versions of different datasets, and all return a data.frame with a single column for version. These versions can be passed to functions such as `listShp`, `listSpecies`, `listPRPointCountries`, `listVecOccPointCountries`, `getPR`, `getVecOcc` and `getShp`. Use: - `listPRPointVerions()` to see the available versions for PR point data, which can then be used in `listPRPointCountries` and `getPR`. - `listVecOccPointVersions()` to see the available versions for vector occurrence data, which can then be used in `listSpecies`, `listVecOccPointCountries` and `getVecOcc`. - `listShpVersions()` to see the available versions for admin unit shape data, which can then be used in `listShp` and `getShp`. ```{r eval = FALSE} listPRPointVersions() ``` ```{r eval = FALSE} listVecOccPointVersions() ``` ```{r eval = FALSE} listShpVersions() ``` ### List Countries and Species Functions To list the countries where there is available data for PR points or vector occurrence points, use: - `listPRPointCountries()` for PR points - `listVecOccPointCountries()` for vector occurrence points To list the species available for vector point data use `listSpecies()` All three of these functions can optionally take a version parameter (which can be found with the list versions functions). If you choose not to provide a version, the most recent version of the relevant dataset will be selected by default. ```{r eval = FALSE} listPRPointCountries(version = "202206") ``` ```{r eval = FALSE} listVecOccPointCountries(version = "201201") ``` ```{r eval = FALSE} listSpecies(version = "201201") ``` ### List Administrative Units To list administrative units for which shapefiles are stored on the MAP geoserver, use `listShp()`. Similar to the list countries and species functions, this function can optionally take a version. ```{r eval = FALSE} listShp(version = "202206") ``` ### List Raster Function `listRaster()` gets minimal information on all available rasters. It returns a data.frame with several columns for each raster such as dataset_id, title, abstract, min_raster_year and max_raster_year. The dataset_id can then be used in `getRaster` and `extractRaster`. ```{r eval = FALSE} listRaster() ``` ### Is Available Functions `isAvailable_pr` confirms whether or not PR survey point data is available to download for a specified country, ISO3 code or continent. Check whether PR data is available for Madagascar: ```{r eval = FALSE} isAvailable_pr(country = "Madagascar") ``` Check whether PR data is available for the United States of America by ISO code: ```{r eval = FALSE} isAvailable_pr(ISO = "USA") ``` Check whether PR data is available for Asia: ```{r eval = FALSE} isAvailable_pr(continent = "Asia") ``` `isAvailable_vec` confirms whether or not vector survey point data is available to download for a specified country, ISO3 code or continent. Check whether vector data is available for Myanmar: ```{r eval = FALSE} isAvailable_vec(country = "Myanmar") ``` Check whether vector data is available for multiple countries: ```{r eval = FALSE} isAvailable_vec(country = c("Nigeria", "Ethiopia")) ``` You can also pass these functions a dataset version. If you don't they will default to using the most recent version. ```{r eval = FALSE} isAvailable_pr(country = "Madagascar", version = "202206") ``` ## Downloading & Visualising Data: ### get\* functions & autoplot methods ### Parasite Rate Survey Points `getPR()` downloads all publicly available PR data points for a specified location (country, ISO, continent or extent) and plasmodium species (Pf, Pv or BOTH) and returns this as a dataframe with the following format: ```{r eval = FALSE} MDG_pr_data <- getPR(country = "Madagascar", species = "both") ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo=FALSE} # Hiding error handling for CRAN MDG_pr_data <- tryOrLog(getPR(country = "Madagascar", species = "both")) ``` ```{r echo = FALSE} tibble::glimpse(MDG_pr_data) ``` ```{r eval = FALSE} Africa_pvpr_data <- getPR(continent = "Africa", species = "Pv") ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo = FALSE} # Hiding error handling for CRAN Africa_pvpr_data <- tryOrLog(getPR(continent = "Africa", species = "Pv")) ``` ```{r eval = FALSE} Extent_pfpr_data <- getPR(extent = rbind(c(-2.460181, 13.581921), c(-3.867188, 34.277344)), species = "Pf") ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo = FALSE} # Hiding error handling for CRAN Extent_pfpr_data <- tryOrLog(getPR(extent = rbind(c(-2.460181, 13.581921), c(-3.867188, 34.277344)), species = "Pf")) ``` You can also pass this function a dataset version. If you don't it will default to using the most recent version. ```{r eval = FALSE} MDG_pr_data_202206 <- getPR(country = "Madagascar", species = "both", version = "202206") ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo = FALSE} # Hiding error handling for CRAN MDG_pr_data_202206 <- tryOrLog(getPR(country = "Madagascar", species = "both", version = "202206")) ``` `autoplot.pr.points` configures autoplot method to enable quick mapping of the locations of downloaded PR points. ```{r message = FALSE, warning = FALSE, results = "hide"} autoplot(MDG_pr_data) ``` A version without facetting is also available. ```{r message = FALSE, warning = FALSE, results = "hide"} autoplot(MDG_pr_data, facet = FALSE) ``` ### Vector Survey Points `getVecOcc()` downloads all publicly available Vector survey points for a specified location (country, ISO, continent or extent) and species (options for which can be found with `listSpecies`) and returns this as a dataframe with the following format: ```{r eval=FALSE} MMR_vec_data <- getVecOcc(country = "Myanmar") ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo=FALSE} # Hiding error handling for CRAN MMR_vec_data <- tryOrLog(getVecOcc(country = "Myanmar")) ``` ```{r echo = FALSE} tibble::glimpse(MMR_vec_data) ``` You can also pass this function a dataset version. If you don't it will default to using the most recent version. ```{r eval=FALSE} MMR_vec_data_201201 <- getVecOcc(country = "Myanmar", version = "201201") ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo=FALSE} # Hiding error handling for CRAN MMR_vec_data_201201 <- tryOrLog(getVecOcc(country = "Myanmar", version = "201201")) ``` `autoplot.vector.points` configures autoplot method to enable quick mapping of the locations of downloaded vector points. ```{r message = FALSE, warning = FALSE, results = "hide"} autoplot(MMR_vec_data) ``` N.B. Facet-wrapped option is also available for species stratification. ```{r message = FALSE, warning = FALSE, results = "hide"} autoplot(MMR_vec_data, facet = TRUE) ``` ### Shapefiles `getShp()` downloads a shapefile for a specified country (or countries) and returns this as a simple feature object. ```{r eval = FALSE} MDG_shp <- getShp(ISO = "MDG", admin_level = c("admin0", "admin1")) ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo = FALSE} # Hiding error handling for CRAN MDG_shp <- tryOrLog(getShp(ISO = "MDG", admin_level = c("admin0", "admin1"))) ``` ```{r echo = FALSE} tibble::glimpse(MDG_shp) ``` `autoplot.sf` configures autoplot method to enable quick mapping of downloaded shapefiles. ```{r message = FALSE} autoplot(MDG_shp) ``` N.B. Facet-wrapped option is also available for species stratification. ```{r message = FALSE, warning = FALSE, results = "hide"} autoplot(MDG_shp, facet = TRUE, map_title = "Example of facetted shapefiles.") ``` ### Modelled Rasters `getRaster()`downloads publicly available MAP rasters for a specific dataset_id & year, clipped to a given bounding box or shapefile ```{r eval=FALSE} MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0") MDG_PfPR2_10 <- getRaster(dataset_id = "Explorer__2020_Global_PfPR", shp = MDG_shp, year = 2013) ``` ```{r message = FALSE, warning = FALSE, results = "hide", echo=FALSE} # Hiding error handling for CRAN MDG_shp <- tryOrLog(getShp(ISO = "MDG", admin_level = "admin0")) MDG_PfPR2_10 <- tryOrLog(getRaster(dataset_id = "Explorer__2020_Global_PfPR", shp = MDG_shp, year = 2013)) ``` `autoplot.SpatRaster` & `autoplot.SpatRasterCollection` configures autoplot method to enable quick mapping of downloaded rasters. ```{r message = FALSE} p <- autoplot(MDG_PfPR2_10, shp_df = MDG_shp) ``` ### Combined visualisation By using the above tools along with ggplot, simple comparison figures can be easily produced. ```{r eval=FALSE} MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0") MDG_PfPR2_10 <- getRaster(dataset_id = "Explorer__2020_Global_PfPR", shp = MDG_shp, year = 2013) p <- autoplot(MDG_PfPR2_10, shp_df = MDG_shp, printed = FALSE) pr <- getPR(country = c("Madagascar"), species = "Pf") p[[1]] + geom_point(data = pr[pr$year_start==2013,], aes(longitude, latitude, fill = positive / examined, size = examined), shape = 21)+ scale_size_continuous(name = "Survey Size")+ scale_fill_distiller(name = "PfPR", palette = "RdYlBu") ``` Similarly for vector survey data ```{r eval=FALSE} MMR_shp <- getShp(ISO = "MMR", admin_level = "admin0") MMR_An_dirus <- getRaster(dataset_id = "Explorer__2010_Anopheles_dirus_complex", shp = MMR_shp) p <- autoplot(MMR_An_dirus, shp_df = MMR_shp, printed = FALSE) vec <- getVecOcc(country = c("Myanmar"), species = "Anopheles dirus") p[[1]] + geom_point(data = vec, aes(longitude, latitude, colour = species))+ scale_colour_manual(values = "black", name = "Vector survey locations")+ scale_fill_distiller(name = "Predicted distribution of An. dirus complex", palette = "PuBuGn", direction = 1) ```