#' Download and Cache a World Ocean Atlas File
#'
#' The data are downloaded with [utils::download.file()]
#' pointed to links inferred by tracing a NOAA website (ref 1) through a series
#' of links down to a THREDDS server and finally to an HTTPServer. At the
#' moment, there is no choice on which version of the database is used: it is
#' WOA13 for all variables except salinity and temperature, and in these latter
#' two, it is WOA13V2, which is said to be an improvement over the initial
#' release (ref 2).
#'
#' @param database String indicating the name of the database. This must be
#' `"woa13"` in this version, but other databases can be added if users
#' need them.
#' @param version String indicating the version of the atlas. This is
#' ignored in this version, but a future version could allow specification
#' of either the original or the version-2 data.
#' @param time String indicating the time. This is ignored in this version,
#' but a future version could allow division into months for some fields
#' and decades for others.
#' @param resolution Number indicating the resolution, in degrees
#' of longitude and latitude. The permitted values are 0.25, 1
#' and 5. The downloaded files are of typical size 634 Mb, 177 Mb
#' and 4.1 Mb, respectively. The 1-deg resolution is a good
#' choice for global-scale applications.
#' @param field String indicating the variable. This must be one of
#' the following: `"temperature"`, `"temperature"`,
#' `"salinity"`, `"density"`, `"oxygen"`,
#' `"phosphate"`, `"nitrate"` or `"silicate"`.
#' @template destdir
#' @template destfile
#' @template force
#' @template dryrun
#' @template debug
#'
#' @return String indicating the full pathname to the downloaded file.
#'
#' @examples
#' library(dc)
#'\dontrun{
#' ## Example 1: download and plot 1-deg grid (177 Mb file)
#' ## Download Levitus 2013 (Version 2) temperature on a 1-degree grid,
#' ## in netcdf format, then read the data, and finally, plot sea-surface
#' ## temperature using oce::imagep() to get an image with a palette.
#' T1f <- dc.woa(field="temperature", destdir="~/data/woa")
#' library(ncdf4)
#' T1nc <- nc_open(T1f) # or nc_open("woa13_decav_t00_01v2.nc")
#' lon1 <- ncvar_get(T1nc, "lon")
#' lat1 <- ncvar_get(T1nc, "lat")
#' T1 <- ncvar_get(T1nc, "t_an")
#' library(oce)
#' imagep(lon1, lat1, T1[,,1])
#'
#' ## Example 2: download and plot 5-deg grid (4.1 Mb file)
#' ## Note that the variable 't_an' used above must be switched
#' ## to 't_mn' here. Also, a point of confusion: the metadata
#' ## in the downloaded file say that t_an is 4D, with the
#' ## extra dimension being time, but the time vector in the file
#' ## is of unit length, so ncdf4 appraently demotes it to 3D.
#' T5f <- dc.woa(field="temperature", resolution=5, destdir="~/data/woa")
#' T5nc <- nc_open(T5f)
#' lon5 <- ncvar_get(T5nc, "lon")
#' lat5 <- ncvar_get(T5nc, "lat")
#' T5 <- ncvar_get(T5nc, "t_mn")
#' library(oce)
#' imagep(lon5, lat5, T5[,,1])
#'
#' ## Example 3: download all fields on default 1-deg grid
#' for (field in c("temperature", "salinity", "oxygen", "silicate",
#' "phosphate", "nitrate", "density"))
#' dc.woa(field=field)
#'}
#'
#' @seealso The work is done with [dc()].
#'
#' @references
#' 1. \url{https://www.nodc.noaa.gov/OC5/woa13/woa13data.html}
#'
#' 2. \url{https://www.nodc.noaa.gov/OC5/woa13}
#'
#' @author Dan Kelley (2017-09-22)
#'
#' @family functions that download ocean-related data
#' @export
dc.woa <- function(database="woa13",
version=NULL, time=NULL, resolution=1, field="temperature",
destdir=".", destfile, force=FALSE, dryrun=FALSE,
debug=getOption("dcDebug", 0))
{
if (database != "woa13")
stop("database must equal \"woa13\"")
if (!is.null(time))
stop("time must be NULL")
## set up resolution nicknames (used in the query) and also ensure
## resolution is in permitted list
if (0.01 > abs(resolution - 0.25)) {
rn1 <- "0.25"
rn2 <- "04"
} else if (0.01 > abs(resolution - 1)) {
rn1 <- "1.00"
rn2 <- "01"
} else if (0.01 > abs(resolution - 5)) {
rn1 <- "5deg"
rn2 <- "5d"
} else {
stop("resolution must equal 0.25, 1, or 5, but it is ", resolution)
}
## Expand field, if abbreviated.
fieldAllowed <- c("temperature", "salinity", "density",
"oxygen", "phosphate", "nitrate", "silicate")
fnumber <- pmatch(field, fieldAllowed)
if (is.na(fnumber))
stop("field '", field, "' is not understood; use one of: ", paste(fieldAllowed, collapse=" "))
field <- fieldAllowed[fnumber]
URLv2 <- "https://data.nodc.noaa.gov/thredds/fileServer/woa/WOA13/DATAv2"
URL <- "https://data.nodc.noaa.gov/thredds/fileServer/woa/WOA13/DATA"
## https://data.nodc.noaa.gov/thredds/fileServer/woa/WOA13/DATAv2/temperature/netcdf/decav/0.25/woa13_decav_t00_04v2.nc
## https://data.nodc.noaa.gov/thredds/fileServer/woa/WOA13/DATAv2/temperature/netcdf/decav/1.00/woa13_decav_t00_01v2.nc
## https://data.nodc.noaa.gov/thredds/fileServer/woa/WOA13/DATAv2/temperature/netcdf/decav/5deg/woa13_decav_t00_5dv2.nc
if (field == "temperature" || field == "salinity") {
fn <- if (field == "temperature") "t" else "s"
url <- paste(URLv2, "/", field, "/netcdf/decav/", rn1, "/woa13_decav_", fn, "00_", rn2, "v2.nc", sep="")
destfile <- paste("woa13_decav_", fn, "00_", rn2, "v2.nc", sep="")
} else if (field == "oxygen") {
url <- paste(URL, "/", field, "/netcdf/all/", rn1, "/woa13_all_o00_", rn2, ".nc", sep="")
destfile <- paste("woa13_all_o00_", rn2, ".nc", sep="")
} else if (field == "silicate") {
url <- paste(URL, "/", field, "/netcdf/all/", rn1, "/woa13_all_i00_", rn2, ".nc", sep="")
destfile <- paste("woa13_all_i00_", rn2, ".nc", sep="")
} else if (field == "phosphate") {
url <- paste(URL, "/", field, "/netcdf/all/", rn1, "/woa13_all_p00_", rn2, ".nc", sep="")
destfile <- paste("woa13_all_p00_", rn2, ".nc", sep="")
} else if (field == "nitrate") {
url <- paste(URL, "/", field, "/netcdf/all/", rn1, "/woa13_all_n00_", rn2, ".nc", sep="")
destfile <- paste("woa13_all_n00_", rn2, ".nc", sep="")
} else if (field == "density") {
## https://data.nodc.noaa.gov/thredds/fileServer/woa/WOA13/DATAv2/density/netcdf/decav/1.00/woa13_decav_I00_01.nc
url <- paste(URLv2, "/", field, "/netcdf/decav/", rn1, "/woa13_decav_I00_", rn2, ".nc", sep="")
destfile <- paste("woa13_decav_I00_", rn2, ".nc", sep="")
} else {
stop("unknown field, \"", field, "\"") # we cannot reach this point, but keep it in case of code changes
}
rval <- dc(url=url, destdir=destdir, destfile=destfile, dryrun=dryrun, force=force, debug=debug-1)
dcDebug(debug, "} # dc.woa", sep="", "\n", unindent=1)
rval
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.