Create or extract Cycle objects

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

Georgi N. Boshnakov

Examples

## pcCycle
pcCycle(4)
#> Object from class 'BareCycle'
#> Number of seasons: 4 
pcCycle(4, seasons = c("Spring", "Summer", "Autumn", "Winter"))
#> Object from class 'SimpleCycle'
#> Number of seasons: 4 
#> Seasons: Spring Summer Autumn Winter 
#> Abbreviated: Spring Summer Autumn Winter 

pcCycle("QuarterYearCycle")
#> Object from built-in class 'QuarterYearCycle'
#> Cycle start: Quarter_1 
BuiltinCycle(4) # same, recommended
#> Object from built-in class 'QuarterYearCycle'
#> Cycle start: Quarter_1 

pcCycle("QuarterYearCycle", type = "BareCycle")
#> Object from class 'BareCycle'
#> Number of seasons: 4 
pcCycle("QuarterYearCycle", type = "SimpleCycle")
#> Object from class 'SimpleCycle'
#> Number of seasons: 4 
#> Seasons: Quarter_1 Quarter_2 Quarter_3 Quarter_4 
#> Abbreviated: Q1 Q2 Q3 Q4 

## BuiltinCycle
BuiltinCycle(2)  # "OpenCloseCycle"
#> Object from built-in class 'OpenCloseCycle'
#> Cycle start: Open 
BuiltinCycle(4)  # "QuarterYearCycle"
#> Object from built-in class 'QuarterYearCycle'
#> Cycle start: Quarter_1 
BuiltinCycle(5)  #  five day week cycle
#> Object from class 'PartialCycle'
#>     partial cycle of 'DayWeekCycle', seasons: 1, 2, 3, 4, 5
#> Cycle start: Monday 
BuiltinCycle(7)  # "DayWeekCycle"
#> Object from built-in class 'DayWeekCycle'
#> Cycle start: Monday 
BuiltinCycle(12) # "MonthYearCycle"
#> Object from built-in class 'MonthYearCycle'
#> Cycle start: January 
BuiltinCycle(48) # "Every30MinutesCycle"
#> Object from built-in class 'Every30MinutesCycle'
#> Cycle start: 00:30 

## 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)
#> Object from class 'BareCycle'
#> Number of seasons: 19 
BuiltinCycle(19, coerce = TRUE, stop = FALSE)
#> Object from class 'SimpleCycle'
#> Number of seasons: 19 
#> Seasons: Season_1 Season_2 Season_3 Season_4 Season_5 Season_6 Season_7 Season_8 Season_9 Season_10 Season_11 Season_12 Season_13 Season_14 Season_15 Season_16 Season_17 Season_18 Season_19 
#> Abbreviated: S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12 S13 S14 S15 S16 S17 S18 S19