Download meteorological timeseries data

dod.met() attempts to download data from Environment Canada's historical-data website, and to cache the files locally. Lacking a published API, this function must rely on reverse-engineering of queries handled by that web server. For that reason, it is brittle.

Usage

dod.met(
  id,
  year,
  month,
  deltat,
  type = "xml",
  destdir = ".",
  age = 1,
  debug = 0
)

Arguments

id: A number giving the "Station ID" of the station of interest. If not provided, id defaults to 43405, for Halifax Dockyard. (Previously, the default was 6358, for Halifax International Airport, but in March 2024 it was noticed that 6358 held no data.) 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. As a special case, if neither year nor month is given, and it is the first day of the month, dod.met() goes back one month, to avoid returning a file with no data.
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: a character value indicating the directory in which to store downloaded files.
age: a numerical value indicating a time interval, in days. If the file to be downloaded from the server already exists locally, and was created less than age days in the past, it will not be downloaded again. Setting age=0 forces a download, so that existing files will always be updated. By contrast, setting age to a negative number prevents the updating of files that already exist locally, regardless of their age.
debug: an integer value indicating the level of debugging. If this exceeds 0, then some debugging messages will be printed. This value is passed down to related functions, but with 1 subtracted for each pass.

Value

dod.met() returns a character value holding the full pathname of the downloaded file.

Details

If this function fails, users might try using Gavin Simpson's canadaHCD package (reference 2). That 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() in the oce package, although doing so leaves many important metadata blank.

References

Environment Canada website for Historical Climate Data https://climate.weather.gc.ca/index_e.html
Gavin Simpson's canadaHCD package on GitHub https://github.com/gavinsimpson/canadaHCD

Author

Dan Kelley

Examples

# Meteorological data for Halifax, Nova Scotia.
if (interactive()) { # sidestep a pkgdown::build_site() error
    # NOTE: data file is removed at end, to pass CRAN checks
    library(dod)
    destdir <- tempdir()
    metFile <- dod.met(43405, destdir = destdir, debug = 1)
    if (requireNamespace("oce", quietly = TRUE) &&
        requireNamespace("XML", quietly = TRUE)) {
        library(oce)
        met <- read.met(metFile)
        t <- met[["time"]]
        p <- met[["pressure"]]
        oce.plot.ts(t, p, ylab = "Atm. Pressure [Pa]")
    }
    unlink(destdir, recursive = TRUE)
}