Create or Test For An xts Time-Series Object

Constructor function for creating an extensible time-series object.

Usage

xts(
  x = NULL,
  order.by = index(x),
  frequency = NULL,
  unique = TRUE,
  tzone = Sys.getenv("TZ"),
  ...
)

.xts(
  x = NULL,
  index,
  tclass = c("POSIXct", "POSIXt"),
  tzone = Sys.getenv("TZ"),
  check = TRUE,
  unique = FALSE,
  ...
)

is.xts(x)

Arguments

x: An object containing the underlying data.
order.by: A corresponding vector of dates/times of a known time-based class. See Details.
frequency: Numeric value indicating the frequency of order.by. See details.
unique: Can the index only include unique timestamps? Ignored when check = FALSE.
tzone: Time zone of the index (ignored for indices without a time component, e.g. Date, yearmon, yearqtr). See tzone().
...: Additional attributes to be added. See details.
index: A corresponding numeric vector specified as seconds since the UNIX epoch (1970-01-01 00:00:00.000).
tclass: Time class to use for the index. See tclass().
check: Must the index be ordered? The index cannot contain duplicates when check = TRUE and unique = TRUE.

Value

An S3 object of class xts.

Details

xts() is used to create an xts object from raw data inputs. The xts class inherits from and extends the zoo class, which means most zoo functions can be used on xts objects.

The xts() constructor is the preferred way to create xts objects. It performs several checks to ensure it returns a well-formed xts object. The .xts() constructor is mainly for internal use. It is more efficient then the regular xts() constructor because it doesn't perform as many validity checks. Use it with caution.

Similar to zoo objects, xts objects must have an ordered index. While zoo indexes cannot contain duplicate values, xts objects have optionally supported duplicate index elements since version 0.5-0. The xts class has one additional requirement: the index must be a time-based class. Currently supported classes include: ‘Date’, ‘POSIXct’, ‘timeDate’, as well as ‘yearmon’ and ‘yearqtr’ where the index values remain unique.

The uniqueness requirement was relaxed in version 0.5-0, but is still enforced by default. Setting unique = FALSE skips the uniqueness check and only ensures that the index is ordered via the isOrdered() function.

As of version 0.10-0, xts no longer allows missing values in the index. This is because many xts functions expect all index values to be finite. The most important of these is merge.xts(), which is used ubiquitously. Missing values in the index are usually the result of a date-time conversion error (e.g. incorrect format, non-existent time due to daylight saving time, etc.). Because of how non-finite numbers are represented, a missing timestamp will always be at the end of the index (except if it is -Inf, which will be first).

Another difference from zoo is that xts object may carry additional attributes that may be desired in individual time-series handling. This includes the ability to augment the objects data with meta-data otherwise not cleanly attachable to a standard zoo object. These attributes may be assigned and extracted via xtsAttributes() and xtsAttributes<-, respectively.

Examples of usage from finance may include the addition of data for keeping track of sources, last-update times, financial instrument descriptions or details, etc.

The idea behind xts is to offer the user the ability to utilize a standard zoo object, while providing an mechanism to customize the object's meta-data, as well as create custom methods to handle the object in a manner required by the user.

