dc.woa: Download and Cache a World Ocean Atlas File

In dankelley/dac: Download and Cache Data

Description

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).

Usage

dc.woa(
  database = "woa13",
  version = NULL,
  time = NULL,
  resolution = 1,
  field = "temperature",
  destdir = ".",
  destfile,
  force = FALSE,
  dryrun = FALSE,
  debug = getOption("dcDebug", 0)
)

Arguments

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.
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.
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.
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.
field	String indicating the variable. This must be one of the following: "temperature", "temperature", "salinity", "density", "oxygen", "phosphate", "nitrate" or "silicate".
destdir	character value indicating the directory in which to store downloaded files. The default value of "." means to store the downloaded file in the present working directory. Set destdir=NULL if destfile is a filename with full path information. File clutter is reduced by creating a top-level directory called data, with subdirectories for various file types; see “Examples”.
destfile	character value indicating the name of the file. If not supplied, then the file name is constructed from the other parameters of the function call, so that subsequent calls with the same parameters will yield the same result; this is useful for caching.
force	A logical value that indicates whether to force the download, even if the pathname constructed from destdir and destfile already exists.
dryrun	A logical value that indicates whether to return the constructed web query, without attempting to download the file. This can be helpful in designing responses to changing URLs.
debug	an integer specifying whether debugging information is to be printed during processing. The printing is done by a call to dcDebug(). Setting debug=0 turns off this form of debugging, while higher values yield more information. If one dc function calls another, it passes the value of debug but decreased by 1, which means that the value of debug controls not just the breadth of debugging, but also the depth.

Value

String indicating the full pathname to the downloaded file.

Author(s)

Dan Kelley (2017-09-22)

References

1. https://www.nodc.noaa.gov/OC5/woa13/woa13data.html

2. https://www.nodc.noaa.gov/OC5/woa13

See Also

The work is done with dc().

Other functions that download ocean-related data: dc.coastline(), dc.g1sst(), dc.hydrography(), dc.met(), dc.topo()

Examples

library(dc)
## Not run: 
## 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)

## End(Not run)

dankelley/dac documentation built on June 4, 2020, 11:45 p.m.