index.xts | R Documentation |
Functions to get and replace an xts object's index values and it's components.
## S3 method for class 'xts'
index(x, ...)
## S3 replacement method for class 'xts'
index(x) <- value
.index(x, ...)
.index(x) <- value
convertIndex(x, value)
# date/time component extraction
.indexsec(x)
.indexmin(x)
.indexhour(x)
.indexDate(x)
.indexday(x)
.indexwday(x)
.indexmday(x)
.indexweek(x)
.indexmon(x)
.indexyear(x)
.indexyday(x)
.indexisdst(x)
x |
an |
value |
new index value |
... |
arguments passed to other methods |
Internally, an xts object's index is a numeric value corresponding to
seconds since the 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 index
and index<-
methods get and replace the xts object's
index, respectively. 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 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 extract time components (similar to
POSIXlt
components) from the internal time index:
.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:
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 will throw a warning that they're deprecated, but they
will continue to work. There are no plans to remove them or have them
throw an error. Ever.
The latter 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.
There are options to throw a warning if there is no tzone
or
tclass
attribute on the index, even if there may be one on the xts
object. This gives the user a way to know if an xts object should be
updated to use the new structure.
You can enable the warnings via:
options(xts.warn.index.missing.tzone = TRUE, xts.warn.index.missing.tclass = TRUE)
You can identify xts objects with the old structure by printing them. Then
you can update them to the new structure using x <- as.xts(x)
.
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.
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.
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.
Objects track their timezone and index class
in their .indexTZ
and .indexCLASS
attributes, respectively.
Jeffrey A. Ryan
tformat
describes how the index values are formatted when printed,
tclass
provides details how xts handles the class of the index,
and tzone
has more information about the index timezone settings.
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)
class(index(x)) # POSIXct
tclass(x) # POSIXct
# the internal numeric index
.index(x)
# add 1 hour (3600 seconds) to the numeric index
.index(x) <- index(x) + 3600
index(x)
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)]
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]
# Select all observations on Monday
mon <- y[.indexwday(y) == 1]
head(mon)
tail(mon)
unique(weekdays(index(mon))) # check
# 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]
### 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))]
# 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))]
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)]
# Select all data for the 28th to 31st of each month, excluding any Fridays:
u[.indexmday(u) %in% 28:31 & .indexwday(u) != 5]
# Subset by week since origin
unique(.indexweek(u))
origin <- xts(1, as.POSIXct("1970-01-01"))
unique(.indexweek(origin))
# Select all observations in weeks 2515 to 2517.
u2 <- u[.indexweek(u) %in% 2515:2517]
head(u2); tail(u2)
# Select all observations after 12pm for day 50 and 51 in each year
u[.indexyday(u) %in% 50:51 & .indexhour(u) >= 12]
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.