Title:	An R Interface to Open-Access Malaria Data, Hosted by the 'Malaria Atlas Project'
Version:	1.6.4
Description:	A suite of tools to allow you to download all publicly available parasite rate survey points, mosquito occurrence points and raster surfaces from the 'Malaria Atlas Project' https://malariaatlas.org/ servers as well as utility functions for plotting the downloaded data.
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	xml2, gridExtra, httr, dplyr, tidyr, methods, stats, utils, rlang, sf, lifecycle, terra, tidyterra, ows4R, future.apply, lubridate, jsonlite, stringr, ggnewscale
Depends:	ggplot2
RoxygenNote:	7.2.3
Suggests:	testthat, knitr, rmarkdown, palettetown, magrittr, tibble, rdhs (≥ 0.8.0)
URL:	https://github.com/malaria-atlas-project/malariaAtlas
BugReports:	https://github.com/malaria-atlas-project/malariaAtlas/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-06-11 00:15:12 UTC; mvandenberg
Author:	Mauricio van den Berg [aut, cre], Daniel Pfeffer [aut], Tim Lucas [aut], Daniel May [aut], Suzanne Keddie [aut], Jen Rozier [aut], Oliver Watson [aut], Harry Gibson [aut], Nick Golding [ctb], David Smith [ctb]
Maintainer:	Mauricio van den Berg <mauricio.vandenberg@thekids.org.au>
Repository:	CRAN
Date/Publication:	2025-06-11 11:00:06 UTC

Convert Raster objects into MAPraster objects

Description

as.MAPraster converts a RasterLayer or RasterStack object into a 'MAPraster' object (data.frame) for easy plotting with ggplot.

Usage

as.MAPraster(raster_object)

Arguments

Value

as.MAPraster returns a MAPraster object (data.frame) containing the below columns.

1. x - x coordinates of raster pixels

2. y - y coordinates of raster pixels

3. z - value of raster pixels

4. raster_name - name of raster for which values are stored in z

See Also

getRaster:

to download rasters directly from MAP.

as.MAPraster:

to convert RasterLayer/RasterStack objects into a 'MAPraster' object (data.frame) for easy plotting with ggplot.

autoplot.MAPraster:

to quickly visualise MAPraster objects created using as.MAPraster.

Examples

# Download PfPR2-10 Raster for Madagascar in 2015 and visualise this on a map.
## Not run: 
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", shp = MDG_shp, year = 2015)
MDG_PfPR2_10 <- as.MAPraster(MDG_PfPR2_10)
autoplot(MDG_PfPR2_10)
## End(Not run)

#Download global raster of G6PD deficiency from Howes et al 2012 and visualise this on a map.
## Not run: 
G6PDd_global <- getRaster(surface = "G6PD Deficiency Allele Frequency")
G6PDd_global <- as.MAPraster(G6PDd_global)
autoplot(G6PDd_global)
## End(Not run)

Convert SpatialPolygon objects into MAPshp objects

Description

as.MAPshp converts a SpatialPolygon or SpatialPolygonsDataframe object downloaded using getShp into a 'MAPshp object (data.frame) for easy plotting with ggplot.

Usage

as.MAPshp(object)

Arguments

Value

as.MAPshp returns a MAPshp object (data.frame) containing the below columns.

1. country_id ISO-3 code of given administrative unit (or the ISO code of parent unit for administrative-level 1 units).

2. gaul_code GAUL code of given administrative unit.

3. admn_level administrative level of the given administrative unit - either 0 (national) or 1 (first-level division)

4. parent_id GAUL code of parent administrative unit of a given polygon (for admin0 polygons, PARENT_ID = 0).

5. country_level composite country_id_admn_level field.

See Also

autoplot.MAPshp

to download rasters directly from MAP.

Examples

#Download shapefiles for Madagascar and visualise these on a map.

## Not run: 
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
MDG_shp <- as.MAPshp(MDG_shp)
autoplot(MDG_shp)

## End(Not run)

Convert data.frames to pr.points objects.

Description

Will create empty columns for any missing columns expected in a pr.points data.frame. This function is particularly useful for use with packages like dplyr that strip objects of their classes.

Usage

as.pr.points(x)

Arguments

Examples

#Download PfPR data for Nigeria and Cameroon and map the locations of these points using autoplot
## Not run: 
library(dplyr)
NGA_CMR_PR <- getPR(country = c("Nigeria", "Cameroon"), species = "Pf")

# Filter the data frame then readd pr.points class so that autoplot can be used.
NGA_CMR_PR %>%
  filter(year_start > 2010) %>%
  as.pr.points %>%
  autoplot


## End(Not run)

Convert data.frames to vector.points objects.

Description

Will create empty columns for any missing columns expected in a vector.points data.frame. This function is particularly useful for use with packages like dplyr that strip objects of their classes.

Usage

as.vectorpoints(x)

Arguments

Examples

## Not run: 
library(dplyr)
Brazil_vec <- getVecOcc(country = "Brazil")

# Filter data.frame then readd vector points class so autoplot can be used.
Brazil_vec %>%
  filter(sample_method1 == 'larval collection') %>%
  as.vectorpoints %>%
  autoplot

