pcCycle-methods {pcts}

Create or extract Cycle objects

Description

pcCycle() is a generic function with methods for creating, converting, modifying, and extracting cycle objects. BuiltinCycle() is a function to create cycle objects from the builtin cycle classes.

Usage

pcCycle(x, type, ...)

BuiltinCycle(n, coerce = FALSE, first = 1, stop = TRUE)

Arguments

x

an object, methods include numeric, character and cyclic objects, see Details.

type

class of the result. If equal to "auto", the default, the class is determined by the argument(s), otherwise should be the name of a cycle class.

...

further arguments for methods.

n

number of seasons, an integer.

coerce

if TRUE coerce the objects to a modifiable cycle class, currently "SimpleCycle".

first

which season is first for this object.

stop

if TRUE, the default, throw error if there is no builtin class with n seasons, otherwise create a "BareCycle" object.

Details

pcCycle serves as both a constructor and extractor of cycle objects. It is meant to just do the right thing, relieving the user from the burden of specifying a particular cycle class.

If x is numeric it constructs a cycle object with period x and additional properties as specified by the other arguments. If x is a character string, it is taken to be the name of one of the builtin cycles.

pcCycle can be used to create a modified version of a cycle object and/or convert it to another cycle type. This is done by providing a cycle object as argument x, i.e. one inheriting from "BasicCycle".

If x inherits from "Cyclic", pcCycle returns its cycle component.

Argument type should be rarely needed, except maybe to conveniently force conversion of the builtin type to an ordinary type.

The descriptions of the individual methods in section Methods give some further specific details.

BuiltinCycle is a convenience function to create objects from builtin cycle classes by specifying the number of seasons. The builtin cycle classes are esseintially fixed, except that which season is considered first can be changed using argument first. If other modifications are desired, convert the returned builtin cycle object to class "SimpleCycle". This can be done also in the call to BuiltinCycle() by specifying coerce = TRUE.

By default, BuiltinCycle throws an error if there is no builtin class with the requested number of seasons. Set argument stop to FALSE to create an object from class "BareCycle" instead (and it will be converted to "SimpleCycle" if coerce = TRUE). Argument stop is mainly for programming.

Value

for pcCycle, an object from one of the cycle classes;

for BuiltinCycle, an object from one of the builtin classes, coerced if requested.

Methods

signature(x = "numeric", type = "missing")

creates a cycle object with period x. If x is the only argument, a "BareCycle" object is created, otherwise the constructor of "SimpleCycle" is invoked with all arguments except type passed on to it.

signature(x = "character", type = "missing")

creates an object from the class specified by x. Currently this is equivalent to new(x, ...) but somewhat more portable. Future amendments may use a more suitable class for some combinations of the arguments. Also, if a class is renamed, a code will be inserted here to create an equivalent object.

signature(x = "numeric", type = "character")

signature(x = "character", type = "character")

first call the method with type = "missing", then convert the result to class type.

signature(x = "Cyclic", type = "ANY")

extracts the cycle component of x (x@cycle). Currently ignores the remaining arguments.

signature(x = "BasicCycle", type = "missing")

convert an object from any cycle class to class "SimpleCycle". This is like as(x, "SimpleCycle") but can have further arguments.

signature(x = "BasicCycle", type = "character")

convert an object from any cycle class to class type.

signature(x = "ts", type = "missing")

signature(x = "ts", type = "character")

when x is of class "ts", extract the frequency and convert it to a cycle class. Just as for "ts", certain frequencies are taken to correspond to specific classes. While base R treats periodicities 4 and 12 specially, pcCycle extends this to all builtin classes in pcts. Argument type can be used to overwrite this default behaviour by requesting a specific class. In particular, type = "BareCycle" and type = "" cause the result to be "BareCycle".

signature(x = "PeriodicTimeSeries", type = "missing")

signature(x = "PeriodicTimeSeries", type = "character")

extract the cycle part of an object inheriting from "PeriodicTimeSeries", currently "PeriodicTS" or "PeriodicMTS". Argument type can be used to force the result to be from a specific cycle class, as in the methods for "ts".

Author(s)

Georgi N. Boshnakov

See Also

allSeasons for further examples,

class BuiltinCycle for the available builtin classes and more examples,

Pctime for representation of dates and conversion from/to datetime objects

Examples

## pcCycle
pcCycle(4)
pcCycle(4, seasons = c("Spring", "Summer", "Autumn", "Winter"))

pcCycle("QuarterYearCycle")
BuiltinCycle(4) # same, recommended

pcCycle("QuarterYearCycle", type = "BareCycle")
pcCycle("QuarterYearCycle", type = "SimpleCycle")

## BuiltinCycle
BuiltinCycle(2)  # "OpenCloseCycle"
BuiltinCycle(4)  # "QuarterYearCycle"
BuiltinCycle(5)  #  five day week cycle
BuiltinCycle(7)  # "DayWeekCycle"
BuiltinCycle(12) # "MonthYearCycle"
BuiltinCycle(48) # "Every30MinutesCycle"

## error, since there is no builtin cycle with 19 seasons:
## BuiltinCycle(19)

## use stop = FALSE to reate a default cycle in this case
BuiltinCycle(19, stop = FALSE)
BuiltinCycle(19, coerce = TRUE, stop = FALSE)