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