R: Download and Cache a met File

download.met {oce} | R Documentation

## Download and Cache a met File

### Description

Data are downloaded from the Environment Canada's historical data website and cached locally.

### Usage

    download.met(
      id,
      year,
      month,
      deltat,
      type = "xml",
      destdir = ".",
      destfile,
      force = FALSE,
      quiet = FALSE,
      debug = getOption("oceDebug")
    )

### Arguments

`id` | A number giving the "Station ID" of the station of interest. If not provided, `id` defaults to 6358, for Halifax International Airport. See “Details”.
`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. This may be `"hour"` or `"month"`. If `deltat` is not given, it defaults to `"hour"`.
`type` | String indicating which type of file to download, either `"xml"` (the default) for an XML file or `"csv"` for a CSV file.
`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.
`force` | Logical value indicating whether to force a download, even if the file already exists locally.
`quiet` | Logical value passed to `download.file()`; a `TRUE` value silences output.
`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 using `utils::download.file()` based on a query devised by reverse-engineering queries create by the Environment Canada interface `https://climate.weather.gc.ca/historical_data/search_historic_data_e.html`. 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 (reference 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. Another approach would be to use Gavin Simpson's `canadaHCD` package (reference 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. These data can then be converted to the `met` class with `as.met()`, although doing so leaves many important metadata blank.

### Value

String indicating the full pathname to the downloaded file.

### Author(s)

Dan Kelley

### References

1. Environment Canada website for Historical Climate Data `https://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 `utils::download.file()`.

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

Other things related to met data: `[[,met-method`, `[[<-,met-method`, `as.met()`, `met-class`, `met`, `plot,met-method`, `read.met()`, `subset,met-method`, `summary,met-method`, `test_met_csv1.csv`, `test_met_csv2.csv`, `test_met_xml2.xml`

### Examples

    ## Not run:
    library(oce)
    ## Download data for Halifax International Airport, in September
    ## of 2003. (This dataset is used for data(met) provided with oce.)
    metFile <- download.met(6358, 2003, 9, destdir=".")
    met <- read.met(metFile)

    ## End(Not run)

[Package oce version 1.7-2 Index]