call.MGRAST: Interface to MG-RAST API
In MGRASTer: API Client for the MG-RAST Server of the US DOE KBase

Description Usage Arguments Details Value Author(s) References See Also Examples

An interface to the MG-RAST API enabling convenient access in the R environment to provided resources, as well as facilitating export.

call.MGRAST(resource, request, ..., args=NULL, destfile=NULL, parse=is.null(destfile), 
  verify=parse, bugs=c("ignore", "warn", "stop", "ask", "report"), quiet=TRUE,
  timeout=300, issue=TRUE)
parse.MGRAST(call.url)

`resource`	name of API resource (string)
`request`	name of request, valid for the specified resource (string)
`...`	required and/or optional parameters for the call
`args`	further parameters (`list`)
`destfile`	file to save the retrieved resource (string)
`parse`	attempt JSON parsing of result? (`logical`)
`verify`	check integrity of the returned object? (`logical`)
`bugs`	reporting action for API-side problems – not used
`quiet`	print debugging messages? (`logical`)
`timeout`	number of seconds to allow for the call (single `integer`)
`issue`	issue the call, or only return the constructed URL? (`logical`)
`call.url`	URL for an API resource (string)

This documentation assumes familiarity with the MG-RAST API, which is described elsewhere.

resource and request are required for all API calls. Optional and required parameters may be given in ... and must be named. In general, parameters should be length-one character vectors, which is what is meant by "string", above. Regardless, parameters are coerced by as.character. Parameters may also be given with args, which must be a named list. Partial resource, request, and parameter names are matched wherever possible, as are partial parameter values tied to a controlled vocabulary.

Parameters named id are specially handled with some helpful scrubbing. In particular, prefixes mgl, mgm, mgp, and mgs are added as necessary, and multiple ids given in a vector are separated.

For certain resource-request combinations, destfile is mandatory. For all others, it is optional. When verify=TRUE a check is made that all documented components for a resource-request are actually received.

Setting quiet=FALSE can help shed light on unexpected results.

parse.MGRAST() tokenizes a valid API URL. If x is a URL validly requesting an API resource, then do.call(call.MGRAST, parse.MGRAST(x)) will retrieve that resource.

For call.MGRAST(), a list mirroring the JSON structure of the received resource (invisibly). But if parse=FALSE, then the resource, uninterpreted. For non-JSON resources, parse is ignored.

But if destfile is not NULL and the resource was successfully written to destfile, then destfile. If parse=TRUE and relevant, the file is written in .rda format, otherwise raw (usually meaning, as legible text).

Only a URL for the specified resource, if issue=FALSE.

For parse.MGRAST(), a named list including resource, request, and further parameters for the indicated API call.

Daniel T. Braithwaite

http://metagenomics.anl.gov
http://api.metagenomics.anl.gov
http://www.json.org

doc.MGRAST, MGRASTAPI

## Not run: 
##  The calls below are adapted from the MG-RAST API documentation pages.
##  An example is provided for most resource types.
##  Note that resources are returned invisibly by call.MGRAST().
##  These examples are "not run" because they take too long.

##
##  Use of call.MGRAST(), parse.MGRAST(), and do.call() together

parse.MGRAST ("http://api.metagenomics.anl.gov/download/mgm4447943.3?stage=650")
ll <- list (id=4447943.3, stage=650)
call.MGRAST ("down", "set", args=ll)

print (tt <- tempfile())
parse.MGRAST ("http://api.metagenomics.anl.gov/download/mgm4447943.3?file=350.1")
call.MGRAST ("down", "inst", id=4447943.3, file=350.1, destfile=tt)
parse.MGRAST (call.MGRAST (issue=FALSE, "down", "inst", id=4447943.3, file=350.1, 
	destfile=tt))
unlink (tt)

parse.MGRAST ("http://api.metagenomics.anl.gov/library?limit=20&order=name")
call.MGRAST ("lib", "query", lim=20, ord="name")
do.call (call.MGRAST, 
	parse.MGRAST ("http://api.metagenomics.anl.gov/library?limit=20&order=name"))

