seas (version 0.2-1)

seas.sum: Seasonal sum data object

Description

Create a seasonal sum object used for analysis of precipitation data (among other things, such as recharge rates).

Usage

# minimum usage
seas.sum(x)
# all options
seas.sum(x, start, end, width = 11, var, prime, a.cut = 0.3, 
     na.cut = 0.2, unit = "mm", id, name)

Arguments

x

time-varying data.frame with variables which are summed, such as precipitation

start

start year; if omitted minimum year will be used

end

end year; if omitted will use same as start, and if start is omitted, will use maximum year

width

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

var

a character array of the names from x that are to be summed, such as c("rain","snow","precip"), if available

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 <

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

na.cut

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

unit

unit for seas.sum object; useful for future plotting

id

unique station identifier used to extract a subset of data from dat

name

provide a name for the seasonal sum object; otherwise generated from id (if available)

Value

• Returns a seas.sum object, which is a list with the following elements:
• ann
  data.frame of annual data; the columns are: year{year} active{the number of active days in the year where the prime variable is above a.cut (if used)} days{number of days in the year} na{number of missing days in the year} 1 or more variables{annual sum of each variable; if the original units were mm/day, they are now mm/year}
• seas
  array of seasonal data; the dimensions are: [[1]]{years} [[2]]{bins, or seasonal factors generated by mkfact} [[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
  number of days in the 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
• call
  function call
• years
  years (same as ann[[1]] and seas[[1]])
• var
  variables which the sums represent (part of ann[[2]] and seas[[3]])
• prime
  prime variable
• unit
  unit of variable
• width
  width argument passed to mkfact bins{names of bins returned by mkfact (same as seas[[2]])}
• precip.only
  value used in argument (modified if insufficient data found in dat)
• na.cut
  value used in argument
• a.cut
  value used in argument; if it is zero or NA, this will be FALSE
• id
  value used in argument; or found in dat$id if present and not given as argument
• name
  either given by name argument or generated from id or from dat object name

synopsis

seas.sum(x, start, end, width = 11, var, prime, a.cut = 0.3, na.cut = 0.2, unit = "mm", id, name)

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 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 year (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, years 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 is controlled by na.cut, which is a fraction of NA values for the whole year (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 (fraction of NAs in each bin of each individual year; default is 0.2).

See Also

image.seas.sum to view the result result, seas.norm to view a normal

Examples

loc <- Sys.getlocale()
on.exit(Sys.setlocale(locale=loc))
Sys.setlocale(loc="C")
data(mscstn)
data(mscdata)

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

# Annual data
dat.ss$ann

# Demonstrate how to slice through a cubic array
dat.ss$seas["1990",,]
dat.ss$seas[,"Feb",] # month names are locale specific
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=""))

# 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(mscdata,id=1108447)
image(dat.ss)