## End(Not run)

Quickly visualise Rasters downloaded from MAP

Description

autoplot.MAPraster creates a map of all rasters in a MAPraster object and displays these in a grid.

Usage

## S3 method for class 'MAPraster'
autoplot(
  object,
  ...,
  shp_df = NULL,
  legend_title = "",
  plot_titles = TRUE,
  fill_scale_transform = "identity",
  fill_colour_palette = "RdYlBu",
  printed = TRUE
)

Arguments

Value

autoplot.MAPraster returns a list of plots (gg objects) for each supplied raster.

See Also

getRaster:

to download rasters directly from MAP.

as.MAPraster:

to convert RasterLayer/RasterStack objects into a 'MAPraster' object (data.frame) for easy plotting with ggplot.

autoplot.MAPraster:

to quickly visualise MAPraster objects created using as.MAPraster.

Examples

## Not run: 
# Download PfPR2-10 Raster (Bhatt et al 2015) and raw survey points
#   for Madagascar in 2013 and visualise these together on a map.

# Download madagascar shapefile to use for raster download.
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")

# Download PfPR2-10 Raster for 2013 & plot this
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", 
                          shp = MDG_shp, year = 2013)
p <- autoplot(MDG_PfPR2_10, shp_df = MDG_shp)

# Download raw PfPR survey points & plot these over the top of the raster
pr <- getPR(country = c("Madagascar"), species = "Pf")

# Download global raster of G6PD deficiency (Howes et al 2012) and visualise this on a map.
G6PDd_global <- getRaster(surface = "G6PD Deficiency Allele Frequency")
autoplot(G6PDd_global)

## End(Not run)

Create a basic plot to visualise downloaded shapefiles

Description

autoplot.MAPshp creates a map of shapefiles downloaded using getShp.

Usage

## S3 method for class 'MAPshp'
autoplot(object, ..., map_title = NULL, facet = FALSE, printed = TRUE)

Arguments

Value

autoplot.MAPshp returns a map (gg object) of the supplied MAPShp dataframe.

Examples

## Not run: 
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
autoplot(as.MAPshp(MDG_shp))

## End(Not run)

Quickly visualise Rasters downloaded from MAP

Description

autoplot.SpatRaster creates a map of all rasters in a SpatRaster object and displays these in a grid.

Usage

## S3 method for class 'SpatRaster'
autoplot(
  object,
  ...,
  shp_df = NULL,
  legend_title = "",
  plot_titles = TRUE,
  fill_scale_transform = "identity",
  fill_colour_palette = "RdYlBu",
  printed = TRUE
)

Arguments

Value

autoplot.SpatRaster returns a list of plots (gg objects) for each supplied raster.

See Also

getRaster:

to download rasters directly from MAP.

Examples

## Not run: 
# Download PfPR2-10 Raster (Bhatt et al 2015) and raw survey points
#   for Madagascar in 2013 and visualise these together on a map.

# Download madagascar shapefile to use for raster download.
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")

# Download PfPR2-10 Raster for 2013 & plot this
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", 
                          shp = MDG_shp, year = 2013)
p <- autoplot(MDG_PfPR2_10, shp_df = MDG_shp)

# Download raw PfPR survey points & plot these over the top of the raster
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")


# Download global raster of G6PD deficiency (Howes et al 2012) and visualise this on a map.
G6PDd_global <- getRaster(surface = "G6PD Deficiency Allele Frequency")
autoplot(G6PDd_global)

## End(Not run)

Quickly visualise Rasters downloaded from MAP

Description

autoplot.SpatRasterCollection creates a map of all rasters in a autoplot.SpatRasterCollection object and displays these in a grid.

Usage

## S3 method for class 'SpatRasterCollection'
autoplot(
  object,
  ...,
  shp_df = NULL,
  legend_title = "",
  plot_titles = TRUE,
  fill_scale_transform = "identity",
  fill_colour_palette = "RdYlBu",
  printed = TRUE
)

Arguments

Value

autoplot.SpatRasterCollection returns a list of plots (gg objects) for each supplied raster.

gg object

Default autoplot method

Description

Default autoplot method

Usage

## Default S3 method:
autoplot(object, ...)

Arguments

Create a basic plot showing locations of downloaded PR points

Description

autoplot.pr.points creates a map of PR points downloaded from MAP.

Usage

## S3 method for class 'pr.points'
autoplot(
  object,
  ...,
  shp_df = NULL,
  admin_level = "admin0",
  map_title = "PR Survey Locations",
  fill_legend_title = "Raw PR",
  fill_scale_transform = "identity",
  facet = NULL,
  hide_confidential = FALSE,
  printed = TRUE
)

Arguments

Value

autoplot.pr.points returns a plots (gg object) for the supplied pr.points dataframe.

Examples

## Not run: 
PfPR_surveys_NGA <- getPR(country = c("Nigeria"), species = "Pf")
autoplot(PfPR_surveys_NGA)

# Download PfPR2-10 Raster (Bhatt et al. 2015) and raw survey points for Madagascar in
#   2013 and visualise these together on a map.