##
##  accessing the "m5nr" resource

call.MGRAST ("m5", "ont", source="Sub", min="level3")
call.MGRAST ("m5", "tax", filter="Bacteroidetes", filter_lev="phylum", min="genus")
call.MGRAST ("m5", "md5", id="000821a2e2f63df1a3873e4b280002a8", source="InterPro")
call.MGRAST ("m5", "func", text="sulfatase", source="GenBank")
call.MGRAST ("m5", "seq", text="MAGENHQWQGSIL", source="TrEMBL")

##
##  parsing URLs for the calls above

parse.MGRAST (
	"http://api.metagenomics.anl.gov/m5nr/ontology?source=Subsystems&min_level=level3")
parse.MGRAST (paste0 ("http://api.metagenomics.anl.gov/m5nr/taxonomy",
	"?filter=Bacteroidetes&filter_level=phylum&min_level=genus"))
parse.MGRAST (paste0 ("http://api.metagenomics.anl.gov/m5nr/md5/",
	"000821a2e2f63df1a3873e4b280002a8?source=InterPro"))
parse.MGRAST ("http://api.metagenomics.anl.gov/m5nr/function/sulfatase?source=GenBank")
parse.MGRAST (
	"http://api.metagenomics.anl.gov/m5nr/sequence/MAGENHQWQGSIL?source=TrEMBL")

##
##  annotation data via the "matrix" resource,
##  and different ways to provide arguments

xx <- c (4447943.3, 4447192.3, 4447102.3, 4447103.3)
yy <- "4447943.3 4447192.3 4447102.3 4447103.3"
aa <- list (group="level3", source="Sub", res="ab", ident=80, 
	filter_lev="phylum", filter="Firmicutes")
call.MGRAST ("matrix", "org", id=xx, group="family", source="Ref", result="abund", eval=15)
call.MGRAST ("matrix", "func", id=xx, args=aa)
call.MGRAST ("matrix", "feat", id=yy, source="KEGG", result="ev", len=25)

##
##  parsing URLs for the calls above

parse.MGRAST (paste0 (
	"http://api.metagenomics.anl.gov/matrix/organism",
	"?id=mgm4447943.3&id=mgm4447192.3&id=mgm4447102.3&id=mgm4447103.3",
	"&group_level=family&source=RefSeq&result_type=abundance&evalue=15"))
parse.MGRAST (paste0 (
	"http://api.metagenomics.anl.gov/matrix/function",
	"?id=mgm4447943.3&id=mgm4447192.3&id=mgm4447102.3&id=mgm4447103.3",
	"&group_level=level3&source=Subsystems&result_type=abundance&identity=80",
	"&filter_level=phylum&filter=Firmicutes"))
parse.MGRAST (paste0 (
	"http://api.metagenomics.anl.gov/matrix/feature",
	"?id=mgm4447943.3&id=mgm4447192.3&id=mgm4447102.3&id=mgm4447103.3",
	"&source=KEGG&result_type=evalue&length=25"))

##
##  examples for still other resources

parse.MGRAST ("http://api.metagenomics.anl.gov/metadata/export/mgp128")
call.MGRAST ("metadata", "exp", id=128)

parse.MGRAST (
	"http://api.metagenomics.anl.gov/metagenome/mgm4447943.3?verbosity=metadata")
call.MGRAST ("metagenome","inst", id=4447943.3, verb="meta")

parse.MGRAST ("http://api.metagenomics.anl.gov/project?limit=20&order=name")
call.MGRAST ("proj", "query", lim=20, ord="name")

parse.MGRAST ("http://api.metagenomics.anl.gov/sample/mgs25823?verbosity=full")
call.MGRAST ("samp", "inst", id=25823, verb="full")

##
##  finally, examples for annotation downloads (they take substantial time)

print (tt <- tempfile())
call.MGRAST ("annot", "seq", id=4447943.3, eval=10, type="org", source="Swiss",
	destfile=tt)
call.MGRAST ("annot", "sim", id=4447943.3, ident=80, type="fu", source="KO", 
	destfile=tt)
unlink (tt)

## End(Not run)