getNMDinfo: Get NMD API data and reference information
In Sea2Data/Rstox: Running Stox functionality independently in R

Description Usage Arguments Details Examples

getNMDinfo converts, prints and optionally returns NMD reference information given a search string to the reference information. Used in StoX.URL().

getNMDdata downloads data from specific cruises, cruise series ot survey time series from NMD.

downloadXML downloads xml data from an API, parses the xml data, and converts to a list (the latter is time consuming).

getNMDinfo(type = NULL, ver = getRstoxDef("ver"),
  server = "http://tomcat7.imr.no:8080/apis/nmdapi", recursive = TRUE,
  msg = FALSE, simplify = TRUE, return.URL = FALSE)

getNMDdata(cruise = NULL, year = NULL, shipname = NULL,
  serialno = NULL, tsn = NULL, datasource = NULL, dir = NULL,
  subdir = FALSE, group = "default", abbrev = FALSE, subset = NULL,
  prefix = "NMD", suffix = NA, ver = getRstoxDef("ver"),
  server = "http://tomcat7.imr.no:8080/apis/nmdapi", cleanup = TRUE,
  model = "StationLengthDistTemplate", msg = TRUE, ow = NULL,
  return.URL = FALSE, info.out = FALSE, run = TRUE, timeout = NULL,
  snapshot = Sys.time(), ...)

getNMDver(ver = NULL)

downloadXML(URL, msg = FALSE, list.out = TRUE, file = NULL,
  method = "auto", timeout = NULL)

