read.msc {seas}

Read a MSC archive file into a data.frame

Description

Reads a Meteorological Service of Canada (MSC) digital archive files (HLY and DLY formats) into a data.frame.

Usage

read.msc(file, flags = FALSE, add.elem, format, verbose = TRUE)

Arguments

file

file name (with path, if not in getwd); it can also be a connection, such as bzfile

flags

logical return the flags with the data.frame

add.elem

either a data.frame or a list with additional elements not found in this function

format

parameter ignored and will be removed in a future release

verbose

logical verbose output, such as number of stations, elements, records and years in the archive file

Details

This function currently reads in HLY (hourly) and DLY (daily) archive formats. This is automatically detected. The other formats, FIF (fifteen-minute) and MLY (monthly), are not currently supported.

The input file can include multiple stations and multiple elements (measured variables). The multiple stations are deciphered through the id column, and the multiple variables appear as columns to the output data frame.

This function currently only reads a limited number of elements, however additional elements can be used by editing two lines in the R source for this function.

Value

Returns a data.frame object with the following minimum fields:

id:

factor used to distinguish multiple stations within a single data frame

year:

integer year

yday:

integer day of year; 1–365 or 1–366

date:

Date, useful for plotting a continuous time-series

datetime:

POSIXct, includes date and time info, only included if file is in HLY archive format

element:

numeric, with attributes set for units and long.name; these can be changed using attr on dat$varname

flag:

factor; included if flags=TRUE

The are as many element columns for each element found in the archive file, such as:

alias	name	long.name	units
1	t_max	daily maximum temperature	°C
2	t_min	daily minimum temperature	°C
3	t_mean	daily mean temperature	°C
10	rain	total rainfall	mm
11	snow	total snowfall	mm
12	precip	total precipitation	mm
13	snow_d	snow on the ground	cm
...	...	other elements	optional

Additional elements (or variables) can be added by specifying the element variable, and their units can be set using, for example, attr(dat$var, "units") <- "cm".

Units are in common metric units: ‘mm’ for precipitation-related measurements, ‘cm’ for snow depth, and ‘?C’ for temperature. The flag columns are a single character factor, described in the MSC Archive documentation. Units are added to each column using, for example attr(dat$precip, "units") <- "mm".

Author(s)

Mike Toews

Source

Climate data can be requested from MSC, or can be obtained directly from the Canadian Daily Climate Data (CDCD) CD-ROMs, which are available for a free download (procedure described in A1128551.DLY).

References

https://web.archive.org/web/20130625230337/http://climate.weatheroffice.gc.ca/prods_servs/documentation_index_e.html (archived) Technical Documentation - Documentation for the Digital Archive of Canadian Climatological Data (Surface) Identified By Element

⁠http://climate.weatheroffice.gc.ca/prods_servs/index_e.html#cdcd⁠ (dead link) CDCD CD-ROM download location

See Also

mscstn, mksub, mkseas, A1128551.DLY

Examples

fname <- system.file("extdata", "A1128551.DLY", package="seas")
print(fname)
dat <- read.msc(fname)
print(head(dat))

seas.temp.plot(dat)
year.plot(dat)

# Show how to convert from daily to monthly data
dat$yearmonth <- factor(paste(format(dat$date, "%Y-%m"), 15, sep="-"))
mlydat <- data.frame(date=as.Date(levels(dat$yearmonth)))
mlydat$year <- factor(format(mlydat$date, "%Y"))
mlydat$month <- mkseas(mlydat, "mon")

# means for temperature data
mlydat$t_max <- as.numeric(
    tapply(dat$t_max, dat$yearmonth, mean, na.rm=TRUE))
mlydat$t_min <- as.numeric(
    tapply(dat$t_min, dat$yearmonth, mean, na.rm=TRUE))
mlydat$t_mean <- as.numeric(
    tapply(dat$t_mean, dat$yearmonth, mean, na.rm=TRUE))

# sums for precipitation-related data
mlydat$rain <- as.numeric(
    tapply(dat$rain, dat$yearmonth, sum, na.rm=TRUE))
mlydat$snow <- as.numeric(
    tapply(dat$snow, dat$yearmonth, sum, na.rm=TRUE))
mlydat$precip <- as.numeric(
    tapply(dat$precip, dat$yearmonth, sum, na.rm=TRUE))
print(head(mlydat), 12)

# Show how to convert from a HLY file into daily summaries
## Not run: 
hlydat <- read.msc(bzfile("HLY11_L1127800.bz2"), flags=TRUE)
hlydat$date <- factor(hlydat$date)

# sum the solar radiation for each day to find the 'total daily'
sumdat <- tapply(hlydat$solar, hlydat$date, sum, na.rm=TRUE)
dlydat <- data.frame(date=as.Date(names(sumdat)),
                     solar=as.numeric(sumdat))

# sum the number of hours without measurements
sumdat <- tapply(hlydat$solar, hlydat$date,
                 function(v)(24 - sum(!is.na(v))))
dlydat$na <- as.integer(sumdat)

# quality control to remove days with less than 4 hours missing
Summerland <- dlydat[dlydat$na < 4,]

attr(Summerland$solar, "units") <- "W/(m^2*day)"
attr(Summerland$solar, "long.name") <- "Daily total global solar radiation"
seas.var.plot(Summerland, var="solar", col="yellow", width=5)

## End(Not run)