Get and Replace the Class of an xts Index

Functions to get and replace an xts object's index values and it's components.

Usage

# S3 method for class 'xts'
index(x, ...)

# S3 method for class 'xts'
index(x) <- value

# S3 method for class 'xts'
time(x) <- value

# S3 method for class 'xts'
time(x, ...)

.index(x, ...)

.index(x) <- value

.indexsec(x)

.indexmin(x)

.indexhour(x)

.indexmday(x)

.indexmon(x)

.indexyear(x)

.indexwday(x)

.indexbday(x)

.indexyday(x)

.indexisdst(x)

.indexDate(x)

.indexday(x)

.indexweek(x)

.indexyweek(x)

convertIndex(x, value)

Arguments

x: An xts object.
...: Arguments passed to other methods.
value: A new time index value.

Details

An xts object's index is stored internally as the number of seconds since UNIX epoch in the UTC timezone. The .index() and .index<- functions get and replace the internal numeric value of the index, respectively. These functions are primarily for internal use, but are exported because they may be useful for users.

The replacement method also updates the tclass() and tzone() of the index to match the class and timezone of the new index, respectively. The index() method converts the internal numeric index to the class specified by the 'tclass' attribute and with the timezone specified by the 'tzone' attribute before returning the index values to the user.

The .indexXXX() functions below extract time components from the internal time index. They return values like the values of POSIXlt components.

