dc.met: Download and Cache a Meteorology File

In dankelley/dac: Download and Cache Data

Description

The data are downloaded with utils::download.file() pointed to the Environment Canada website (ref 1) using queries that had to be devised by reverse-engineering, since the agency does not provide documentation about how to construct queries. Caution: the query format changes from time to time, so dc.met() may work one day, and fail the next.

Usage

dc.met(
  id,
  year,
  month,
  deltat = "hour",
  destdir = ".",
  destfile,
  force = FALSE,
  dryrun = FALSE,
  debug = getOption("dcDebug", 0)
)

Arguments

id	A number giving the "Station ID" of the station of interest.
year	A number giving the year of interest. Ignored unless deltat is "hour". If year is not given, it defaults to the present year.
month	A number giving the month of interest. Ignored unless deltat is "hour". If month is not given, it defaults to the present month.
deltat	Optional character string indicating the time step of the desired dataset. Only "hour" or "month" are permitted. If deltat is not given, it defaults to "hour".
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.

Details

The constructed query contains Station ID, as provided in the id argument. Note that this seems to be a creation of Environment Canada, alone; it is distinct from the more standard "Climate ID" and "WMO ID". To make things more difficult, Environment Canada states that the Station ID is subject to change over time. (Whether this applies to existing data is unclear.)

Given these difficulties with Station ID, users are advised to consult the Environment Canada website (ref 1) before downloading any data, and to check it from time to time during the course of a research project, to see if the Station ID has changed. It can be very helpful to use Gavin Simpson's canadaHCD package (ref 2) to look up Station IDs. This package maintains a copy of the Environment Canada listing of stations, and its find_station function provides an easy way to determine Station IDs. After that, its hcd_hourly function (and related functions) make it easy to read data.

Value

String indicating the full pathname to the downloaded file.

Author(s)

Dan Kelley

Dan Kelley 2017-09-16

References

1. Environment Canada website for Historical Climate Data http://climate.weather.gc.ca/index_e.html

2. Gavin Simpson's canadaHCD package on GitHub https://github.com/gavinsimpson/canadaHCD

See Also

The work is done with dc().

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

Examples

## Not run: 
## Download data for Halifax International Airport, in September
## of 2003. (This dataset is used for data(met) in the oce package.)
library(dc)
metFile <- dc.met(6358, 2003, 9, destdir="~/data/met")
library(oce)
met <- read.met(metFile)
plot(met)

## End(Not run)

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