getLayer: Query, subset, and/or summarize HarvestChoice indicators

In harvestchoice/hc-api3: HarvestChoice Data Services v3

Description

Workhorse method to query, subset and/or aggregate HarvestChoice layers. This method may also be used to summarize classified variables along continuous variables, e.g. getLayer(var="AEZ16_CLAS", by="bmi"). It does so by returning the dominant class of a classified variable within each by class, and by splitting any continuous variable passed to by using default value breaks. The dominant class of a variable var is defined as dominant(var). Variables may also be summarized over custom areas (passed as an integer array of gridcell IDs). Note that calling getLayer is equivalent to using the convenience method hcapi with the same arguments.

Usage

getLayer(var, iso3 = "SSA", by = NULL, ids = NULL, collapse = TRUE,
  as.class = "data.table")

Arguments

var	character array of variable names (all types are accepted). Use e.g. category("poverty") to search for valid variable codes).
iso3	optional array of 3-letter country or regional code(s) to filter by. Use iso to view all available codes.
by	optional character array of variables to summarize by (all types are accepted)
ids	optional array of gridcell ids to filter by (if collapse=FALSE) or summarize by (if collapse=TRUE).
collapse	if TRUE collapses over by variables. If FALSE always return all pixel values (useful for plotting and to convert to spatial formats).
as.class	one of "data.table" (default) or "list". By default returns a simple data.table. If as.class="list" returns a list with variable metadata.

Details

API call: mean body mass index and maize yield across districts in Tanzania

$ curl http://hcapi.harvestchoice.org/ocpu/library/hcapi3/R/hcapi/json \ -d '{"var":["AEZ8_CLAS","bana_h"], "iso3":"CIV", "by":["ADM1_NAME_ALT","ELEVATION"]}' \ -X POST -H 'Content-Type:application/json'

Value

a data.table (or json array) of var indicators aggregated by by domains

See Also

hcapi and getLayerWKT

Examples

# Mean body mass index and maize yield across districts in Tanzania
x <- getLayer(c("bmi", "maiz_y"), iso3="TZA", by=c("ADM1_NAME_ALT", "ADM2_NAME_ALT"))
x

# Plot results for Mara province
require(lattice)
barchart(ADM2_NAME_ALT~bmi, x[ADM1_NAME_ALT=="Mara"], col="grey90")

# The method may be expanded to summarize classified (discrete) variables by continuous
# variables. For example the call below returns the dominant agro-ecological zone and
# banana harvested area over Ivory Coast's provinces and elevation zones
x <- hcapi(c("AEZ8_CLAS", "bana_h"), iso3="CIV", by=c("ADM1_NAME_ALT", "ELEVATION"))
x

harvestchoice/hc-api3 documentation built on May 17, 2019, 3:04 p.m.