Many xts-specific methods have been written to better handle the unique aspects of xts. These include, subsetting ([), merge(), cbind(), rbind(), c(), math and logical operations, lag(), diff(), coredata(), head(), and tail(). There are also xts-specific methods for converting to/from R's different time-series classes.

Subsetting via [ methods offers the ability to specify dates by range, if they are enclosed in quotes. The style borrows from python by creating ranges separated by a double colon “"::"” or “"/"”. Each side of the range may be left blank, which would then default to the start and end of the data, respectively. To specify a subset of times, it is only required that the time specified be in standard ISO format, with some form of separation between the elements. The time must be left-filled, that is to specify a full year one needs only to provide the year, a month requires the full year and the integer of the month requested - e.g. '1999-01'. This format would extend all the way down to seconds - e.g. '1999-01-01 08:35:23'. Leading zeros are not necessary. See the examples for more detail.

Users may also extend the xts class to new classes to allow for method overloading.

Additional benefits derive from the use of as.xts() and reclass(), which allow for lossless two-way conversion between common R time-series classes and the xts object structure. See those functions for more detail.

References

zoo

Author

Jeffrey A. Ryan and Joshua M. Ulrich

Examples


data(sample_matrix)
sample.xts <- as.xts(sample_matrix, descr='my new xts object')

class(sample.xts)
#> [1] "xts" "zoo"
str(sample.xts)
#> An xts object on 2007-01-02 / 2007-06-30 containing: 
#>   Data:    double [180, 4]
#>   Columns: Open, High, Low, Close
#>   Index:   POSIXct,POSIXt [180] (TZ: "")
#>   xts Attributes:
#>     $ descr: chr "my new xts object"

head(sample.xts)  # attribute 'descr' hidden from view
#>                Open     High      Low    Close
#> 2007-01-02 50.03978 50.11778 49.95041 50.11778
#> 2007-01-03 50.23050 50.42188 50.23050 50.39767
#> 2007-01-04 50.42096 50.42096 50.26414 50.33236
#> 2007-01-05 50.37347 50.37347 50.22103 50.33459
#> 2007-01-06 50.24433 50.24433 50.11121 50.18112
#> 2007-01-07 50.13211 50.21561 49.99185 49.99185
attr(sample.xts,'descr')
#> [1] "my new xts object"

sample.xts['2007']  # all of 2007
#>                Open     High      Low    Close
#> 2007-01-02 50.03978 50.11778 49.95041 50.11778
#> 2007-01-03 50.23050 50.42188 50.23050 50.39767
#> 2007-01-04 50.42096 50.42096 50.26414 50.33236
#> 2007-01-05 50.37347 50.37347 50.22103 50.33459
#> 2007-01-06 50.24433 50.24433 50.11121 50.18112
#> 2007-01-07 50.13211 50.21561 49.99185 49.99185
#> 2007-01-08 50.03555 50.10363 49.96971 49.98806
#> 2007-01-09 49.99489 49.99489 49.80454 49.91333
#> 2007-01-10 49.91228 50.13053 49.91228 49.97246
#> 2007-01-11 49.88529 50.23910 49.88529 50.23910
#>        ...                                    
#> 2007-06-21 47.71012 47.71012 47.61106 47.62921
#> 2007-06-22 47.56849 47.59266 47.32549 47.32549
#> 2007-06-23 47.22873 47.24771 47.09144 47.24771
#> 2007-06-24 47.23996 47.30287 47.20932 47.22764
#> 2007-06-25 47.20471 47.42772 47.13405 47.42772
#> 2007-06-26 47.44300 47.61611 47.44300 47.61611
#> 2007-06-27 47.62323 47.71673 47.60015 47.62769
#> 2007-06-28 47.67604 47.70460 47.57241 47.60716
#> 2007-06-29 47.63629 47.77563 47.61733 47.66471
#> 2007-06-30 47.67468 47.94127 47.67468 47.76719
sample.xts['2007-03/']  # March 2007 to the end of the data set
#>                Open     High      Low    Close
#> 2007-03-01 50.81620 50.81620 50.56451 50.57075
#> 2007-03-02 50.60980 50.72061 50.50808 50.61559
#> 2007-03-03 50.73241 50.73241 50.40929 50.41033
#> 2007-03-04 50.39273 50.40881 50.24922 50.32636
#> 2007-03-05 50.26501 50.34050 50.26501 50.29567
#> 2007-03-06 50.27464 50.32019 50.16380 50.16380
#> 2007-03-07 50.14458 50.20278 49.91381 49.91381
#> 2007-03-08 49.93149 50.00364 49.84893 49.91839
#> 2007-03-09 49.92377 49.92377 49.74242 49.80712
#> 2007-03-10 49.79370 49.88984 49.70385 49.88698
#>        ...                                    
#> 2007-06-21 47.71012 47.71012 47.61106 47.62921
#> 2007-06-22 47.56849 47.59266 47.32549 47.32549
#> 2007-06-23 47.22873 47.24771 47.09144 47.24771
#> 2007-06-24 47.23996 47.30287 47.20932 47.22764
#> 2007-06-25 47.20471 47.42772 47.13405 47.42772
#> 2007-06-26 47.44300 47.61611 47.44300 47.61611
#> 2007-06-27 47.62323 47.71673 47.60015 47.62769
#> 2007-06-28 47.67604 47.70460 47.57241 47.60716
#> 2007-06-29 47.63629 47.77563 47.61733 47.66471
#> 2007-06-30 47.67468 47.94127 47.67468 47.76719
sample.xts['2007-03/2007']  # March 2007 to the end of 2007
#>                Open     High      Low    Close
#> 2007-03-01 50.81620 50.81620 50.56451 50.57075
#> 2007-03-02 50.60980 50.72061 50.50808 50.61559
#> 2007-03-03 50.73241 50.73241 50.40929 50.41033
#> 2007-03-04 50.39273 50.40881 50.24922 50.32636
#> 2007-03-05 50.26501 50.34050 50.26501 50.29567
#> 2007-03-06 50.27464 50.32019 50.16380 50.16380
#> 2007-03-07 50.14458 50.20278 49.91381 49.91381
#> 2007-03-08 49.93149 50.00364 49.84893 49.91839
#> 2007-03-09 49.92377 49.92377 49.74242 49.80712
#> 2007-03-10 49.79370 49.88984 49.70385 49.88698
#>        ...                                    
#> 2007-06-21 47.71012 47.71012 47.61106 47.62921
#> 2007-06-22 47.56849 47.59266 47.32549 47.32549
#> 2007-06-23 47.22873 47.24771 47.09144 47.24771
#> 2007-06-24 47.23996 47.30287 47.20932 47.22764
#> 2007-06-25 47.20471 47.42772 47.13405 47.42772
#> 2007-06-26 47.44300 47.61611 47.44300 47.61611
#> 2007-06-27 47.62323 47.71673 47.60015 47.62769
#> 2007-06-28 47.67604 47.70460 47.57241 47.60716
#> 2007-06-29 47.63629 47.77563 47.61733 47.66471
#> 2007-06-30 47.67468 47.94127 47.67468 47.76719
sample.xts['/'] # the whole data set
#>                Open     High      Low    Close
#> 2007-01-02 50.03978 50.11778 49.95041 50.11778
#> 2007-01-03 50.23050 50.42188 50.23050 50.39767
#> 2007-01-04 50.42096 50.42096 50.26414 50.33236
#> 2007-01-05 50.37347 50.37347 50.22103 50.33459
#> 2007-01-06 50.24433 50.24433 50.11121 50.18112
#> 2007-01-07 50.13211 50.21561 49.99185 49.99185
#> 2007-01-08 50.03555 50.10363 49.96971 49.98806
#> 2007-01-09 49.99489 49.99489 49.80454 49.91333
#> 2007-01-10 49.91228 50.13053 49.91228 49.97246
#> 2007-01-11 49.88529 50.23910 49.88529 50.23910
#>        ...                                    
#> 2007-06-21 47.71012 47.71012 47.61106 47.62921
#> 2007-06-22 47.56849 47.59266 47.32549 47.32549
#> 2007-06-23 47.22873 47.24771 47.09144 47.24771
#> 2007-06-24 47.23996 47.30287 47.20932 47.22764
#> 2007-06-25 47.20471 47.42772 47.13405 47.42772
#> 2007-06-26 47.44300 47.61611 47.44300 47.61611
#> 2007-06-27 47.62323 47.71673 47.60015 47.62769
#> 2007-06-28 47.67604 47.70460 47.57241 47.60716
#> 2007-06-29 47.63629 47.77563 47.61733 47.66471
#> 2007-06-30 47.67468 47.94127 47.67468 47.76719
sample.xts['/2007'] # the beginning of the data through 2007
#>                Open     High      Low    Close
#> 2007-01-02 50.03978 50.11778 49.95041 50.11778
#> 2007-01-03 50.23050 50.42188 50.23050 50.39767
#> 2007-01-04 50.42096 50.42096 50.26414 50.33236
#> 2007-01-05 50.37347 50.37347 50.22103 50.33459
#> 2007-01-06 50.24433 50.24433 50.11121 50.18112
#> 2007-01-07 50.13211 50.21561 49.99185 49.99185
#> 2007-01-08 50.03555 50.10363 49.96971 49.98806
#> 2007-01-09 49.99489 49.99489 49.80454 49.91333
#> 2007-01-10 49.91228 50.13053 49.91228 49.97246
#> 2007-01-11 49.88529 50.23910 49.88529 50.23910
#>        ...                                    
#> 2007-06-21 47.71012 47.71012 47.61106 47.62921
#> 2007-06-22 47.56849 47.59266 47.32549 47.32549
#> 2007-06-23 47.22873 47.24771 47.09144 47.24771
#> 2007-06-24 47.23996 47.30287 47.20932 47.22764
#> 2007-06-25 47.20471 47.42772 47.13405 47.42772
#> 2007-06-26 47.44300 47.61611 47.44300 47.61611
#> 2007-06-27 47.62323 47.71673 47.60015 47.62769
#> 2007-06-28 47.67604 47.70460 47.57241 47.60716
#> 2007-06-29 47.63629 47.77563 47.61733 47.66471
#> 2007-06-30 47.67468 47.94127 47.67468 47.76719
sample.xts['2007-01-03'] # just the 3rd of January 2007
#>               Open     High     Low    Close
#> 2007-01-03 50.2305 50.42188 50.2305 50.39767