dc.topo: Download and Cache a Topographic File
In dankelley/dac: Download and Cache Data

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

Data are downloaded (from https://maps.ngdc.noaa.gov/viewers/wcs-client, by default) and a string containing the full path to the downloaded file is returned. If destfile is not supplied, then the filename is constructed from the query, which means that subsequent calls to dc.topo() with identical parameters will simply return the name of the cached file, assuming the user has not deleted it in the meantime.

dc.topo(
  west,
  east,
  south,
  north,
  resolution,
  format = NULL,
  server,
  destdir = ".",
  destfile,
  force = FALSE,
  dryrun = FALSE,
  debug = getOption("dcDebug", 0)
)

`west, east`	Longitudes of the western and eastern sides of the box.
`south, north`	Latitudes of the southern and northern sides of the box.
`resolution`	Optional grid spacing, in minutes. If not supplied, a default value of 4 (corresponding to 7.4km, or 4 nautical miles) is used. Note that (as of August 2016) the original data are on a 1-minute grid, which limits the possibilities for `resolution`.
`format`	ignored, as of May 30, 2020.
`server`	character value giving the base name of the server, used in the construction of URL queries. Since servers tend to change over time, this is a good argument to check, when debugging code that once worked but now fails.
`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.

The data are downloaded with utils::download.file(), using a URL devised from reverse engineering web-based queries constructed by the default server used here. Note that the data source is "etopo1", which is a 1 arc-second file (ref 1,2).

Three values are permitted for format, each named after the targets of menu items on the NOAA website (as of August 2016): (1) "aaigrid" (for the menu item "ArcGIS ASCII Grid"), which yields a text file, (2) "netcdf" (the default, for the menu item named "NetCDF"), which yields a NetCDF file and (3) "gmt" (for the menu item named "GMT NetCDF"), which yields a NetCDF file in another format. All of these file formats are recognized by oce::read.topo() in the oce package. (The NOAA server has more options, and if oce::read.topo() is extended to handle them, they will also be added here.)

String indicating the full pathname to the downloaded file.

This function has been changed repeatedly over the years, to keep up with changes in server URLs and query strings. Until May 2020, the NOAA server was set up to supply data in netcdf and other formats, but then there was a change to only supply image (tiff) format or JSON format, neither of which is particularly useful for reading in R. To get around this, a scheme used by marmap::getNOAA.bathy() was mimicked here, to convert a TIFF object into a raster object, and then the result was written into a local netcdf file. In this way, dc.topo() is still able to accomplish what it has before May 2020, although it stopped paying attention to the format argument.

Dan Kelley

Dan Kelley 2020-05-30

https://www.ngdc.noaa.gov/mgg/global/global.html
Amante, C. and B.W. Eakins, 2009. ETOPO1 1 Arc-Minute Global Relief Model: Procedures, Data Sources and Analysis. NOAA Technical Memorandum NESDIS NGDC-24. National Geophysical Data Center, NOAA. doi:10.7289/V5C8276M (access date: Aug 30, 2017).

The work is done with utils::download.file().

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

## Not run: 
library(dc)
topoFile <- dc.topo(west=-64, east=-60, south=43, north=46, destdir="~/data/topo")
library(oce)
topo <- read.topo(topoFile)
imagep(topo, zlim=c(-400, 400), drawTriangles=TRUE)
data(coastlineWorldFine, package="ocedata")
lines(coastlineWorldFine[["longitude"]], coastlineWorldFine[["latitude"]])

## End(Not run)

## Not run: 
# not run because it is slow, and downloads files
library(dc)
library(oce)
f <- dc.topo(-70, -50, 35, 50, resolution=2, force=TRUE)
topo <- read.topo(f)
summary(topo)
imagep(topo, colormap(name="gmt_globe"))
## End(Not run)