`type`	A character string naming the type of information to return for the specifications given in 'spec'. Possible values are shown in the list below. Any reference data can be requested, and the names of the possible reference data are returned by running getNMDinfo(): NULL List of available reference data "c" List of cruises (Will be implemented in version 2) "cs" List of cruise series. If given as a vector of length 2, where the first element is "cs" and the second is the exact case sensitive name of a cruise series, information only about that cruise sereis is returned. "sts" List of survey time series. Can be given as a two element vector as for "cs". "v" List of vessels, where the first line of the platform information is extracted and presented in a matrix with vessels in the rows. Use "platform" to preserve all details about the platforms/vessels
`ver`	The version of the APIs and data, given as a list such as that returned by getRstoxDef("ver"). To use version 1 of the API (the only one available prior to Rstox 1.10) use getRstoxDef("ver", API=list(biotic=1, reference=1)), or simply ver = 1. Giving `ver` as a single integer imposes this value on all API versions. To set API versions to 1 and at the same time set the version of the data, use e.g. ver = list(API=1, biotic=1.4).
`server`	The path of the server.
`recursive`	Logical, special for type %in% c("cs","sts"); if FALSE only the list of cruise series or survey time series is returned.
`msg`	Logical: if TRUE a message is printed to the consolle stating the estimated time left for the funciton.
`simplify`	Logical: if TRUE simplify the data into matrices instead of complicated lists in some cases like taxa.
`return.URL`	Logical: If TRUE, return the URL of the files to download.
`cruise`	Either the code of a cruise, such as "2015116", or the full or short name of a cruise series or survey time series. In the current version, if given as a cruise code, the parameter 'shipname' must be given as well, based on which the path to the cruise is searched for by functionallity provided by NMD. For cruises prior to the year 1995 several vessels can be linked to the same cruise code, and as of version 2 the user will by default be asked to specify which vessel(s) to specify the vessels when this occurs, instead of having to specify the cruise initially.
`year`	Used in conjunction with 'shipname' to get all cruises from one or more years from a specific ship.
`shipname`	Specifies the ship name WITHOUT call signal, e.g., "G.O.Sars" and not "G.O.Sars_LMEL" (see 'cruise' and 'year').
`serialno`	A vector of the requested serial numbers.
`tsn`	The species code for downloading a specific species. See the examples for how to get the `tsn` of a species.
`datasource`	The type of data requested. Currently implemented are "echosunder" and "biotic", while "landing" and "ctd" are in the pipeline. datasource=NULL (default) returns all possible data.
`dir`	The path to the directory in which to place the StoX project holding the downloaded data, or TRUE indicating that a sub directory should be created in which to put mulpitle with the name of the in which to put the downloaded projects
`subdir`	Either a name of the sub directory in which to put the StoX projects of downloaded data, or TRUE which puts all projects in a sub folder named after the cruise series or survey time series.
`group`	Specifies how to gruop the data: (1) If given as "year", the data are split into years, and one StoX project is saved for each year; (2) if given as "cruise", one Stox project is generated for each cruise, and (3) group is "all", NULL or NA, all data are saved in one StoX project. Abbreviations are accepted (e.g., group="c"). The default "default" groups by years if several cruises are requested and by cruise otherwise. The projects generated from the downloaded data are named differently depending on the grouping, with, e.g., the suffixes "_Year_2004"/"_CruiseNumber_2004204_ShipName_Johan Hjort"/"_Alldata" for group = "year"/"cruise"/"all". This implies that the projects downloaded using group = "year" are not replaced when using group = "cruise", even if there is only one cruise per year.
`abbrev`	Logical: If TRUE, abbreviate the project names. Particularly useful when downloading survey time series, which can have long names.
`subset`	An vector giving the subset of the cruises/projects to download in a cruise series/survey time series. Can be given either as indices such as 1:3 or -4 or as a vector of years or cruise numbers such as c(2005, 2007, 2008) or c(2005105, 2007845, 2008809). Get the years and cruise numbers using getNMDinfo("cs").
`prefix, suffix`	The prefix/suffix to use in the names of the StoX projects to which the data are downloaded, separated from the file name by underscore.
`cleanup`	Logical: if FALSE, zip files containing cruise series or survey time series are not deleted.
`model`	The model to use, either given as a string specifying a template, or a vector of process names or list of processes given as lists of parameter specifications (not yet implemented). Show available templates with createProject().
`ow`	Specifies whether to ovewrite existing project: If TRUE, overwrite; if FALSE, do not overwrite; if NULL (default), aks the user to confitm overwriting.
`info.out`	Logical: If TRUE, return a data frame with download info along with the project paths.
`run`	Logical: If TRUE, download data and generate projects. If FALSE, only generate project names (useful for retrieveing the project names without downloading).
`timeout`	If given, the timeout of the reponse to download.file() is set. Only used on Windows and if used, method is forced to "internal". Note that setting `timeout` in options() will not have the desired effect, since it requires method = "internal" to be set in `download.file` (which is used by `getNMDdata`).
`snapshot`	A time stamp specifying which snapshot to download. The latest snapshot before this time stamp is found and downloaded. The specific snapshot ID can also be given, as a string in the format returned from getRstoxDef("dateTimeNMDAPIFormat").
`...`	Same as parlist, but can be specified separately (not in a list but as separate inputs).
`URL`	The URL(s) to the xml data, or the path to a local XML file.
`list.out`	Logical: If TRUE, convert the XML data to a list (time consuming).
`file`	The path to a the file to which the data are saved.
`method`	The download method. See `download.file`.

If non-standard characters are not shown as expected, it might be an issue of locale encoding. It may help to run Sys.setlocale(category = "LC_ALL", locale = ""), at least to display nordic characters on a nordic system.

## Not run: 
# A list of available reference data:
g1 <- getNMDinfo()
# List of cruise series:
g2 <- getNMDinfo("cs")
# List of survey time series:
g3 <- getNMDinfo("sts")
# List of vessels (the first vessel per platform) and the more complicated list of platforms,
# (where there can be several vessels per platform). These requestes may take tens of seconds:
g5 <- getNMDinfo("platform")
# Get other types of information:
g6 <- getNMDinfo("gearcondition")
g7 <- getNMDinfo("missiontype")
g8 <- getNMDinfo("person")
g9 <- getNMDinfo("taxa")
# Get the tsn code of torsk:
g9[g9$Norwegian=="torsk",]
# And all names containing "torsk":
g9[grep("torsk", g9$Norwegian, ignore.case=TRUE),]

## End(Not run)

# Download all reference data (takes at lest 5 minutes):
# system.time(l <- lapply(g1, getNMDinfo, msg=TRUE))

# For examples of downloading data from Norwegian Marine Data Centre (NMD in norwegian), 
# go to ftp://ftp.imr.no/StoX/Download/Rstox/Examples/Rstox-example_1.10.R.