---
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}
knitr::opts_chunk$set(fig.width=12, fig.height=8)
```

# 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://malariaatlas.org/explorer/#/explorer](https://malariaatlas.org/explorer/#/explorer).
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* Functions


`listData()` retrieves a list of available data to download. 

Use: 

* listData(datatype = "pr points") OR listPoints(sourcedata = "pr points") to see for which countries PR survey point data can be downloaded.

* use listData(datatype = "vector points") or listPoints(sourcedata = "vector points") to see for which countries Vector Occurrence data can be downloaded.

* use listData(datatype = "rasters") OR listRaster() to see rasters available to download. 

* use listData(datatype = "shape") OR listShp() to see shapefiles available to download. 

```{r listd, results = "hide", message = FALSE}
library(malariaAtlas)
listData(datatype = "pr points")
```
```{r results = "hide", message = FALSE}
listData(datatype = "vector points")
```
```{r results = "hide", message = FALSE}
listData(datatype = "raster")
```
``` {r results = "hide", message = FALSE}
listData(datatype = "shape")
```

### is_available

`isAvailable_pr` confirms whether or not PR survey point data is available to download for a specified country. 

Check whether PR data is available for Madagascar:
```{r highlight = TRUE}
isAvailable_pr(country = "Madagascar")
```

Check whether PR data is available for the United States of America
```{r, error = TRUE, purl = FALSE, highlight = TRUE}
isAvailable_pr(ISO = "USA")
```

`isAvailable_vec` confirms whether or not Vector occurrence point data is available to download for a specified country. 

Check whether Vector occurrence data is available for Myanmar:
```{r highlight = TRUE}
isAvailable_vec(country = "Myanmar")
```

Check whether Vector occcurrence data is available for the Brazil
```{r, error = TRUE, purl = FALSE, highlight = TRUE}
isAvailable_vec(ISO = "BRA")
```

## Downloading & Visualising Data: 
### get* functions & autoplot methods

### Parasite Rate Survey Points
`getPR()` downloads all publicly available PR data points for a specified country and plasmodium species (Pf, Pv or BOTH) and returns this as a dataframe with the following format: 


```{r message = FALSE}
MDG_pr_data <- getPR(country = "Madagascar", species = "both")
```
```{r echo = FALSE, error = TRUE, purl = FALSE}
tibble::glimpse(MDG_pr_data)
```

### Vector Occurrnece points
`getVecOcc()` downloads all publicly available Vector Occurrence data points for a specified country and mosquito species (if required) and returns this as a dataframe with the following format: 


```{r message = FALSE}
MMR_vec_data <- getVecOcc(country = "Myanmar")
```
```{r echo = FALSE, error = TRUE, purl = FALSE}
tibble::glimpse(MMR_vec_data)
```

`autoplot.pr.points` is an autoplot method to enable quick mapping of the locations of downloaded PR points. 


```{r message = FALSE, warning = FALSE, results = "hide", error = TRUE, purl = FALSE}
autoplot(MDG_pr_data)
```

`autoplot.vector.points` is an autoplot method to enable quick mapping of the locations of downloaded vector occurrence points. 


```{r message = FALSE, warning = FALSE, results = "hide", error = TRUE, purl = FALSE}
autoplot(MMR_vec_data)
```

Furthermore, being ggplot2 plots, these plots can easily be added to or modified.

```{r message = FALSE, warning = FALSE, results = "hide", error = TRUE, purl = FALSE}
p <- autoplot(MDG_pr_data, printed = FALSE)
p + 
  scale_fill_gradientn(colours = rev(palettetown::pokepal('charmeleon', spread = 3))) +
  theme_minimal()
```


### Shapefiles
`getShp()` downloads a shapefile for a specified country (or countries) and returns this as either a spatialPolygon or data.frame object.

```{r message = FALSE}
MDG_shp <- getShp(ISO = "MDG", admin_level = c("admin1", "admin2"))
```
```{r echo = FALSE, error = TRUE, purl = FALSE, error = TRUE, purl = FALSE}
tibble::glimpse(MDG_shp)
```

`autoplot.MAPshp` configures autoplot method to enable quick mapping of downloaded shapefiles.

```{r message = FALSE, error = TRUE, purl = FALSE}
MDG_shp <- as.MAPshp(MDG_shp)
autoplot(MDG_shp)
```

### Modelled Rasters 

`getRaster()`downloads publicly available MAP rasters for a specific surface & year, clipped to a given bounding box or shapefile

```{r message = FALSE, error = TRUE, purl = FALSE}
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", shp = MDG_shp, year = 2013)
```
N.B. to use downloaded rasters and shapefiles directly with autoplot, use as.MAPraster() and as.MAPshp() to convert these to data.frames. Alternatively autoplot_MAPraster() will work directly with RasterLayer, RasterStack or RasterBrick objects downloaded with getRaster().

`autoplot.MAPraster` and `autoplot_MAPraster` are autoplot methods to enable quick mapping of downloaded rasters.

```{r message = FALSE, error = TRUE, purl = FALSE, purl = FALSE}
MDG_PfPR2_10_df <- as.MAPraster(MDG_PfPR2_10)
MDG_shp_df <- as.MAPshp(MDG_shp)
p <- autoplot(MDG_PfPR2_10_df, shp_df = MDG_shp_df)
```


### Combined visualisation 

By using the above tools along with ggplot, simple comparison figures can be easily produced. 

```{r message = FALSE, warning = FALSE, error = TRUE, purl = FALSE}
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
MDG_shp_df <- as.MAPshp(MDG_shp)
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", shp = MDG_shp, year = 2013)
MDG_PfPR2_10_df <- as.MAPraster(MDG_PfPR2_10)

p <- autoplot(MDG_PfPR2_10_df, shp_df = MDG_shp_df, 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")+
 ggtitle("Raw PfPR Survey points\n + Modelled PfPR 2-10 in Madagascar in 2013")
```

```{r message = FALSE, warning = FALSE, error = TRUE, purl = FALSE}
MMR_shp <- getShp(ISO = "MMR", admin_level = "admin0")
MMR_shp_df <- as.MAPshp(MMR_shp)
MMR_an_dirus <- getRaster(surface = "Anopheles dirus species complex", shp = MMR_shp)
MMR_an_dirus_df <- as.MAPraster(MMR_an_dirus)

p <- autoplot(MMR_an_dirus_df, shp_df = MMR_shp_df, printed = FALSE)

vec <- getVecOcc(country = c("Myanmar"), species = "Anopheles dirus")
p[[1]] +
geom_point(data = vec, aes(longitude, latitude), shape = 21,  show.legend = TRUE)+
  scale_fill_distiller(name = "Predicted distribution of Anopheles dirus species complex", palette = "RdYlBu")+
  ggtitle("Raw Vector Survey points\n + The predicted distribution of Anohpeles dirus species complex")
```

