finished off argo, for now at least, fix #123

DESCRIPTION

@@ -7,7 +7,7 @@ Description: Client for many 'NOAA' data sources including the 'NCDC' climate
     for 'NOAA' sea ice data, the 'NOAA' severe weather inventory, 'NOAA' Historical
     Observing 'Metadata' Repository ('HOMR') data, 'NOAA' storm data via 'IBTrACS',
     tornado data via the 'NOAA' storm prediction center, and more.
-Version: 0.5.0.9500
+Version: 0.5.0.9800
 License: MIT + file LICENSE
 Authors@R: c(
     person("Hart", "Edmund", role = "ctb", email = "[email protected]"),

NAMESPACE

@@ -17,7 +17,11 @@ S3method(type_summ,integer)
 S3method(type_summ,logical)
 S3method(type_summ,matrix)
 S3method(type_summ,numeric)
+export(argo)
+export(argo_buoy_files)
 export(argo_files)
+export(argo_plan)
+export(argo_qwmo)
 export(argo_search)
 export(buoy)
 export(buoys)

R/argo.R

@@ -2,50 +2,87 @@
 #'
 #' @export
 #' @name argo
-#' @param gt gt string
-#' @param of of string
-#' @param qwmo qwmo string
-#' @param wmo wmo string
-#' @param box Bounding box, of the form: min lon, min lat, max lon, max lat
-#' @param limit (integer) number to return
-#' @param ... Curl options passed on to \code{\link[httr]{GET}}. Optional
-#' @references \url{http://www.ifremer.fr/lpo/naarc/m/docs/api/howto.html}
-#' @examples \dontrun{
-#' argo_search("n", limit = 3)
-#' argo_search("np", limit = 3)
-#' argo_search("nf", limit = 3)
-#' argo_search("coord", limit = 3)
-#' argo_search("fullcoord", limit = 5)
-#' argo_search("list", "dac", limit = 5)
-#' argo_search(qwmo = 49, limit = 3)
-#' argo_search("n", box = c(-40, 35, 3, 2))
-#' 
-#' argo_files(wmo = 4900881)
-#' }
-argo_search <- function(gt = NULL, of = NULL, qwmo = NULL, 
-                 wmo = NULL, box=NULL, limit = 10, ...) {
-  args <- noaa_compact(list(get = gt, of = of, qwmo = qwmo, 
-                            wmo = wmo, file = file, box = box, 
-                            limit = limit))
-  argo_GET(argo_base(), args, ...)
+#' @template argo_params
+#' @template argo_egs
+argo_search <- function(func = NULL, of = NULL, qwmo = NULL, wmo = NULL, box=NULL, 
+                        area = NULL, around = NULL, year = NULL, yearmin = NULL, 
+                        yearmax = NULL, month = NULL, monthmin = NULL, monthmax = NULL, 
+                        lr = NULL, from =NULL, to = NULL, dmode = NULL, 
+                        pres_qc = NULL, temp_qc = NULL, psal_qc = NULL, doxy_qc = NULL, 
+                        ticket = NULL, limit = 10, ...) {
+
+  args <- noaa_compact(list(get = func, of = of, qwmo = qwmo, wmo = wmo, file = file, 
+      box = box, area = area, around = around, year = year, yearmin = yearmin, 
+      yearmax = yearmax, month = month, monthmin = monthmin, monthmax = monthmax,
+      lr = lr, from = from, to = to, dmode = dmode, pres_qc = pres_qc, temp_qc = temp_qc, 
+      psal_qc = psal_qc, doxy_qc = doxy_qc, ticket = ticket, limit = limit))
+  res <- argo_GET(argo_api(), args, ...)
+  jsonlite::fromJSON(content(res, "text"))
 }
 
 #' @export
 #' @rdname argo
-argo_files <- function(gt = NULL, of = NULL, qwmo = NULL, 
-                       wmo = NULL, box=NULL, ...) {
-  args <- noaa_compact(list(get = gt, of = of, qwmo = qwmo, 
-                            wmo = wmo, file = "", box = box))
-  argo_GET(argo_base(), args, ...)
+argo_files <- function(wmo = NULL, cyc = NULL, ...) {
+  args <- noaa_compact(list(wmo = wmo, cyc = cyc, file = ""))
+  res <- argo_GET(argo_api(), args, ...)
+  jsonlite::fromJSON(content(res, "text"))
+}
+
+#' @export
+#' @rdname argo
+argo_qwmo <- function(qwmo, limit = 10, ...) {
+  args <- noaa_compact(list(qwmo = qwmo, limit = limit))
+  res <- argo_GET(argo_api(), args, ...)
+  jsonlite::fromJSON(content(res, "text"))
+}
+
+#' @export
+#' @rdname argo
+argo_plan <- function(...) {
+  args <- noaa_compact(list(plan = ""))
+  res <- argo_GET(argo_api(), args, ...)
+  jsonlite::fromJSON(content(res, "text"))
+}
+
+#' @export
+#' @rdname argo
+argo_buoy_files <- function(dac, id, ...) {
+  tfile <- tempfile(fileext = ".txt")
+  url <- paste0(argo_ftp(), sprintf('dac/%s/%s/profiles/', dac, id))
+  download.file(url, destfile = tfile, quiet = TRUE)
+  res <- readLines(tfile, warn = FALSE)
+  tab <- read.table(text = res, stringsAsFactors = FALSE)
+  tab[,NCOL(tab)]
+}
+
+#' @export
+#' @rdname argo
+argo <- function(dac, id, cycle, dtype, path = "~/.rnoaa/argo", overwrite = TRUE, ...) {
+  path <- file.path(path, dac)
+  apath <- a_local(dac, id, cycle, dtype, path)
+  if (!is_isd(apath)) {
+    dir.create(path, showWarnings = FALSE, recursive = TRUE)
+    suppressWarnings(argo_GET(a_remote(dac, id, cycle, dtype), list(), write_disk(apath, overwrite), ...))
+  }
+  message(sprintf("<path> %s", apath), "\n")
+  ncdf4::nc_open(apath)
 }
 
 # helpers -----------------------------------
-argo_GET <- function(url, args, ...) {
+argo_GET <- function(url, args = list(), ...) {
   res <- GET(url, query = args, ...)
   stop_for_status(res)
-  jsonlite::fromJSON(content(res, "text"))  
+  res
 }
 
-argo_base <- function() "http://www.ifremer.fr/lpo/naarc/api/v1"
+argo_base <- function() "http://www.ifremer.fr/"
+argo_api <- function() paste0(argo_base(), "lpo/naarc/api/v1")
+argo_ftp <- function() "ftp://ftp.ifremer.fr/ifremer/argo/"
+
+a_local <- function(dac, id, cycle, dtype, path) {
+  file.path(path, sprintf("%s%s_%s.nc", dtype, id, cycle))
+}
 
-# http://www.ifremer.fr/lpo/naarc/api/v1/?file&wmo=4900881
+a_remote <- function(dac, id, cycle, dtype) {
+  file.path(argo_ftp(), "dac", dac, id, "profiles", sprintf("%s%s_%s.nc", dtype, id, cycle))
+}

man-roxygen/argo_egs.R

@@ -0,0 +1,81 @@
+#' @examples \dontrun{
+#' # Search Argo metadata 
+#' ## Number of profiles
+#' argo_search("np", limit = 3)
+#' ## Number of floats
+#' argo_search("nf", limit = 3)
+#' ## Number of both profiles and floats
+#' argo_search("n", limit = 3)
+#' ## return the coordinates in time and space of profiles
+#' argo_search("coord", limit = 3)
+#' ## return the coordinates in time and space of profiles, plus other metadata
+#' argo_search("fullcoord", limit = 3)
+#' 
+#' ## List various things, e.g,...
+#' ### data assembly centers
+#' argo_search("list", "dac")
+#' ### data modes
+#' argo_search("list", "dmode", limit = 5)
+#' ### World Meteorological Organization unique float ID's
+#' argo_search("list", "wmo", limit = 5)
+#' ### Profile years
+#' argo_search("list", "year", limit = 5)
+#' 
+#' ## coord or fullcoord with specific buoy id
+#' argo_search("coord", wmo = 4900881, limit = 3)
+#' argo_search("fullcoord", wmo = 4900881, limit = 3)
+#' 
+#' # Spatial search
+#' ### search by bounding box (see param def above)
+#' argo_search("coord", box = c(-40, 35, 3, 2))
+#' ### search by area
+#' argo_search("coord", area = 0)
+#' ### search by around
+#' argo_search("coord", around = '-40,35,100')
+#' 
+#' # Time based search
+#' ### search by year
+#' argo_search("coord", year = 2006)
+#' ### search by yearmin and yearmax
+#' argo_search("coord", yearmin = 2007)
+#' argo_search("coord", yearmin = 2007, yearmax = 2009)
+#' ### search by month
+#' argo_search("coord", month = '12,1,2')
+#' ### search by lr
+#' argo_search("coord", lr = 7)
+#' ### search by from or to
+#' argo_search("coord", from = 20090212)
+#' argo_search("coord", to = 20051129)
+#' 
+#' # Data mode search
+#' argo_search("coord", dmode = "R")
+#' argo_search("coord", dmode = "R,A")
+#' 
+#' # Data quality based search
+#' argo_search("coord", pres_qc = "A,B")
+#' argo_search("coord", temp_qc = "A")
+#' argo_search("coord", pres_qc = "A", temp_qc = "A")
+#' 
+#' # Ticket search
+#' argo_search("coord", ticket = 1)
+#' 
+#' ## Search on partial float id number
+#' argo_qwmo(qwmo = 49)
+#' argo_qwmo(qwmo = 49, limit = 2)
+#' 
+#' ## Get files
+#' argo_files(wmo = 6900087)
+#' argo_files(wmo = 6900087, cyc = 12)
+#' argo_files(wmo = 6900087, cyc = 45)
+#' 
+#' ## Get planned buoys data, accepts no parameters
+#' argo_plan()
+#' 
+#' # Get files for a buoy, must specify data assembly center (dac)
+#' argo_buoy_files(dac = "bodc", id = 1901309)
+#' argo_buoy_files(dac = "kma", id = 2900308)
+#' 
+#' # Get data
+#' x <- argo_buoy_files(dac = "meds", id = 4900881)
+#' argo(dac = "meds", id = 4900881, cycle = 127, dtype = "D")
+#' }

man-roxygen/argo_params.R

@@ -0,0 +1,98 @@
+#' @param func A function, one of n, np, nf, coord, fullcoord, list, ftplist, ticket, version
+#' @param of of string
+#' @param qwmo qwmo string
+#' @param wmo wmo string. mandatory when using \code{argo_files}
+#' @param box Bounding box, of the form: A) lon, lat for geographical coordinates of 
+#' the center of a box, or B) min lon, min lat, width, height, for geographical
+#' coordinates of the center of the box and its width and height, and the longitude must 
+#' given between -180W and 180E. Width and height are in degrees of longitude and latitude.
+#' @param area (integer/character), One of 0, 1, or 2, but can be in combination. e.g. 0, '0,2'
+#' See Details.
+#' @param around (character) Selects profiles located around a given center point. List of 
+#' 3 or 4 numerical values depending on how the center point need to be specified: 
+#' e.g., '-40,35,100', '6900678,2,200', '6900678,2,200,30'. See Details
+#' @param cyc a cycle number
+#' @param year restrict profiles sampled on a single, or a list of given years. One or a 
+#' comma separated list of numerical value(s) higher than 0 and lower than 9999.
+#' @param yearmin,yearmax restrict profiles sampled before (yearmax) and/or after (yearmin) 
+#' a given year. A numerical value higher than 0 and lower than 9999. cannot be applied with 
+#' the other restriction parameter \code{year}
+#' @param month restrict profiles sampled on a single, or a list of given month(s). One or a 
+#' comma separated list of numerical value(s) higher or equal to 1 and lower or equal to 12. 
+#' The month convention is a standard one: January is 1, February is 2, ... December is 12.
+#' @param monthmin,monthmax restrict profiles sampled before (monthmax) and/or after (monthmin) 
+#' a given month. Higher or equal to 1 and lower or equal to 12. The month convention is a 
+#' standard one: January is 1, February is 2, ... December is 12. These restrictions cannot be 
+#' applied with the other restriction parameter month. At this time, these parameters are not 
+#' circular, so that the restriction chain: monthmin=12&monthmax=2 will through an error 
+#' and not select December to February profiles. To do so, you need to use a coma separated 
+#' list of months using the month restriction parameter.
+#' @param lr restriction allows you to impose the last report (hence lr) date in days. A 
+#' numerical value in days between 1 (profiles sampled yesterday) and 60 (profiles sampled 
+#' over the last 60 days). This restriction allows a simple selection of the so-called 
+#' 'active' floats, ie those which reported a profiles over the last 30 days.
+#' @param from,to select profiles sampled before (to) and/or after (from) an explicit date 
+#' (included). The date is specified following the format: YYYYMMDD, ie the year, month 
+#' and day numbers.
+#' @param dmode (character) imposes a restriction on the Data Mode of profiles. A single value or 
+#' a coma separated list of characters defining the Data Mode to select. It can be: R for 
+#' "Real Time", A for "Real Time with Adjusted value" and D for "Delayed Mode". See Details.
+#' @param pres_qc,temp_qc,psal_qc,doxy_qc Quality control. Imposes a restriction on the profile 
+#' data quality flag. For a given variable <PARAM> which can be: pres (pressure), 
+#' temp (temperature), psal (salinity) or doxy (oxygen), this restriction selects profiles 
+#' having one or a coma separated list of data quality flag. See Details.
+#' @param ticket (numeric) select profiles with or without a ticket filled in the database. A 
+#' value: 0 (no ticket) or 1 (has a ticket). See 
+#' http://www.ifremer.fr/lpo/naarc/m/docs/api/database.html for more details.
+#' @param dac (character) Data assembly center code
+#' @param id (numeric) Buoy identifier
+#' @param cycle (numeric) Cycle number
+#' @param dtype (character) Data type, one of \code{D} for delayed, or \code{R} for real-time
+#' @param path (character) Base path to write argo netcdf files to, this isn't for each file itself, that's 
+#' determined by input parameters
+#' @param overwrite (logical) Will only overwrite existing path if \code{TRUE}
+#' @param limit (integer) number to return
+#' @param ... Curl options passed on to \code{\link[httr]{GET}}. Optional
+#' @references \url{http://www.ifremer.fr/lpo/naarc/m/docs/api/howto.html}
+#' @details 
+#' \code{area} parameter definitions:
+#' \itemize{
+#'  \item Value 0 selects profiles located in the North-Atlantic ocean north of 20S 
+#'  and not in areas 1 and 2.
+#'  \item Value 1 selects profiles located in the Mediterranean Sea.
+#'  \item Value 2 selects profiles located in the Nordic Seas.
+#' }
+#' 
+#' \code{around} parameter definitions:
+#' \itemize{
+#'  \item Specification 1: The location is specified with specific geographical 
+#'  coordinates in the following format: around=longitude,latitude,distance - The longitude 
+#'  must given between -180W and 180E and the distance is in kilometers.
+#'  \item Specification 2: The location is the one of an existing profile in the database. 
+#'  It is thus specified with a float WMO and a cycle number: around=wmo,cyc,distance
+#'  This specification can take an optional fourth value specifying the time range in days 
+#'  around the specified profile.
+#' }
+#' 
+#' \code{dmode} parameter definitions:
+#' \itemize{
+#'  \item Data from Argo floats are transmitted from the float, passed through processing and 
+#'  automatic quality control procedures. These profiles have a Data Mode called: real-time data.
+#'  \item The data are also issued to the Principle Investigators who apply other procedures to 
+#'  check data quality returned to the global data centre within 6 to 12 months. These profiles 
+#'  have a Data Mode called: delayed mode data.
+#'  \item The adjustments applied to delayed-data may also be applied to real-time data, to 
+#'  correct sensor drifts for real-time users. These profiles have a Data Mode called: real 
+#'  time data with adjusted values.
+#' }
+#' 
+#' \code{*_qc} parameter definitions:
+#' This information was extracted from the netcdf profile variable PROFILE_<PARAM>_QC. Once 
+#' quality control procedures have been applied, a synthetic flag is assigned for each 
+#' parameter of each profile under this variable in netcdf files. It indicates the fraction 
+#' n of profile levels with good data. It can take one of the following values:
+#' \itemize{
+#'  \item A or F: All (n=100%) or none (n=0%) of the profile levels contain good data,
+#'  \item B,C,D,E: n is in one of the intermediate range: [75-100],[50-75],[25-50] or [0-25] 
+#'  \item empty: No QC was performed.
+#' }