# Download madagascar shapefile to use for raster download.
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")

# Download PfPR2-10 Raster for 2013 & plot this
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", shp = MDG_shp, year = 2013)
p <- autoplot(MDG_PfPR2_10)

# Download raw PfPR survey points & plot these over the top of the raster
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")

## End(Not run)

Create a basic plot to visualise downloaded shapefiles

Description

autoplot.sf creates a map of shapefiles downloaded using getShp.

Usage

## S3 method for class 'sf'
autoplot(object, ..., map_title = NULL, facet = FALSE, printed = TRUE)

Arguments

Value

autoplot.sf returns a map of the supplied sf object

Examples

## Not run: 
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
autoplot(MDG_shp)

## End(Not run)

Create a basic plot showing locations of downloaded Vector points

Description

autoplot.vector.points creates a map of Vector points downloaded from MAP.

Usage

## S3 method for class 'vector.points'
autoplot(
  object,
  ...,
  shp_df = NULL,
  admin_level = "admin0",
  map_title = "Vector Survey Locations",
  fill_legend_title = "Raw Vetor Occurrences",
  fill_scale_transform = "identity",
  facet = NULL,
  printed = TRUE
)

Arguments

Value

autoplot.vector.points returns a plots (gg object) for the supplied vector.points dataframe.

Examples

## Not run: 
Vector_surveys_NGA_NG <- getVecOcc(country = c("Nigeria", "Niger"))
autoplot(Vector_surveys_NGA_NG)

# Download the predicted distribution of An. dirus species complex Raster and  
#  vector points for Myanmar and visualise these together on a map.

# Download Myanmar shapefile to use for raster download.
MMR_shp <- getShp(ISO = "MMR", admin_level = "admin0")

# Download An. dirus predicted distribution Raster & plot this
MMR_An_dirus <- getRaster(surface = "Anopheles dirus species complex", shp = MMR_shp)
p <- autoplot(MMR_An_dirus, shp_df = MMR_shp, printed = FALSE)

# Download raw occurrence points & plot these over the top of the raster   
species <- getVecOcc(country = "Myanmar", species = "Anopheles dirus")
# p[[1]] +
# geom_point(data = species,
#  aes(longitude,
#   latitude,
#   colour = species))+
#   scale_colour_manual(values = "black", name = "Vector suvery locations")+
# scale_fill_distiller(name = "Predicted distribution of An. dirus complex",
#  palette = "PuBuGn",
#   direction = 1)+
#   ggtitle("Vector Survey points\n + The predicted distribution of An. dirus complex")

## End(Not run)

Quickly visualise Rasters downloaded from MAP

Description

autoplot_MAPraster is a wrapper for autoplot.MAPraster that calls as.MAPraster to allow automatic map creation for RasterLayer/RasterStack objects downloaded from MAP.

Usage

autoplot_MAPraster(object, ...)

Arguments

Value

autoplot_MAPraster returns a list of plots (gg objects) for each supplied raster.

See Also

getRaster:

to download rasters directly from MAP.

as.MAPraster:

to convert RasterLayer/RasterStack objects into a 'MAPraster' object (data.frame) for easy plotting with ggplot.

autoplot.MAPraster:

to quickly visualise MAPraster objects created using as.MAPraster.

Examples

## Not run: 
#Download PfPR2-10 Raster (Bhatt et al 2015) and raw survey points for Madagascar in
#  2013 and visualise these together on a map.

# Download madagascar shapefile to use for raster download.
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")

# Download PfPR2-10 Raster for 2013 & plot this
MDG_PfPR2_10 <- getRaster(surface = "Plasmodium falciparum PR2-10", shp = MDG_shp, year = 2013)
# p <- autoplot_MAPraster(MDG_PfPR2_10)

# Download raw PfPR survey points & plot these over the top of the raster
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")
## End(Not run)


# Download global raster of G6PD deficiency (Howes et al 2012) and visualise this on a map.
## Not run: 
G6PDd_global <- getRaster(surface = "G6PD Deficiency Allele Frequency")
#autoplot_MAPraster(G6PDd_global)

## End(Not run)

Builds a filter to be used with getFeatures, that will filter based on the given bounding box.

Description

Builds a filter to be used with getFeatures, that will filter based on the given bounding box.

Usage

build_bbox_filter(bbox)

Arguments

Value

The character string of the filter.

Builds a CQL filter to be used with getFeatures, that will filter based on the given bounding box.

Description

Builds a CQL filter to be used with getFeatures, that will filter based on the given bounding box.

Usage

build_cql_bbox_filter(bbox)

Arguments

Value

The character string of the CQL filter.

Builds a cql filter to be used with getFeatures, that will filter based on the given list of values.

Description

Builds a cql filter to be used with getFeatures, that will filter based on the given list of values.

Usage

build_cql_filter(attribute, values)

Arguments

Value

The character string of the cql filter.

Builds a cql filter to be used with getFeatures, that will filter based on the time range provided by start_date and end_date.

Description

Builds a cql filter to be used with getFeatures, that will filter based on the time range provided by start_date and end_date.

