R: Download and Cache a topo File

download.topo {oce} | R Documentation

## Download and Cache a topo File

### Description

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. 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, rounding longitude and latitude limits to 0.01 degrees.

### 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 default "https://gis.ngdc.noaa.gov/cgi-bin/public/wcs/etopo1.xyz" 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. If one function calls another, it usually reduces the value of `debug` first, so that a user can often obtain deeper debugging by specifying higher `debug` values.

### Details

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 (see references 1 and 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.)

### Value

String indicating the full pathname to the downloaded file.

### Webserver history

All versions of `download.topo` to date have used a NOAA server as the data source, but the URL has not been static. A list of the servers that have been used is provided below, in hopes that it can help users to make guesses for `server`, should `download.topo` fail because of a fail to download the data. Another hint is to look at the source code for `getNOAA.bathy()` in the `marmap` package, which is also forced to track the moving target that is NOAA.

- August 2016. http://maps.ngdc.noaa.gov/mapviewer-support/wcs-proxy/wcs.groovy

- December 2016. http://mapserver.ngdc.noaa.gov/cgi-bin/public/wcs/etopo1.xyz

- June-September 2017. https://gis.ngdc.noaa.gov/cgi-bin/public/wcs/etopo1.xyz

### Author(s)

Dan Kelley

### References

1. `https://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

### See Also

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

Other functions that download files: `download.amsr()`, `download.coastline()`, `download.met()`

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)
    if (requireNamespace("ocedata", quietly=TRUE)) {
        data(coastlineWorldFine, package="ocedata")
        lines(coastlineWorldFine[["longitude"]], coastlineWorldFine[["latitude"]])
    }

    ## End(Not run)

[Package oce version 1.2-0 Index]