oce (version 0.9-20)

download.topo: Download and Cache a topo File

Description

Data are downloaded (from http://maps.ngdc.noaa.gov/viewers/wcs-client/, by default) and a string containing the full path to the downloaded file is returned. Typically, this return value is used with read.topo to read the data. Subsequent calls to download.topo with identical parameters will simply return the name of the cached file, assuming the user has not deleted it in the meantime. For convenience, if destfile is not given, then download.topo will construct a filename from the other arguments.

Usage

download.topo(west, east, south, north, resolution, destdir, destfile, format, server, debug = getOption("oceDebug"))

Arguments

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.

destdir

Optional string indicating the directory in which to store downloaded files. If not supplied, "." is used, i.e. the data file is stored in the present working directory.

destfile

Optional string indicating the name of the file. If not supplied, the file name is constructed from the other parameters of the function call, so subsequent calls with the same parameters will yield the same result, thus providing the key to the caching scheme.

format

Optional string indicating the type of file to download. If not supplied, this defaults to "gmt". See “Details”.

server

Optional string indicating the server from which to get the data. If not supplied, the humorously-named default "http://maps.ngdc.noaa.gov/mapviewer-support/wcs-proxy/wcs.groovy" will be used.

debug

an integer specifying whether debugging information is to be printed during the processing. This is a general parameter that is used by many oce functions. Generally, setting debug=0 turns off the printing, while higher values suggest that more information be printed.

Value

String indicating the full pathname to the downloaded file.

Warning

All of the download.* functions are subject to change through the autumn of 2016. The plan is to create individual functions as needs arise in everyday work, thereby discovering patterns of arguments that might make sense more generally. Therefore, it is likely that argument order (and even name) may change up until approximately December 2016. Users are advised to refer to arguments by name, i.e. not to rely on their order, and they are asked for patience, because argument names and defaults may vary through the early development.

Details

The data are downloaded with 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 [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 read.topo. (The NOAA server has more options, and if read.topo is extended to handle them, they will also be added here.)

References

1. http://www.ngdc.noaa.gov/mgg/global/global.html

2. 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 20, 2016].

See Also

The work is done with download.file.

Other functions that download files: download.amsr, download.coastline

Other things related to topo data: [[,topo-method, [[<-,topo-method, as.topo, plot,topo-method, read.topo, subset,topo-method, summary,topo-method, topo-class, topoInterpolate, topoWorld

Examples

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