Usage

build_cql_time_filter(start_date, end_date)

Arguments

Value

The character string of the cql filter.

Calls getFeatures on the given type with the given filters, where they are not NULL.

Description

Calls getFeatures on the given type with the given filters, where they are not NULL.

Usage

callGetFeaturesWithFilters(feature_type, cql_filter, ...)

Arguments

Value

The features returned from the getFeatures called on the feature_type with the filter where not NULL.

Function to clean up a bunch of mess in the mosquito names.

Description

Function to clean up a bunch of mess in the mosquito names.

Usage

clean_mosquito_names(available_rasters)

Arguments

Value

The same data.frame inputted, but now with some of the titles corrected.

Builds a cql filter from a list of cql sub filters

Description

Builds a cql filter from a list of cql sub filters

Usage

combine_cql_filters(filter_list)

Arguments

Value

If all values in filter_list are null, will return NULL, else will return character of combined filters. e.g. "time_start AFTER 2020-00-00T00:00:00Z AND country IN ('Nigeria')"

convert prevalences from one age range to another

Description

convert prevalences from one age range to another

Usage

convertPrevalence(
  prevalence,
  age_min_in,
  age_max_in,
  age_min_out = rep(2, length(prevalence)),
  age_max_out = rep(9, length(prevalence)),
  parameters = "Pf_Smith2007",
  sample_weights = NULL
)

Arguments

References

Smith, D. L. et al. Standardizing estimates of the Plasmodium falciparum parasite rate. Malaria Journal 6, 131 (2007).

Gething, Peter W., et al. "A long neglected world malaria map: Plasmodium vivax endemicity in 2010." PLoS neglected tropical diseases 6.9 (2012): e1814.

Code written by Nick Golding and Dave Smith

Examples

# Convert from prevalence 2 to 5 to prevalence 2 to 10
pr2_10 <- convertPrevalence(0.1, 2, 5, 2, 10)

# Convert many surveys all to 2 to 10.
pr <- runif(20, 0.1, 0.15)
min_in <- sample(1:5, 20, replace = TRUE)
max_in <- rep(8, 20)
min_out <- rep(2, 20)
max_out <- rep(10, 20)
pr_standardised <- convertPrevalence(pr, min_in, max_in,
                                     min_out, max_out)

plot(pr_standardised, pr)

Tries to convert character into a Date object. If this fails, the program will be stopped and an error message shown to the user

Description

Tries to convert character into a Date object. If this fails, the program will be stopped and an error message shown to the user

Usage

convert_to_date_with_trycatch(input, input_name)

Arguments

Value

Will return input as a Date is it can be converted into one. Else will stop the program and issue the user with an error message.

Download rasters from the MAP geoserver to a specifed location. If file already exists it will read it instead.

Description

Download rasters from the MAP geoserver to a specifed location. If file already exists it will read it instead.

Usage

download_rst(dataset_id, extent, year, file_name, file_path)

Arguments

Value

SpatRaster

Returns a data.frame of the extracted raster values with columns for layerName, year, value, long and lat.

Description

Returns a data.frame of the extracted raster values with columns for layerName, year, value, long and lat.

Usage

extractLayerValues(points_to_query, dataset_id, year)

Arguments

Extract pixel values from MAP rasters using point coordinates.

Description

extractRaster extracts pixel values from MAP rasters at user-specified point locations (without downloading the entire raster).

Usage

extractRaster(
  df,
  csv_path = NULL,
  surface = NULL,
  year = NULL,
  dataset_id = NULL
)

Arguments

Value

extractRaster returns the input dataframe (df), with the following columns appended, providing values for each raster, location and year.

1. layerName dataset id corresponding to extracted raster values for a given row, check listRaster for raster metadata.

2. year the year for which raster values were extracted (time-varying rasters only; static rasters do not have this column).

3. value the raster value for the pixel in which a given point location falls.

See Also

autoplot method for quick mapping of PR point locations (autoplot.pr.points).

Examples

#Download PfPR data for Nigeria and Cameroon and map the locations of these points using autoplot
## Not run: 
# Get some data and remove rows with NAs in location or examined or positive columns.
NGA_CMR_PR <- getPR(country = c("Nigeria", "Cameroon"), species = "Pf")
complete <- complete.cases(NGA_CMR_PR[, c(4, 5, 16, 17)])
NGA_CMR_PR <- NGA_CMR_PR[complete, ]

# Extract PfPR data at those locations.
data <- extractRaster(df = NGA_CMR_PR[, c('latitude', 'longitude')],
                      dataset_id = 'Malaria__202206_Global_Pf_Parasite_Rate',
                      year=2020)

# Some rasters are stored with NA encoded as -9999
data$value[data$value == -9999] <- NA

# We can quickly plot a summary
plot((NGA_CMR_PR$positive / NGA_CMR_PR$examined) ~ data$value)

## End(Not run)

Get the list of available countries for a given dataset_id in the Explorer workspace,

Description

Get the list of available countries for a given dataset_id in the Explorer workspace,

Usage

fetchCountriesGivenDatasetId(wfs_client, dataset_id)

