CFfactor {CFtime}  R Documentation 
Create a factor from the offsets in an CFtime instance
Description
With this function a factor can be generated for the time series, or a part
thereof, contained in the CFtime
instance. This is specifically interesting
for creating factors from the date part of the time series that aggregate the
time series into longer time periods (such as month) that can then be used to
process daily CF data sets using, for instance, tapply()
.
Usage
CFfactor(cf, period = "month", epoch = NULL)
Arguments
cf 
CFtime. An instance of the 
period 
character. A character string with one of the values "year", "season", "quarter", "month" (the default), "dekad" or "day". 
epoch 
numeric or list, optional. Vector of years for which to
construct the factor, or a list whose elements are each a vector of years.
If 
Details
The factor will respect the calendar of the datum that the time series is
built on. For period
s longer than a day this will result in a factor where
the calendar is no longer relevant (because calendars impacts days, not
dekads, months, quarters, seasons or years).
The factor will be generated in the order of the offsets of the CFtime
instance. While typical CFcompliant data sources use ordered time series
there is, however, no guarantee that the factor is ordered as multiple
CFtime
objects may have been merged out of order.
If the epoch
parameter is specified, either as a vector of years to include
in the factor, or as a list of such vectors, the factor will only consider
those values in the time series that fall within the list of years, inclusive
of boundary values. Other values in the factor will be set to NA
. The years
need not be contiguous, within a single vector or among the list items, or in
order.
The following periods are supported by this function:

year
, the year of each offset is returned as "YYYY". 
season
, the meteorological season of each offset is returned as "Sx", with x being 14, preceeded by "YYYY" if noepoch
is specified. Note that December dates are labeled as belonging to the subsequent year, so the date "20201201" yields "2021S1". This implies that for standard CMIP files having one or more full years of data the first season will have data for the first two months (January and February), while the final season will have only a single month of data (December). 
quarter
, the calendar quarter of each offset is returned as "Qx", with x being 14, preceeded by "YYYY" if noepoch
is specified. 
month
, the month of each offset is returned as "01" to "12", preceeded by "YYYY" if noepoch
is specified. This is the default period. 
dekad
, tenday periods are returned as "Dxx", where xx runs from "01" to "36", preceeded by "YYYY" if noepoch
is specified. Each month is subdivided in dekads as follows: 1 days 01  10; 2 days 11  20; 3 remainder of the month. 
day
, the month and day of each offset are returned as "MMDD", preceeded by "YYYY" if noepoch
is specified.
It is not possible to create a factor for a period that is shorter than the
temporal resolution of the source data set from which the cf
argument
derives. As an example, if the source data set has monthly data, a dekad or
day factor cannot be created.
Creating factors for other periods is not supported by this function. Factors
based on the timestamp information and not dependent on the calendar can
trivially be constructed from the output of the as_timestamp()
function.
For nonepoch factors the attribute 'CFtime' of the result contains a CFtime
instance that is valid for the result of applying the factor to a data set
that the cf
argument is associated with. In other words, if CFtime instance
'Acf' describes the temporal dimension of data set 'A' and a factor 'Af' is
generated from 'Acf', then attr(Af, "CFtime")
describes the temporal
dimension of the result of, say, apply(A, 1:2, tapply, Af, FUN)
. The
'CFtime' attribute is NULL
for epoch factors.
Value
If epoch
is a single vector or not specified, a factor with a
length equal to the number of offsets in cf
. If epoch
is a list, a list
with the same number of elements and names as epoch
, each containing a
factor. Elements in the factor will be set to NA
for time series values
outside of the range of specified years.
The factor, or factors in the list, have attributes 'period', 'epoch' and
'CFtime'. Attribute 'period' holds the value of the period
argument.
Attribute 'epoch' indicates the number of years that are included in the
epoch, or 1 if no epoch
is provided. Attribute 'CFtime' holds an
instance of CFtime that has the same definition as cf
, but with offsets
corresponding to the midpoint of nonepoch factor levels; if the epoch
argument is specified, attribute 'CFtime' is NULL
.
See Also
cut()
creates a nonepoch factor for arbitrary cut points.
Examples
cf < CFtime("days since 19491201", "360_day", 19830:54029)
# Create a dekad factor for the whole time series
f < CFfactor(cf, "dekad")
# Create three monthly factors for early, mid and late 21st century epochs
ep < CFfactor(cf, epoch = list(early = 2021:2040, mid = 2041:2060, late = 2061:2080))