seas.sum {seas}

Seasonal sum data object

Description

Create a seasonal sum object used for analysis of precipitation data (among other things, such as recharge rates); this object has sums in each ‘bin’ of a season, as well as for each annum (or year).

Usage

seas.sum(x, var, width = 11, start.day = 1, prime,
         a.cut = 0.3, na.cut = 0.2)

Arguments

x

a data.frame with daily variables to be summed, such as precipitation

var

the names of one or more variables in x, such as c("rain","snow","precip")

width

a number specifying the width of the bin (factor) in days, or "mon" for months (see mkseas for others)

start.day

the first day of the season, specified as either a Date or as an integer day of the year; annual sums start on this day, and end a day before start.day in the following year

prime

a single variable from var which is the prime variable of interest, such as "precip"; this is the variable used for comparison with a.cut and na.cut in the resulting active and na dimensions

a.cut

cut-off value for the day to be considered an active or ‘wet day’ (based on the prime variable); a trace amount of 0.3 mm is suggested; if a.cut is NA or zero, the active variable and analysis will be ignored

na.cut

cut-off fraction of missing values; can be single value or a vector for c(annual,seasonal); details given below

Details

This function is used to discretize and sum time-varying data in a data.frame for analysis in seasonal and annual parts. This is particularly useful for calculating normals of rates, such as precipitation and recharge. This function simply sums up each variable in each bin for each annum (or year), and provides the results in several arrays.

Sums are not normalized, and represent a sum for the number of days in the bin (seasonal data) or annum (for annual data). Seasonal data can be normalized by the number of days (for a rate per day) or by the number of active days where prime > a.cut.

For annual sums, annums with many missing values are ignored (receiving a value of NA) since it has insufficient data for a complete sum. The amount of allowable NA values per annum is controlled by na.cut[1], which is a fraction of NA values for the whole annum (default is 0.2).

The seasonal sums are calculated independently from the annual sums. Individual bins from each year with many missing values are ignored, where the amount of allowable NA values is controlled by na.cut[2] (or na.cut[1], if the length of na.cut is 1). The default fraction of NAs in each bin of each annum is 0.2.

Value

Returns a seas.sum object, which is a list with the following elements:

ann:

A data.frame of annual data; the columns are:

year:

year, or annum

active:

the number of ‘active’ days in the year where the prime variable is above a.cut (if used)

days:

number of days in each year

na:

number of missing days in the year

var(s):

annual sum of one or more variable; if the original units were mm/day, they are now mm/year

seas:

An array: of seasonal data; the dimensions are:

[[1]]:

year, or annum

[[2]]:

bins, or seasonal factors generated by mkseas

[[3]]:

sums of variables for each bin of each year; if the original unit was mm/day, it is now mm per number of days, which is held in the days item

active:

the number of ‘active’ days in the bin where the prime variable is above a.cut (if used)

days:

an array of the number of days in each bin; this array is useful for normalizing the numbers in seas to comparable units of mm/day

na:

number of missing days in each bin

start.day:

same as input

years:

years (same as ann[[1]] and seas[[1]]); if start.day is not 1, this represents the starting and ending years (i.e., 1991_1992) of each annum; see mkann

var:

variable(s) which the sums represent (part of ann[[2]] and seas[[3]])

units:

a list of units for each var, such as “mm/day”; these are obtained from the units attribute (using attr) found in x$var

long.name:

a list of long names for each var; these are obtained from long.name in x$var; set to be var if NULL

prime:

a prime variable, such as "precip"

width:

width argument passed to mkseas

bins:

names of bins returned by mkseas (same as seas[[2]])

bin.lengths:

the maximum length in days for each bin

year.range:

range of years from x

precip.only:

value used in argument (modified if insufficient data found in x)

na.cut:

value used in argument

a.cut:

value used in argument; if it is zero or NA, this will be FALSE

id:

from attr(x,"id") (NULL if not set)

name:

from attr(x,"name") (NULL if not set)

Author(s)

Mike Toews

See Also

To view the result try image.seas.sum, or alternatively, plot.seas.sum

To calculate and view a “normal”, use seas.norm and plot.seas.norm, or for precipitation use precip.norm and plot.precip.norm

Examples

data(mscdata)
dat <- mksub(mscdata, id=1108447)
dat.ss <- seas.sum(dat, width="mon")

# Structure in R
str(dat.ss)

# Annual data
dat.ss$ann

# Demonstrate how to slice through a cubic array
dat.ss$seas["1990",,]
dat.ss$seas[,2,] # or "Feb", if using English locale
dat.ss$seas[,,"precip"]

# Simple calculation on an array
(monthly.mean <- apply(dat.ss$seas[,,"precip"], 2, mean,na.rm=TRUE))
barplot(monthly.mean, ylab="Mean monthly total (mm/month)",
	main="Un-normalized mean precipitation in Vancouver, BC")
text(6.5, 150, paste("Un-normalized rates given 'per month' should be",
	"avoided since ~3-9% error is introduced",
	"to the analysis between months", sep="\n"))

# Normalized precip
norm.monthly <- dat.ss$seas[,,"precip"] / dat.ss$days
norm.monthly.mean <- apply(norm.monthly, 2, mean,na.rm=TRUE)
print(round(norm.monthly, 2))
print(round(norm.monthly.mean, 2))
barplot(norm.monthly.mean,
    ylab="Normalized mean monthly total (mm/day)",
	main="Normalized mean precipitation in Vancouver, BC")

# Better graphics of data
dat.ss <- seas.sum(dat, width=11)
image(dat.ss)