Arguments

Value

A dataframe with columns for country, country_id and continent_id

Add DHS locations to malaria data

Description

We cannot directly share DHS data. We can share coordinates, but not the data values. This function attempts to fill the data gaps directly from the DHS server using the package rdhs. To use the function you will need to setup an account on the DHS website and request any datasets you wish to use (including requesting the GPS data). Confirmation can take a few days. Once this has been verified, you should be able to use this function.

Usage

fillDHSCoordinates(
  data,
  email = NULL,
  project = NULL,
  cache_path = NULL,
  config_path = NULL,
  global = TRUE,
  verbose_download = FALSE,
  verbose_setup = TRUE,
  data_frame = NULL,
  timeout = 30,
  password_prompt = FALSE,
  prompt = TRUE
)

Arguments

Details

This function requires the package rdhs which is currently only suggested by the package (not a dependency). So you will need to install it.

Note that the project has to be the exact name in your DHS project.

Author(s)

OJ Watson

Examples

## Not run: 
pf <- malariaAtlas::getPR("all",species = "pf")
pf <- fillDHSCoordinates(pf, 
email = "pretend_email@emaildomain.com",
project = "pretend project name")

## End(Not run)

Get the latest version of admin boundary data

Description

Get the latest version of admin boundary data

Usage

getLatestVersionForAdminData()

Value

The latest version of admin boundary data

Returns the best latitude column name in df data.frame, if one exists.

Description

Returns the best latitude column name in df data.frame, if one exists.

Usage

getLatitudeColumn(df)

Arguments

Value

Returns the best column name for latitude - 'latitude', 'lat', or 'y' respectively, or NULL if none of these column names exists in df

Returns the best longitude column name in df data.frame, if one exists.

Description

Returns the best longitude column name in df data.frame, if one exists.

Usage

getLongitudeColumn(df)

Arguments

Value

Returns the best column name for longitude - 'longitude', 'long', or 'x' respectively, or NULL if none of these column names exists in df

Gets the minimum and maximum year for the time dimension values of a WMS Layer.

Description

Gets the minimum and maximum year for the time dimension values of a WMS Layer.

Usage

getMinAndMaxYear(time_dimension_values)

Arguments

Value

A named list with a value for min and max.

Download PR points from the MAP database

Description

getPR downloads all publicly available PR points for a specified country (or countries) and returns this as a dataframe.

Usage

getPR(
  country = NULL,
  ISO = NULL,
  continent = NULL,
  species = NULL,
  extent = NULL,
  start_date = NULL,
  end_date = NULL,
  version = NULL
)

Arguments

Details

country and ISO refer to countries and a lower-level administrative regions such as Mayotte and French Guiana. While we cannot direectly distribute DHS coordinates, we can distribute the number of examined and positive. If the coordinates are needed they can be downloaded from www.measuredhs.com, via the rdhs package or using malariaAtlas:fillDHSCoordinates().

Value

getPR returns a dataframe containing the below columns, in which each row represents a distinct data point/ study site.

1. dhs_id The dhs survey id if appropriate.

2. site_id Unique site identifier

3. site_name Name of site.

See Also

autoplot method for quick mapping of PR point locations (autoplot.pr.points).

Examples

#Download PfPR data for Nigeria and Cameroon and map the locations of these points using autoplot
## Not run: 
NGA_CMR_PR <- getPR(country = c("Nigeria", "Cameroon"), species = "Pf")
autoplot(NGA_CMR_PR)

#Download PfPR data for Madagascar and map the locations of these points using autoplot
Madagascar_pr <- getPR(ISO = "MDG", species = "Pv")
autoplot(Madagascar_pr)

getPR(country = "ALL", species = "BOTH")

## End(Not run)

Gets the property string to provide to getFeatures input propertyName, given an admin level.

Description

Gets the property string to provide to getFeatures input propertyName, given an admin level.

Usage

getPropertiesForAdminLevel(admin_level)

Arguments

Value

The properrty string to pass to getFeartures as propertyName

Download Rasters produced by the Malaria Atlas Project

Description

getRaster downloads publicly available MAP rasters for a specific surface & year, clipped to a provided bounding box or shapefile.

Usage

getRaster(
  dataset_id = NULL,
  surface = NULL,
  shp = NULL,
  extent = NULL,
  file_path = NULL,
  year = NULL,
  vector_year = NULL
)

Arguments

Value

getRaster returns a SpatRaster for the specified extent. Or a SpatRasterCollection if the two rasters are incompatible in terms of projection/extent/resolution

See Also

autoplot_MAPraster

to quickly visualise rasters downloded using getRaster.

as.MAPraster

to convert RasterLayer/RasterStack objects into a 'MAPraster' object (data.frame) for easy plotting with ggplot.

autoplot.MAPraster

to quickly visualise MAPraster objects created using as.MAPraster.

Examples

# Download PfPR2-10 Raster for Madagascar and visualise this immediately.
## Not run: 
MDG_shp <- getShp(ISO = "MDG", admin_level = "admin0")
MDG_PfPR2_10 <- getRaster(dataset_id = "Malaria__202206_Global_Pf_Parasite_Rate", shp = MDG_shp)
autoplot(MDG_PfPR2_10)