.indexsec: 0 - 61: seconds of the minute (local time)
.indexmin: 0 - 59: minutes of the hour (local time)
.indexhour: 0 - 23: hours of the day (local time)
.indexDate: date as seconds since the epoch (UTC not local time
.indexday: date as seconds since the epoch (UTC not local time
.indexwday: 0 - 6: day of the week (Sunday - Saturday, local time)
.indexmday: 1 - 31: day of the month (local time)
.indexweek: weeks since the epoch (UTC not local time
.indexmon: 0 - 11: month of the year (local time)
.indexyear: years since 1900 (local time)
.indexyday: 0 - 365: day of the year (local time, 365 only in leap years)
.indexisdst: 1, 0, -1: Daylight Saving Time flag. Positive if Daylight Saving Time is in effect, zero if not, negative if unknown.

Changes in timezone, index class, and index format internal structure, by xts version:

Version 0.12.0:: The .indexTZ, .indexCLASS and .indexFORMAT attributes are no longer stored on xts objects, only on the index itself.

The indexTZ(), indexClass(), and indexFormat() functions (and their respective replacement methods) are deprecated in favor of their respective tzone(), tclass(), and tformat() versions. The previous versions throw a warning that they're deprecated, but they will continue to work. They will never be removed or throw an error. Ever.

The new versions are careful to look for the old attributes on the xts object, in case they're ever called on an xts object that was created prior to the attributes being added to the index itself.

You can set options(xts.warn.index.missing.tzone = TRUE) and options(xts.warn.index.missing.tclass = TRUE) to identify xts objects that do not have a 'tzone' or 'tclass' attribute on the index, even if there is a 'tzone' or 'tclass' attribute on the xts object itself. The warnings will be thrown when the object is printed. Use x <- as.xts(x) to update these objects to the new structure.
Version 0.9.8:: The index timezone is now set to "UTC" for time classes that do not have any intra-day component (e.g. days, months, quarters). Previously the timezone was blank, which meant "local time" as determined by R and the OS.
Version 0.9.2:: There are new get/set methods for the timezone, index class, and index format attributes: tzone() and, tzone<-, tclass() and tclass<-, and tformat() and tformat<-. These new functions are aliases to their indexTZ(), indexClass(), and indexFormat() counterparts.
Version 0.7.5:: The timezone, index class, and index format were added as attributes to the index itself, as 'tzone', 'tclass', and 'tformat', respectively. This is in order to remove those three attributes from the xts object, so they're only on the index itself.

The indexTZ(), indexClass(), and indexFormat() functions (and their respective replacement methods) will continue to work as in prior xts versions. The attributes on the index take priority over their respective counterparts that may be on the xts object.
Versions 0.6.4 and prior:: Objects track their timezone and index class in their '.indexTZ' and '.indexCLASS' attributes, respectively.

Author

Jeffrey A. Ryan

Examples


x <- timeBasedSeq('2010-01-01/2010-01-01 12:00/H')
x <- xts(seq_along(x), x)

# the index values, converted to 'tclass' (POSIXct in this case)
index(x)
#>  [1] "2010-01-01 00:00:00 UTC" "2010-01-01 01:00:00 UTC"
#>  [3] "2010-01-01 02:00:00 UTC" "2010-01-01 03:00:00 UTC"
#>  [5] "2010-01-01 04:00:00 UTC" "2010-01-01 05:00:00 UTC"
#>  [7] "2010-01-01 06:00:00 UTC" "2010-01-01 07:00:00 UTC"
#>  [9] "2010-01-01 08:00:00 UTC" "2010-01-01 09:00:00 UTC"
#> [11] "2010-01-01 10:00:00 UTC" "2010-01-01 11:00:00 UTC"
#> [13] "2010-01-01 12:00:00 UTC"
class(index(x))  # POSIXct
#> [1] "POSIXct" "POSIXt" 
tclass(x)        # POSIXct
#> [1] "POSIXct" "POSIXt" 

# the internal numeric index
.index(x)
#>  [1] 1262304000 1262307600 1262311200 1262314800 1262318400 1262322000
#>  [7] 1262325600 1262329200 1262332800 1262336400 1262340000 1262343600
#> [13] 1262347200
#> attr(,"tzone")
#> [1] ""
#> attr(,"tclass")
#> [1] "POSIXct" "POSIXt" 
# add 1 hour (3600 seconds) to the numeric index
.index(x) <- index(x) + 3600
index(x)
#> Warning: index does not have a ‘tclass’ attribute
#>   and xts object does not have a ‘tclass’ or ‘.indexCLASS’ attribute
#>   returning “POSIXct”index does not have a ‘tclass’ attribute
#>   and xts object does not have a ‘tclass’ or ‘.indexCLASS’ attribute
#>   returning “POSIXt”
#>  [1] "2010-01-01 01:00:00 UTC" "2010-01-01 02:00:00 UTC"
#>  [3] "2010-01-01 03:00:00 UTC" "2010-01-01 04:00:00 UTC"
#>  [5] "2010-01-01 05:00:00 UTC" "2010-01-01 06:00:00 UTC"
#>  [7] "2010-01-01 07:00:00 UTC" "2010-01-01 08:00:00 UTC"
#>  [9] "2010-01-01 09:00:00 UTC" "2010-01-01 10:00:00 UTC"
#> [11] "2010-01-01 11:00:00 UTC" "2010-01-01 12:00:00 UTC"
#> [13] "2010-01-01 13:00:00 UTC"

y <- timeBasedSeq('2010-01-01/2010-01-02 12:00')
y <- xts(seq_along(y), y)

# Select all observations in the first 6 and last 3 minutes of the
# 8th and 15th hours on each day
y[.indexhour(y) %in% c(8, 15) & .indexmin(y) %in% c(0:5, 57:59)]
#>                     [,1]
#> 2010-01-01 08:00:00  481
#> 2010-01-01 08:01:00  482
#> 2010-01-01 08:02:00  483
#> 2010-01-01 08:03:00  484
#> 2010-01-01 08:04:00  485
#> 2010-01-01 08:05:00  486
#> 2010-01-01 08:57:00  538
#> 2010-01-01 08:58:00  539
#> 2010-01-01 08:59:00  540
#> 2010-01-01 15:00:00  901
#> 2010-01-01 15:01:00  902
#> 2010-01-01 15:02:00  903
#> 2010-01-01 15:03:00  904
#> 2010-01-01 15:04:00  905
#> 2010-01-01 15:05:00  906
#> 2010-01-01 15:57:00  958
#> 2010-01-01 15:58:00  959
#> 2010-01-01 15:59:00  960
#> 2010-01-02 08:00:00 1921
#> 2010-01-02 08:01:00 1922
#> 2010-01-02 08:02:00 1923
#> 2010-01-02 08:03:00 1924
#> 2010-01-02 08:04:00 1925
#> 2010-01-02 08:05:00 1926
#> 2010-01-02 08:57:00 1978
#> 2010-01-02 08:58:00 1979
#> 2010-01-02 08:59:00 1980

i <- 0:60000
focal_date <- as.numeric(as.POSIXct("2018-02-01", tz = "UTC"))
y <- .xts(i, c(focal_date + i * 15), tz = "UTC", dimnames = list(NULL, "value"))

# Select all observations for the first minute of each hour
y[.indexmin(y) == 0]
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>   NOTE: set 'options(xts_check_TZ = FALSE)' to disable this warning
#>     This note is displayed once per session
#>                     value
#> 2018-02-01 00:00:00     0
#> 2018-02-01 00:00:15     1
#> 2018-02-01 00:00:30     2
#> 2018-02-01 00:00:45     3
#> 2018-02-01 01:00:00   240
#> 2018-02-01 01:00:15   241
#> 2018-02-01 01:00:30   242
#> 2018-02-01 01:00:45   243
#> 2018-02-01 02:00:00   480
#> 2018-02-01 02:00:15   481
#>                 ...      
#> 2018-02-11 07:00:45 59283
#> 2018-02-11 08:00:00 59520
#> 2018-02-11 08:00:15 59521
#> 2018-02-11 08:00:30 59522
#> 2018-02-11 08:00:45 59523
#> 2018-02-11 09:00:00 59760
#> 2018-02-11 09:00:15 59761
#> 2018-02-11 09:00:30 59762
#> 2018-02-11 09:00:45 59763
#> 2018-02-11 10:00:00 60000

# Select all observations on Monday
mon <- y[.indexwday(y) == 1]
head(mon)
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-05 00:00:00 23040
#> 2018-02-05 00:00:15 23041
#> 2018-02-05 00:00:30 23042
#> 2018-02-05 00:00:45 23043
#> 2018-02-05 00:01:00 23044
#> 2018-02-05 00:01:15 23045
tail(mon)
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-05 23:58:30 28794
#> 2018-02-05 23:58:45 28795
#> 2018-02-05 23:59:00 28796
#> 2018-02-05 23:59:15 28797
#> 2018-02-05 23:59:30 28798
#> 2018-02-05 23:59:45 28799
unique(weekdays(index(mon))) # check
#> [1] "Monday"

# Disjoint time of day selections

# Select all observations between 08:30 and 08:59:59.9999  or between 12:00 and 12:14:59.99999:
y[.indexhour(y) == 8 & .indexmin(y) >= 30 | .indexhour(y) == 12 & .indexmin(x) %in% 0:14]
#> Warning: index does not have a ‘tzone’ attribute
#>   and xts object does not have a ‘tzone’ or ‘.indexTZ’ attribute
#>   returning “”
#> Warning: longer object length is not a multiple of shorter object length
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-01 08:30:00  2040
#> 2018-02-01 08:30:15  2041
#> 2018-02-01 08:30:30  2042
#> 2018-02-01 08:30:45  2043
#> 2018-02-01 08:31:00  2044
#> 2018-02-01 08:31:15  2045
#> 2018-02-01 08:31:30  2046
#> 2018-02-01 08:31:45  2047
#> 2018-02-01 08:32:00  2048
#> 2018-02-01 08:32:15  2049
#>                 ...      
#> 2018-02-11 08:57:30 59750
#> 2018-02-11 08:57:45 59751
#> 2018-02-11 08:58:00 59752
#> 2018-02-11 08:58:15 59753
#> 2018-02-11 08:58:30 59754
#> 2018-02-11 08:58:45 59755
#> 2018-02-11 08:59:00 59756
#> 2018-02-11 08:59:15 59757
#> 2018-02-11 08:59:30 59758
#> 2018-02-11 08:59:45 59759

### Compound selections

# Select all observations for Wednesdays or Fridays between 9am and 4pm (exclusive of 4pm):
y[.indexwday(y) %in% c(3, 5) & (.indexhour(y) %in%  c(9:15))]
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-02 09:00:00  7920
#> 2018-02-02 09:00:15  7921
#> 2018-02-02 09:00:30  7922
#> 2018-02-02 09:00:45  7923
#> 2018-02-02 09:01:00  7924
#> 2018-02-02 09:01:15  7925
#> 2018-02-02 09:01:30  7926
#> 2018-02-02 09:01:45  7927
#> 2018-02-02 09:02:00  7928
#> 2018-02-02 09:02:15  7929
#>                 ...      
#> 2018-02-09 15:57:30 49910
#> 2018-02-09 15:57:45 49911
#> 2018-02-09 15:58:00 49912
#> 2018-02-09 15:58:15 49913
#> 2018-02-09 15:58:30 49914
#> 2018-02-09 15:58:45 49915
#> 2018-02-09 15:59:00 49916
#> 2018-02-09 15:59:15 49917
#> 2018-02-09 15:59:30 49918
#> 2018-02-09 15:59:45 49919

# Select all observations on Monday between 8:59:45 and 09:04:30:

y[.indexwday(y) == 1 & (.indexhour(y) == 8 & .indexmin(y) == 59 & .indexsec(y) >= 45 |
                        .indexhour(y) == 9 &
                        (.indexmin(y) <  4 | .indexmin(y) ==  4 & .indexsec(y) <= 30))]
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-05 08:59:45 25199
#> 2018-02-05 09:00:00 25200
#> 2018-02-05 09:00:15 25201
#> 2018-02-05 09:00:30 25202
#> 2018-02-05 09:00:45 25203
#> 2018-02-05 09:01:00 25204
#> 2018-02-05 09:01:15 25205
#> 2018-02-05 09:01:30 25206
#> 2018-02-05 09:01:45 25207
#> 2018-02-05 09:02:00 25208
#> 2018-02-05 09:02:15 25209
#> 2018-02-05 09:02:30 25210
#> 2018-02-05 09:02:45 25211
#> 2018-02-05 09:03:00 25212
#> 2018-02-05 09:03:15 25213
#> 2018-02-05 09:03:30 25214
#> 2018-02-05 09:03:45 25215
#> 2018-02-05 09:04:00 25216
#> 2018-02-05 09:04:15 25217
#> 2018-02-05 09:04:30 25218

i <- 0:30000
u <- .xts(i, c(focal_date + i * 1800), tz = "UTC", dimnames = list(NULL, "value"))

# Select all observations for January or February:
u[.indexmon(u) %in% c(0, 1)]
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-01 00:00:00     0
#> 2018-02-01 00:30:00     1
#> 2018-02-01 01:00:00     2
#> 2018-02-01 01:30:00     3
#> 2018-02-01 02:00:00     4
#> 2018-02-01 02:30:00     5
#> 2018-02-01 03:00:00     6
#> 2018-02-01 03:30:00     7
#> 2018-02-01 04:00:00     8
#> 2018-02-01 04:30:00     9
#>                 ...      
#> 2019-02-28 19:00:00 18854
#> 2019-02-28 19:30:00 18855
#> 2019-02-28 20:00:00 18856
#> 2019-02-28 20:30:00 18857
#> 2019-02-28 21:00:00 18858
#> 2019-02-28 21:30:00 18859
#> 2019-02-28 22:00:00 18860
#> 2019-02-28 22:30:00 18861
#> 2019-02-28 23:00:00 18862
#> 2019-02-28 23:30:00 18863

# Select all data for the 28th to 31st of each month, excluding any Fridays:
u[.indexmday(u) %in% 28:31 & .indexwday(u) != 5]
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-28 00:00:00  1296
#> 2018-02-28 00:30:00  1297
#> 2018-02-28 01:00:00  1298
#> 2018-02-28 01:30:00  1299
#> 2018-02-28 02:00:00  1300
#> 2018-02-28 02:30:00  1301
#> 2018-02-28 03:00:00  1302
#> 2018-02-28 03:30:00  1303
#> 2018-02-28 04:00:00  1304
#> 2018-02-28 04:30:00  1305
#>                 ...      
#> 2019-09-30 19:00:00 29126
#> 2019-09-30 19:30:00 29127
#> 2019-09-30 20:00:00 29128
#> 2019-09-30 20:30:00 29129
#> 2019-09-30 21:00:00 29130
#> 2019-09-30 21:30:00 29131
#> 2019-09-30 22:00:00 29132
#> 2019-09-30 22:30:00 29133
#> 2019-09-30 23:00:00 29134
#> 2019-09-30 23:30:00 29135

# Subset by week since origin
unique(.indexweek(u))
#>  [1] 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523
#> [16] 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538
#> [31] 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553
#> [46] 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568
#> [61] 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583
#> [76] 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598
origin <- xts(1, as.POSIXct("1970-01-01"))
unique(.indexweek(origin))
#> [1] 0

# Select all observations in weeks 2515 to 2517.
u2 <- u[.indexweek(u) %in% 2515:2517]
head(u2); tail(u2)
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-03-12 00:00:00  1872
#> 2018-03-12 00:30:00  1873
#> 2018-03-12 01:00:00  1874
#> 2018-03-12 01:30:00  1875
#> 2018-03-12 02:00:00  1876
#> 2018-03-12 02:30:00  1877
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-04-01 21:00:00  2874
#> 2018-04-01 21:30:00  2875
#> 2018-04-01 22:00:00  2876
#> 2018-04-01 22:30:00  2877
#> 2018-04-01 23:00:00  2878
#> 2018-04-01 23:30:00  2879

# Select all observations after 12pm for day 50 and 51 in each year
u[.indexyday(u) %in% 50:51 & .indexhour(u) >= 12]
#> Warning: object timezone ('UTC') is different from system timezone ('')
#>                     value
#> 2018-02-20 12:00:00   936
#> 2018-02-20 12:30:00   937
#> 2018-02-20 13:00:00   938
#> 2018-02-20 13:30:00   939
#> 2018-02-20 14:00:00   940
#> 2018-02-20 14:30:00   941
#> 2018-02-20 15:00:00   942
#> 2018-02-20 15:30:00   943
#> 2018-02-20 16:00:00   944
#> 2018-02-20 16:30:00   945
#> 2018-02-20 17:00:00   946
#> 2018-02-20 17:30:00   947
#> 2018-02-20 18:00:00   948
#> 2018-02-20 18:30:00   949
#> 2018-02-20 19:00:00   950
#> 2018-02-20 19:30:00   951
#> 2018-02-20 20:00:00   952
#> 2018-02-20 20:30:00   953
#> 2018-02-20 21:00:00   954
#> 2018-02-20 21:30:00   955
#> 2018-02-20 22:00:00   956
#> 2018-02-20 22:30:00   957
#> 2018-02-20 23:00:00   958
#> 2018-02-20 23:30:00   959
#> 2018-02-21 12:00:00   984
#> 2018-02-21 12:30:00   985
#> 2018-02-21 13:00:00   986
#> 2018-02-21 13:30:00   987
#> 2018-02-21 14:00:00   988
#> 2018-02-21 14:30:00   989
#> 2018-02-21 15:00:00   990
#> 2018-02-21 15:30:00   991
#> 2018-02-21 16:00:00   992
#> 2018-02-21 16:30:00   993
#> 2018-02-21 17:00:00   994
#> 2018-02-21 17:30:00   995
#> 2018-02-21 18:00:00   996
#> 2018-02-21 18:30:00   997
#> 2018-02-21 19:00:00   998
#> 2018-02-21 19:30:00   999
#> 2018-02-21 20:00:00  1000
#> 2018-02-21 20:30:00  1001
#> 2018-02-21 21:00:00  1002
#> 2018-02-21 21:30:00  1003
#> 2018-02-21 22:00:00  1004
#> 2018-02-21 22:30:00  1005
#> 2018-02-21 23:00:00  1006
#> 2018-02-21 23:30:00  1007
#> 2019-02-20 12:00:00 18456
#> 2019-02-20 12:30:00 18457
#> 2019-02-20 13:00:00 18458
#> 2019-02-20 13:30:00 18459
#> 2019-02-20 14:00:00 18460
#> 2019-02-20 14:30:00 18461
#> 2019-02-20 15:00:00 18462
#> 2019-02-20 15:30:00 18463
#> 2019-02-20 16:00:00 18464
#> 2019-02-20 16:30:00 18465
#> 2019-02-20 17:00:00 18466
#> 2019-02-20 17:30:00 18467
#> 2019-02-20 18:00:00 18468
#> 2019-02-20 18:30:00 18469
#> 2019-02-20 19:00:00 18470
#> 2019-02-20 19:30:00 18471
#> 2019-02-20 20:00:00 18472
#> 2019-02-20 20:30:00 18473
#> 2019-02-20 21:00:00 18474
#> 2019-02-20 21:30:00 18475
#> 2019-02-20 22:00:00 18476
#> 2019-02-20 22:30:00 18477
#> 2019-02-20 23:00:00 18478
#> 2019-02-20 23:30:00 18479
#> 2019-02-21 12:00:00 18504
#> 2019-02-21 12:30:00 18505
#> 2019-02-21 13:00:00 18506
#> 2019-02-21 13:30:00 18507
#> 2019-02-21 14:00:00 18508
#> 2019-02-21 14:30:00 18509
#> 2019-02-21 15:00:00 18510
#> 2019-02-21 15:30:00 18511
#> 2019-02-21 16:00:00 18512
#> 2019-02-21 16:30:00 18513
#> 2019-02-21 17:00:00 18514
#> 2019-02-21 17:30:00 18515
#> 2019-02-21 18:00:00 18516
#> 2019-02-21 18:30:00 18517
#> 2019-02-21 19:00:00 18518
#> 2019-02-21 19:30:00 18519
#> 2019-02-21 20:00:00 18520
#> 2019-02-21 20:30:00 18521
#> 2019-02-21 21:00:00 18522
#> 2019-02-21 21:30:00 18523
#> 2019-02-21 22:00:00 18524
#> 2019-02-21 22:30:00 18525
#> 2019-02-21 23:00:00 18526
#> 2019-02-21 23:30:00 18527