temporalCycleGrid: Temporal cycle calculation

In SantanderMetGroup/transformeR: A climate4R package for general climate data manipulation and transformation

Temporal cycle calculation

Description

A function to compute temporal cycles. See Details.

Usage

temporalCycleGrid(
  grid,
  time.frame = c("daily", "monthly"),
  clim.fun = "mean",
  ...,
  parallel = FALSE,
  max.ncores = 16,
  ncores = NULL
)

Arguments

grid	Input grid. This must be a daily or monthly grid, depending on the next argument choice. See details
time.frame	Character string. Temporal unit on which the cycle is based on. Currently accepted values are "daily" (the default, requires a daily input grid) or monthly
clim.fun	Function used to aggregate the values. Default to mean, but any other can be flexibly defined.
...	Further arguments passed to clim.fun (e.g. na.rm = TRUE, ...)
parallel	Logical. Should parallel execution be used?
max.ncores	Integer. Upper bound for user-defined number of cores.
ncores	Integer number of cores used in parallel computation. Self-selected number of cores is used when ncpus = NULL (the default), or when maxcores exceeds the default ncores value.

Details

This function is intended for the computation of reference daily/monthly climatologies (i.e., a climatological reference for each -julian- day of the year/month). It thus has a maximum temporal length of 365 i.e., one value for each day of the year, in case of grids encompassing an annual season (see next subsection regarding leap years) or 12, in the case of monthly annual cycles.

Leap Years

In case of leap years within the sample, the function groups 29th and 28th Feb as the same day. Thus, the 29th Februaries 'disappear' in the output grid.

Moving average filter

Daily average climatologies are typically calculated after the application of a moving average filter, thus reducing the noise introduced by the large inter-annual variability at this temporal resolution. It is therefore recommended the application of filterGrid (See examples).

Value

A temporal cycle grid

Parallel Processing

Parallel processing is enabled using the parallel package. Parallelization is undertaken by a FORK-type parallel socket cluster formed by ncores. If ncores is not specified (default), ncores will be one less than the autodetected number of cores. The maximum number of cores used for parallel processing can be set with the max.ncores argument, although this will be reset to the auto-detected number of cores minus 1 if this number is exceeded. Note that not all code, but just some critical loops within the function are parallelized.

In practice, parallelization does not always result in smaller execution times, due to the parallel overhead. However, parallel computing may potentially provide a significant speedup for the particular case of large multimember datasets or large grids.

Parallel computing is currently not available for Windows machines.

Author(s)

J Bedia

See Also

filterGrid for the application of moving averages to grids.

Examples

require(climate4R.datasets)
data("EOBS_Iberia_tas")

## DAILY CYCLE (example with winter EOBS mean temperature)
grid <- EOBS_Iberia_tas
Mn <- temporalCycleGrid(grid, time.frame = "daily")
# We compute the areal mean to plot the results as a time-series
aggr.fun <- list(FUN = "mean", na.rm = TRUE)
Mn.agg <- aggregateGrid(Mn, aggr.lon = aggr.fun, aggr.lat = aggr.fun)
plot(Mn.agg$Data, ty = 'l', ylim = c(0,15), axes = FALSE,
     xlab = "month-day", ylab = "Mean Temp (degC)",
     main = "Daily Cycle DJF 1997-2000")
axis(2)
axis(1, at = seq(1,length(Mn.agg$Data),5), las = 2,
     labels = substr(getRefDates(Mn.agg), 6, 10)[seq(1,length(Mn.agg$Data),5)])
# It is possible to apply any other function apart from the default mean. For instance:
# Minimum
mn <- temporalCycleGrid(grid, clim.fun = "min", na.rm = TRUE)
mn.agg <- aggregateGrid(mn, aggr.lon = aggr.fun, aggr.lat = aggr.fun, weight.by.lat = TRUE)
# Maximum
mx <- temporalCycleGrid(grid, clim.fun = "max", na.rm = TRUE)
mx.agg <- aggregateGrid(mx, aggr.lon = aggr.fun, aggr.lat = aggr.fun, weight.by.lat = TRUE)
# Range envelope
ix <- 1:length(Mn.agg$Data)
polygon(x = c(ix, rev(ix)), y = c(mn.agg$Data, rev(mx.agg$Data)),
        border = "transparent", col = rgb(.2,.2,.2,.5))
legend("top", c("Daily mean cycle", "range"),
       pch = 22, pt.bg = c("transparent", "grey60"), pt.cex = c(0,2.5),
       lwd = c(1,0), bty = "n")

## Smoothing daily data
## A moving average window of 1 week is used here to smooth the daily series:
fMn <- filterGrid(Mn, window.width = 7, sides = 2)
fMn.agg <- aggregateGrid(fMn, aggr.lat = aggr.fun, aggr.lon = aggr.fun)
lines(fMn.agg$Data, col = "red")
legend("bottom", "Smoothed daily mean cycle", lty = 1, col = "red", bty = "n")

## ANNUAL CYCLE (time.frame = "monthly")
# A monthly input grid is required.
# An attemp to compute a monthly time cycle with daily data will yield an error:
try(temporalCycleGrid(grid, time.frame = "monthly"))
# Thus, monthly aggregation is required:
mgrid <- aggregateGrid(grid, aggr.m = aggr.fun)
mcyc <- temporalCycleGrid(mgrid, time.frame = "monthly")
# The spatial mean is calculated to plot the time series:
mcyc.agg <- aggregateGrid(mcyc, aggr.lat = aggr.fun, aggr.lon = aggr.fun)
plot(mcyc.agg$Data, ty = 'b', xlab = "Month",  ylab = "Mean Temp (degC)",
     axes = FALSE, main = "Monthly Cycle DJF 1997-2000")
axis(2)
axis(1, at = 1:3, labels = month.abb[c(12,1,2)])
## Also, note the special attributes in $Variable:
# type of cycle:
attributes(mcyc$Variable)$'temporal.cycle::time.frame'
# aggregation function:
attributes(mcyc$Variable)$'temporal.cycle::fun'

SantanderMetGroup/transformeR documentation built on Nov. 25, 2024, 1:25 p.m.