## End(Not run)

Gets the rasters dataset id, given a surface (title). If more than one rasters have that surface/title, then the one with the most recent version is selected. If there are no matches, the program will stop with a relevant message.

Description

Gets the rasters dataset id, given a surface (title). If more than one rasters have that surface/title, then the one with the most recent version is selected. If there are no matches, the program will stop with a relevant message.

Usage

getRasterDatasetIdFromSurface(rasterList, surface)

Arguments

Value

character that is the dataset id of the raster that matches the given surface.

Download MAPadmin2013 Administrative Boundary Shapefiles from the MAP geoserver

Description

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

Usage

getShp(
  country = NULL,
  ISO = NULL,
  extent = NULL,
  admin_level = c("admin0"),
  format = NULL,
  long = NULL,
  lat = NULL,
  version = NULL
)

Arguments

Value

getShp returns a sf object for requested administrative unit polygons. The following attribute fields are included:

1. iso ISO-3 code of given administrative unit (or the ISO code of parent unit for administrative-level 1 units).

2. admn_level administrative level of the given administrative unit - either 0 (national), 1 (first-level division), 2 (second-level division), 3 (third-level division).

3. name_0 name of admin0 parent of a given administrative unit (or just shapefile name for admin0 units)

4. id_0 id code of admin0 parent of the current shapefile (or just shapefile id for admin0 units)

5. type_0 if applicable, type of administrative unit or admin0 parent

6. name_1 name of admin1 parent of a given administrative unit (or just shapefile name for admin1 units); NA for admin0 units

7. id_1 id code of admin1 parent of the current shapefile (or just shapefile id for admin1 units); NA for admin0 units

8. type_1 if applicable, type of administrative unit or admin1 parent

9. name_2 name of admin2 parent of a given administrative unit (or just shapefile name for admin2 units); NA for admin0, admin1 units

10. id_2 id code of admin2 parent of the current shapefile (or just shapefile id for admin2 units); NA for admin0, admin1 units

11. type_2 if applicable, type of administrative unit or admin2 parent

12. name_3 name of admin3 parent of a given administrative unit (or just shapefile name for admin3 units); NA for admin0, admin1, admin2 units

13. id_3 id code of admin3 parent of the current shapefile (or just shapefile id for admin3 units); NA for admin0, admin1, admin2 units

14. type_3 if applicable, type of administrative unit

15. source source of administrative boundaries

16. geometry geometry of administrative boundaries

17. country_level composite iso_admn_level field.

See Also

autoplot method for quick mapping of PR point locations (autoplot.pr.points).

Examples

#Download PfPR data & associated shapefiles for Nigeria and Cameroon
## Not run: 
NGA_CMR_PR <- getPR(country = c("Nigeria", "Cameroon"), species = "Pf")
NGA_CMR_shp <- getShp(country = c("Nigeria", "Cameroon"))

#Download PfPR data & associated shapefiles for Chad
Chad_PR <- getPR(ISO = "TCD", species = "both")
Chad_shp <- getShp(ISO = "TCD")

#' #Download PfPR data & associated shapefiles defined by extent for Madagascar
MDG_PR <- getPR(country = "Madagascar", species = "Pv")

## End(Not run)

Return sp style bbox

Description

Return sp style bbox

Usage

getSpBbox(sfBboxOrShp)

Arguments

Value

bbox in sp style. A 2x2 matrix - the first column has the minimum, the second the maximum values; rows 1 & 2 represent the x & y dimensions respectively (matrix(c("xmin", "ymin","xmax", "ymax"), nrow = 2, ncol = 2, dimnames = list(c("x", "y"), c("min", "max"))))

Download Vector Occurrence points from the MAP database getVecOcc downloads all publicly available vector occurrence points for a specified country (or countries) and returns this as a dataframe. country and ISO refer to countries and a lower-level administrative regions such as French Guiana.

Description

Download Vector Occurrence points from the MAP database getVecOcc downloads all publicly available vector occurrence points for a specified country (or countries) and returns this as a dataframe. country and ISO refer to countries and a lower-level administrative regions such as French Guiana.

Usage

getVecOcc(
  country = NULL,
  ISO = NULL,
  continent = NULL,
  species = "all",
  extent = NULL,
  start_date = NULL,
  end_date = NULL,
  version = NULL
)

Arguments

Value

getVecOcc returns a dataframe containing the below columns, in which each row represents a distinct data point/ study site.

1. COLUMNNAME description of contents

2. COLUMNNAME description of contents

3. COLUMNNAME description of contents

See Also

autoplot method for quick mapping of Vector occurrence point locations (autoplot.vector.points).

Examples

# Download vector occurrence data for Brazil and map the locations using autoplot.vector.points
## Not run: 
Brazil_vec <- getVecOcc(country = "Brazil")
autoplot(Brazil_vec)

# Download vector data for Madagascar and map the locations using autoplot
Madagascar_vec <- getVecOcc(ISO = "MDG", species = "All")
autoplot(Madagascar_vec)

