# Basic malariaAtlas usage.

#### Dan Pfeffer, Tim Lucas

#### 2025-06-11

# Overview

This package allows you to download parasite rate data (Plasmodium falciparum and P. vivax) and modelled raster outputs from the Malaria Atlas Project.

## Available Data

The data can be interactively explored at 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`.

    listPRPointVersions()

    listVecOccPointVersions()

    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.

    listPRPointCountries(version = "202206")

    listVecOccPointCountries(version = "201201")

    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.

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

    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:

    isAvailable_pr(country = "Madagascar")

Check whether PR data is available for the United States of America by ISO code:

    isAvailable_pr(ISO = "USA")

Check whether PR data is available for Asia:

    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:

    isAvailable_vec(country = "Myanmar")

Check whether vector data is available for multiple countries:

    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.

    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:

    MDG_pr_data <- getPR(country = "Madagascar", species = "both")

    ## Rows: 2,298
    ## Columns: 28
    ## $ dhs_id                    <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ site_id                   <int> 8689, 6221, 18093, 6021, 15070, 15795, 7374,…
    ## $ site_name                 <chr> "Vodivohitra", "Andranomasina", "Ankazobe", …
    ## $ latitude                  <dbl> -16.21700, -18.71700, -18.31600, -19.83400, …
    ## $ longitude                 <dbl> 49.68300, 47.46600, 47.11800, 47.85000, 47.2…
    ## $ rural_urban               <chr> "RURAL", "UNKNOWN", "RURAL", "UNKNOWN", "UNK…
    ## $ country                   <chr> "Madagascar", "Madagascar", "Madagascar", "M…
    ## $ country_id                <chr> "MDG", "MDG", "MDG", "MDG", "MDG", "MDG", "M…
    ## $ continent_id              <chr> "Africa", "Africa", "Africa", "Africa", "Afr…
    ## $ month_start               <int> 11, 1, 11, 3, 1, 7, 4, 1, 1, 2, 7, 11, 4, 7,…
    ## $ year_start                <int> 1989, 1987, 1989, 1987, 1987, 1995, 1986, 19…
    ## $ month_end                 <int> 11, 1, 12, 3, 1, 8, 6, 1, 1, 2, 8, 12, 4, 8,…
    ## $ year_end                  <int> 1989, 1987, 1989, 1987, 1987, 1995, 1986, 19…
    ## $ lower_age                 <dbl> 5, 0, 5, 0, 0, 2, 7, 0, 0, 0, 2, 5, 6, 2, 2,…
    ## $ upper_age                 <int> 15, 99, 15, 99, 99, 9, 22, 99, 99, 99, 9, 15…
    ## $ examined                  <int> 165, 50, 258, 246, 50, 50, 119, 50, 50, 210,…
    ## $ positive                  <dbl> 144.0, 7.5, 139.0, 126.0, 2.5, 6.0, 37.0, 13…
    ## $ pr                        <dbl> 0.87272727, 0.15000000, 0.53875969, 0.512195…
    ## $ species                   <chr> "P. falciparum", "P. falciparum", "P. falcip…
    ## $ method                    <chr> "Microscopy", "Microscopy", "Microscopy", "M…
    ## $ rdt_type                  <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ pcr_type                  <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ malaria_metrics_available <lgl> TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TR…
    ## $ location_available        <lgl> TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TR…
    ## $ permissions_info          <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ citation1                 <chr> "Lepers, J.P. (1989). <i>Rapport sur la situ…
    ## $ citation2                 <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ citation3                 <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …

    Africa_pvpr_data <- getPR(continent = "Africa", species = "Pv")

    Extent_pfpr_data <- 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.

    MDG_pr_data_202206 <- getPR(country = "Madagascar", species = "both", version = "202206")

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

    autoplot(MDG_pr_data)

A version without facetting is also available.

    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:

    MMR_vec_data <- getVecOcc(country = "Myanmar")

    ## Rows: 2,866
    ## Columns: 25
    ## $ id             <int> 1945, 1946, 1951, 1952, 790, 781, 772, 791, 773, 783, 7…
    ## $ site_id        <int> 30243, 30243, 30243, 30243, 1000000072, 1000000071, 100…
    ## $ latitude       <dbl> 16.257, 16.257, 16.257, 16.257, 17.350, 17.380, 17.380,…
    ## $ longitude      <dbl> 97.725, 97.725, 97.725, 97.725, 96.041, 96.037, 96.037,…
    ## $ country        <chr> "Myanmar", "Myanmar", "Myanmar", "Myanmar", "Myanmar", …
    ## $ country_id     <chr> "MMR", "MMR", "MMR", "MMR", "MMR", "MMR", "MMR", "MMR",…
    ## $ continent_id   <chr> "Asia", "Asia", "Asia", "Asia", "Asia", "Asia", "Asia",…
    ## $ month_start    <int> 2, 3, 8, 9, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 10, …
    ## $ year_start     <int> 1998, 1998, 1998, 1998, 1998, 1998, 1998, 1998, 1998, 1…
    ## $ month_end      <int> 2, 3, 8, 9, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 10, …
    ## $ year_end       <int> 1998, 1998, 1998, 1998, 2000, 2000, 2000, 2000, 2000, 2…
    ## $ anopheline_id  <int> 17, 17, 17, 17, 50, 49, 17, 51, 11, 4, 15, 1, 35, 30, 5…
    ## $ species        <chr> "Anopheles dirus species complex", "Anopheles dirus spe…
    ## $ species_plain  <chr> "Anopheles dirus", "Anopheles dirus", "Anopheles dirus"…
    ## $ id_method1     <chr> "unknown", "unknown", "unknown", "unknown", "morphology…
    ## $ id_method2     <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
    ## $ sample_method1 <chr> "man biting", "man biting", "man biting", "man biting",…
    ## $ sample_method2 <chr> "animal baited net trap", "animal baited net trap", "an…
    ## $ sample_method3 <chr> NA, NA, NA, NA, "animal baited net trap", "animal baite…
    ## $ sample_method4 <chr> NA, NA, NA, NA, "house resting inside", "house resting …
    ## $ assi           <chr> "", "", "", "", "", "", "", "", "", "", "", "", "", "",…
    ## $ citation       <chr> "Oo, T.T., Storch, V. and Becker, N. (2003).  <b><i>Ano…
    ## $ time_start     <date> 1998-02-01, 1998-03-01, 1998-08-01, 1998-09-01, 1998-0…
    ## $ time_end       <date> 1998-02-01, 1998-03-01, 1998-08-01, 1998-09-01, 2000-0…
    ## $ geometry       <POINT [°]> POINT (97.725 16.257), POINT (97.725 16.257), POI…

You can also pass this function a dataset version. If you don’t it will default to using the most recent version.

    MMR_vec_data_201201 <- getVecOcc(country = "Myanmar", version = "201201")

`autoplot.vector.points` configures autoplot method to enable quick mapping of the locations of downloaded vector points.

    autoplot(MMR_vec_data)

N.B. Facet-wrapped option is also available for species stratification.

    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.

    MDG_shp <- getShp(ISO = "MDG", admin_level = c("admin0", "admin1"))

    ## Rows: 23
    ## Columns: 17
    ## $ iso           <chr> "MDG", "MDG", "MDG", "MDG", "MDG", "MDG", "MDG", "MDG", …
    ## $ admn_level    <int> 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
    ## $ name_0        <chr> "Madagascar", "Madagascar", "Madagascar", "Madagascar", …
    ## $ id_0          <int> 10000910, 10000910, 10000910, 10000910, 10000910, 100009…
    ## $ type_0        <chr> "Country", "Country", "Country", "Country", "Country", "…
    ## $ name_1        <chr> NA, "Menabe", "Alaotra Mangoro", "Amoron I Mania", "Anal…
    ## $ id_1          <int> NA, 10023004, 10022998, 10022989, 10022983, 10022999, 10…
    ## $ type_1        <chr> NA, "Region", "Region", "Region", "Region", "Region", "R…
    ## $ name_2        <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ id_2          <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ type_2        <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ name_3        <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ id_3          <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ type_3        <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
    ## $ source        <chr> "Madagascar NMCP 2016", "Madagascar NMCP 2016", "Madagas…
    ## $ country_level <chr> "MDG_0", "MDG_1", "MDG_1", "MDG_1", "MDG_1", "MDG_1", "M…
    ## $ geometry      <MULTIPOLYGON [°]> MULTIPOLYGON (((44.2278 -25..., MULTIPOLYGO…

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

    autoplot(MDG_shp)

N.B. Facet-wrapped option is also available for species stratification.

    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

    MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
    MDG_PfPR2_10 <- 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.

    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.

    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

    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)