Pctime {pcts}

Convert between Pctime and datetime objects

Description

Class "Pctime" is an S3 class inheriting from the base R datetime class "POSIXct". It has methods for conversion between datetimes and the pcts cycle-season pairs, as well as convenience methods for a few other functions.

Usage

Pctime(x, cycle, ...)

as_Pctime(x, ...)

## S3 method for class 'Pctime'
x[i, j, drop = TRUE]

## S3 method for class 'Pctime'
x[[..., drop = TRUE]]

## S3 method for class 'Cyclic'
as_Pctime(x, ...)

Arguments

x

for Pctime, numeric vector, matrix with two columns, or any object that is or can be converted to datetime. For the other functions see Details.

cycle

a positive integer, cycle object, or missing.

i

subscript

j

noi used

drop

not used

...

further argument for methods.

Details

Pctime represents periodic times with cycle specification contained in attribute "cycle". It is basically datetime (inheriting from "POSIXct") with additional attribute(s).

For printing Pctime objects are shown as cycle-season pairs. To print in other formats, just convert them using as_datetime or other suitable function. Note though that some cycles in pcts do not have natural datetime representation. For them, Pctime sets it arbitrarilly as the number of seconds from a origin.

The seasons in cycle-season pairs are numbered from one to the number of seasons. Names and abbreviations are used when available and this is the case for all builtin cycles and partial cycles obtained from them.

The cycles in cycle-season pairs are numbered from a starting point. For years, it is what is expected. For cycles representing weeks, week 1 is the first ISO week of 1970, so c(1,1) corresponds to 1969-12-29. For some other cycle classes c(1,1) also corresponds to the first time in the first ISO week of 1970.

Subsetting with "[" keeps the Pctime class, while "[[" returns a datetime object. Other standard functions work with Pctime objects, as well, including seq.

A common source of frustration is the accidental use of as.Date or as_date, instead of as.POSIXlt or as_datetime. These four are often equivalent, most notably for monthly, quarterly and daily observations but, in general, conversion to dates drops the fractional day part of a datetime.

The default time zone is UTC. Other time zones can be used since the calculations use standard datetime and date functions from base R and package lubridate (Grolemund and Wickham 2011), but currently this has not been tested.

Value

for Pctime, an object from S3 class Pctime

References

Grolemund G, Wickham H (2011). “Dates and Times Made Easy with lubridate.” Journal of Statistical Software, 40(3), 1–25. doi:10.18637/jss.v040.i03.

Examples

## a bare bone date for four seasons
pct4 <- Pctime(c(2020, 2), pcCycle(4))
pct4

## quarterly cycle
Pctime("2020-04-01", BuiltinCycle(4))
pctQ <- Pctime(c(2020, 2), BuiltinCycle(4))  # same
pctQ

## day-in-week cycle
## c(1, 1) is the start of the first ISO week of 1970
weekW1S1 <- Pctime(c(1, 1), BuiltinCycle(7))  # W1 Mon
weekW1S1
as_datetime(weekW1S1)

Pctime("1970-01-01", BuiltinCycle(7)) #  W1 Thu
pctW1Th <- Pctime(c(1, 4), BuiltinCycle(7))  # same
pctW1Th

Pctime("2020-04-01", BuiltinCycle(7))
pctW2623Wed <- Pctime(c(2623, 3), BuiltinCycle(7))  # same
pctW2623Wed
as_datetime(pctW2623Wed)

## Monday-Friday week - a partial cycle derived from DayOfWeekCycle
BuiltinCycle(5)
pctMF <- Pctime("2020-04-03", BuiltinCycle(5)) # Fri
seq(pctMF, length.out = 10) # note: Sat, Sun are skipped

Pctime("2020-04-04", BuiltinCycle(5)) # Sat, not in the cycle

## monthly cycle
Pctime("2020-04-01", BuiltinCycle(12))
pctY2020Apr <- Pctime(c(50, 4), BuiltinCycle(12))  # same
pctY2020Apr
as_datetime(pctW2623Wed)

## Pctime can hold a vector of times
ap <- pcts(AirPassengers)
aptime <- Pctime(ap)              #  as_Pctime(ap)
aptime[1:12] # keep Pctime class
aptime[1]

aptime[[1]] # drop Pctime class

head(aptime)
tail(aptime)

apdates <- as_datetime(ap)
head(apdates)
tail(apdates)