# Subset by extent.
extent_vec <- getVecOcc(extent = matrix(c(100,13,110,18), nrow = 2), species = 'all')

## End(Not run)

Get the name from a wfs feature type id.

Description

Get the name from a wfs feature type id.

Usage

get_name_from_wfs_feature_type_id(id)

Arguments

Value

A name of the dataset

Get the WCS client for a raster ID.

Description

Get the WCS client for a raster ID.

Usage

get_wcs_client_from_raster_id(raster)

Arguments

Value

A WCSClient object.

WCS clients lazily created or from cache

Description

WCS clients lazily created or from cache

Usage

get_wcs_clients(logger = NULL)

Value

A list with of WCSClients by workspace

Get the WCS coverage summary for a raster ID.

Description

Get the WCS coverage summary for a raster ID.

Usage

get_wcs_coverage_summary_from_raster_id(raster)

Arguments

Value

A WCSCoverageSummary object.

WFS clients lazily created or from cache

Description

WFS clients lazily created or from cache

Usage

get_wfs_clients(logger = NULL)

Value

A list with of WFSClients by workspace

WMS clients lazily created or from cache

Description

WMS clients lazily created or from cache

Usage

get_wms_clients(logger = NULL)

Value

A list with of WMSClients by workspace

Get the workspace and version from a raster id.

Description

Get the workspace and version from a raster id.

Usage

get_workspace_and_version_from_coverage_id(id)

Arguments

Value

A list with the workspace and version.

Get the workspace and version from a wfs feature type id.

Description

Get the workspace and version from a wfs feature type id.

Usage

get_workspace_and_version_from_wfs_feature_type_id(id)

Arguments

Value

A list with the workspace and version.

Available data to download from the MAP geoserver.

Description

