Pctime objects

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 Pctime
[(x, i, j, drop = TRUE)

# S3 method for Pctime
[[(x, ..., drop = TRUE)

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

# S3 method for PeriodicTimeSeries
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
#> [1] "C2020 S2"

## quarterly cycle
Pctime("2020-04-01", BuiltinCycle(4))
#> [1] "Y2020 Q2"
pctQ <- Pctime(c(2020, 2), BuiltinCycle(4))  # same
pctQ
#> [1] "Y2020 Q2"

## 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
#> [1] "W1 Mon"
as_datetime(weekW1S1)
#> [1] "1969-12-29 UTC"

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

Pctime("2020-04-01", BuiltinCycle(7))
#> [1] "W2623 Wed"
pctW2623Wed <- Pctime(c(2623, 3), BuiltinCycle(7))  # same
pctW2623Wed
#> [1] "W2623 Wed"
as_datetime(pctW2623Wed)
#> [1] "2020-04-01 UTC"

## Monday-Friday week - a partial cycle derived from DayOfWeekCycle
BuiltinCycle(5)
#> Object from class 'PartialCycle'
#>     partial cycle of 'DayWeekCycle', seasons: 1, 2, 3, 4, 5
#> Cycle start: Monday 
pctMF <- Pctime("2020-04-03", BuiltinCycle(5)) # Fri
seq(pctMF, length.out = 10) # note: Sat, Sun are skipped
#>  [1] "W2623 Fri" "W2624 Mon" "W2624 Tue" "W2624 Wed" "W2624 Thu" "W2624 Fri"
#>  [7] "W2625 Mon" "W2625 Tue" "W2625 Wed" "W2625 Thu"

Pctime("2020-04-04", BuiltinCycle(5)) # Sat, not in the cycle
#> [1] "W2623 NA"

## monthly cycle
Pctime("2020-04-01", BuiltinCycle(12))
#> [1] "Y2020 Apr"
pctY2020Apr <- Pctime(c(50, 4), BuiltinCycle(12))  # same
pctY2020Apr
#> [1] "Y50 Apr"
as_datetime(pctW2623Wed)
#> [1] "2020-04-01 UTC"

## Pctime can hold a vector of times
ap <- pcts(AirPassengers)
aptime <- Pctime(ap)              #  as_Pctime(ap)
aptime[1:12] # keep Pctime class
#>  [1] "Y1949 Jan" "Y1949 Feb" "Y1949 Mar" "Y1949 Apr" "Y1949 May" "Y1949 Jun"
#>  [7] "Y1949 Jul" "Y1949 Aug" "Y1949 Sep" "Y1949 Oct" "Y1949 Nov" "Y1949 Dec"
aptime[1]
#> [1] "Y1949 Jan"

aptime[[1]] # drop Pctime class
#> [1] "1949-01-01 UTC"

head(aptime)
#> [1] "Y1949 Jan" "Y1949 Feb" "Y1949 Mar" "Y1949 Apr" "Y1949 May" "Y1949 Jun"
tail(aptime)
#> [1] "Y1960 Jul" "Y1960 Aug" "Y1960 Sep" "Y1960 Oct" "Y1960 Nov" "Y1960 Dec"

apdates <- as_datetime(ap)
head(apdates)
#> [1] "1949-01-01 UTC" "1949-02-01 UTC" "1949-03-01 UTC" "1949-04-01 UTC"
#> [5] "1949-05-01 UTC" "1949-06-01 UTC"
tail(apdates)
#> [1] "1960-07-01 UTC" "1960-08-01 UTC" "1960-09-01 UTC" "1960-10-01 UTC"
#> [5] "1960-11-01 UTC" "1960-12-01 UTC"