isAvaiable is a wrapper for isAvailable_pr and isAvailable_vec, listing data (PR survey point location data and vector occurrence locations available to download from the MAP geoserver.

Usage

isAvailable(
  sourcedata = NULL,
  full_results = FALSE,
  country = NULL,
  ISO = NULL,
  continent = NULL,
  ...
)

Arguments

Value

isAvailable returns a data.frame detailing the administrative units for which shapefiles are stored on the MAP geoserver.

See Also

link{isAvailable_pr} isAvailable_vec

Examples

## Not run: 
available_pr_locations <- isAvailable_pr(ISO = 'IDN')
available_vector_locations <- isAvailable_vec(ISO = 'IDN')

## End(Not run)

Check whether PR points are available for a given location

Description

isAvailable_pr checks whether the MAP database contains PR points for the specified country/location.

Usage

isAvailable_pr(
  sourcedata = NULL,
  country = NULL,
  ISO = NULL,
  continent = NULL,
  full_results = FALSE,
  version = NULL
)

Arguments

Value

isAvailable_pr returns a named list of input locations with information regarding data availability.

if full_results == TRUE, a named list is returned with the following elements:

1. location - specified input locations

2. is_available- 1 or 0; indicating whether data is available for this location

3. possible_match- agrep-matched country names indicating potential mispellings of countries where is_available == 0; NA if data is available for this location.

Examples

## Not run: 
isAvailable_pr(country = "Suriname")
x <- isAvailable_pr(ISO = "NGA", full_results = TRUE)
x <- isAvailable_pr(continent = "Oceania", full_results = TRUE)

## End(Not run)

Check whether Vector Occurrence points are available for a given location

Description

isAvailable_vec checks whether the MAP database contains Vector Occurrence points for the specified country/location.

Usage

isAvailable_vec(
  sourcedata = NULL,
  country = NULL,
  ISO = NULL,
  continent = NULL,
  full_results = FALSE,
  version = NULL
)

Arguments

Value

isAvailable_Vec returns a named list of input locations with information regarding data availability.

if full_results == TRUE, a named list is returned with the following elements:

1. location - specified input locations

2. is_available- 1 or 0; indicating whether data is available for this location

3. possible_match- agrep-matched country names indicating potential mispellings of countries where is_available == 0; NA if data is available for this location.

Examples

## Not run: 
isAvailable_vec(country = "Suriname")
x <- isAvailable_vec(ISO = "NGA", full_results = TRUE)
x <- isAvailable_vec(continent = "Oceania", full_results = TRUE)

## End(Not run)

Returns true if second band of raster is a mask

Description

Returns true if second band of raster is a mask

Usage

isMaskedRaster(raster)

Arguments

Deprecated function. Please instead use listPRPointCountries for pr points, listVecOccPointCountries for vector points, listRaster for raster and listShp for shape.

Description

listData deprecated function Please remove it from your code.

Usage

listData(datatype, printed = TRUE, ...)

Arguments

List all datasets from the Web Feature Services provided by the Malaria Atlas Project within the given workspace.

Description

This function lists minimal information of all the feature datasets from the Web Feature Services provided by the Malaria Atlas Project, in the given workspace.

Usage

listFeatureTypeDatasetsFromWorkspace(workspace)

Arguments

Value

A data.frame with columns 'id', 'version', and 'workspace' representing the unique identifier, version, and domain of the datasets

List countries where there is pr point data available

Description

listPRPointCountries

Usage

listPRPointCountries(printed = TRUE, version = NULL)

Arguments

Value

listPRPointCountries returns a data.frame detailing the countries for which PR points are publicly available.

List all dataset versions from the Web Feature Services provided by the Malaria Atlas Project within the Parasite Rate workspace.

Description

listPRPointVersions lists available versions of parasite rate point data from the Web Feature Services provided by the Malaria Atlas Project.

Usage

listPRPointVersions(printed = TRUE)

Arguments

Value

A data.frame with column 'version' The version can then be provided to other functions to fetch the data within that dataset. e.g. in getPR

Examples

## Not run: 
prDatasets <- listPRPointVersions()

## End(Not run)

Deprecated function. Please instead use listPRPointCountries for pr points, and listVecOccPointCountries for vector points

Description

listPoints deprecated function Please remove it from your code.

Usage

listPoints(printed = TRUE, sourcedata, version = NULL)

Arguments

List all MAP Rasters available to download.

Description

listRaster lists all rasters available to download from the Malaria Atlas Project database.

Usage

listRaster(printed = TRUE)

Arguments

Value

listRaster returns a data.frame detailing the following information for each raster available to download from the Malaria Atlas Project database.

1. dataset_id the unique dataset ID of the raster, which can the be used in functions such as getRaster and extractRaster

2. raster_code unique identifier for each raster

3. title abbreviated title for each raster, used as surface argument in getRaster()

4. title_extended extended title for each raster, detailing raster content

5. abstract full description of each raster, outlining raster creation methods, raster content and more.

6. citation citation of peer-reviewed article in which each raster has been published

7. pub_year year in which raster was published, used as pub_year argument in getRaster() to updated raster versions from their predecessor(s).

8. min_raster_year earliest year for which each raster is available

9. max_raster_year latest year for which each raster is available

Examples

## Not run: 
available_rasters <- listRaster()

## End(Not run)

List administrative units for which shapefiles are stored on the MAP geoserver.

Description

listShp lists all administrative units for which shapefiles are stored on the MAP geoserver.

Usage

listShp(printed = TRUE, admin_level = c("admin0", "admin1"), version = NULL)

Arguments

Value

listShp returns a data.frame detailing the administrative units for which shapefiles are stored on the MAP geoserver.

Examples

## Not run: 
available_admin_units <- listShp()
available_admin_units <- listShp(admin_level = c('admin2','admin3'), version = '202206')

## End(Not run)

List all versions of admin unit shapes from the Web Feature Services provided by the Malaria Atlas Project within the Admin Units workspace.

Description

listShpVersions lists available versions of Admin Unit shapefiles from the Web Feature Services provided by the Malaria Atlas Project.

Usage

listShpVersions(printed = TRUE)

Arguments

Value

A data.frame with column 'version'. The version can then be provided to other functions to fetch the data within that dataset. e.g. in getShp

Examples

## Not run: 
vecOccDatasets <- listShpVersions()

## End(Not run)

list all species which have occurrence data within the MAP database.

Description

listSpecies lists all species occurrence data available to download from the Malaria Atlas Project database.

Usage

listSpecies(printed = TRUE, version = NULL)

Arguments

Value

listSpecies returns a data.frame detailing the following information for each species available to download from the Malaria Atlas Project database.

1. species string detailing species

Examples

## Not run: 
available_species <- listSpecies()

## End(Not run)

List countries where there is vector occurrence point data available

Description

listVecOccPointCountries

Usage

listVecOccPointCountries(printed = TRUE, version = NULL)

Arguments

Value

listVecOccPointCountries returns a data.frame detailing the countries for which vector occurrence points are publicly available.

List all dataset versions from the Web Feature Services provided by the Malaria Atlas Project within the Vector Occurrence workspace.

Description

listVecOccPointVersions lists available versions of all the feature datasets in the Vector Occurrence workspace from the Web Feature Services provided by the Malaria Atlas Project.

Usage

listVecOccPointVersions(printed = TRUE)

Arguments

Value

A data.frame with column 'version'. The version can then be provided to other functions to fetch the data within that dataset. e.g. in getVecOcc

Examples

## Not run: 
vecOccDatasets <- listVecOccPointVersions()

## End(Not run)

Create a single (sub) plot for a SpatRaster

Description

Create a single (sub) plot for a SpatRaster

Usage

makeSpatRasterAutoplot(
  spatraster,
  rastername,
  shp_df,
  legend_title,
  fill_scale_transform,
  fill_colour_palette,
  plot_titles
)

Arguments

Value

ggplot object

An R interface to open-access malaria data, hosted by the Malaria Atlas Project.

Description

malariaAtlas provides a suite of tools to allow you to download all publicly available PR points for a specified country (or ALL countries) as a dataframe within R.

malariaAtlas functions

1. listAll - lists all countries for which there are publicly visible PR datapoints in the MAP database.

2. is_available - checks whether the MAP database contains PR points for the specified country/countries.

3. getPR - downloads all publicly available PR points for a specified country (or countries) and returns this as a dataframe.