xts: merge – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

merge

Merge xts Objects

Description

Used to perform merge operation on xts objects by time (index). Given the inherent ordered nature of xts time-series, a merge-join style merge allows for optimally efficient joins.

Usage

## S3 method for class 'xts'
merge(...,
      all = TRUE,
      fill = NA,
      suffixes = NULL,
      join = "outer",
      retside = TRUE,
      retclass = "xts",
      tzone = NULL,
      drop=NULL,
      check.names=NULL)

Arguments

`...`	one or more xts objects, or objects coercible to class xts
`all`	a logical vector indicating merge type
`fill`	values to be used for missing elements
`suffixes`	to be added to merged column names
`join`	type of database join
`retside`	which side of the merged object should be returned (2-case only)
`retclass`	object to return
`tzone`	time zone of merged object
`drop`	not currently used
`check.names`	not currently used

Details

This is an xts method compatible with merge.zoo, as xts extends zoo. That documentation should also be referenced. Difference are noted where applicable.

Implemented almost entirely in custom C-level code, it is possible using either the all argument or the join argument to implement all common database join operations along the to-be-merged objects time-index: ‘outer’ (full outer - all rows), ‘inner’ (only rows with common indexes), ‘left’ (all rows in the left object, and those that match in the right), and ‘right’ (all rows in the right object, and those that match in the left).

The above join types can also be expressed as a vector of logical values passed to all. c(TRUE,TRUE) or TRUE for ‘join="outer"’, c(FALSE,FALSE) or FALSE for ‘join="inner"’, c(TRUE, FALSE) for ‘join="left"’, and c(FALSE,TRUE) for ‘join="right"’.

Note that the all and join arguments imply a two case scenario. For merging more than two objects, they will simply fall back to a full outer or full inner join, depending on the first position of all, as left and right can be ambiguous with respect to sides.

To do something along the lines of merge.zoo's method of joining based on an all argument of the same length of the arguments to join, see the example.

The resultant object will have the timezone of the leftmost argument if available. Use tzone to override.

If retclass is NULL, the joined objects will be split and reassigned silently back to the original environment they are called from. This is for backward compatibility with zoo, though unused by xts.

If retclass is FALSE the object will be stripped of its class attribute. This is for internal use.

Value

A new xts object containing the appropriate elements of the objects passed in to be merged.

Note

This is a highly optimized merge, specifically designed for ordered data. The only supported merging is based on the underlying time index.

Author(s)

Jeffrey A. Ryan

References

Merge Join Discussion: https://blogs.msdn.microsoft.com/craigfr/2006/08/03/merge-join/

Examples

(x <- xts(4:10, Sys.Date()+4:10))
(y <- xts(1:6, Sys.Date()+1:6))

merge(x,y)
merge(x,y, join='inner')
merge(x,y, join='left')
merge(x,y, join='right')

merge.zoo(zoo(x),zoo(y),zoo(x), all=c(TRUE, FALSE, TRUE))
merge(merge(x,x),y,join='left')[,c(1,3,2)]

# zero-width objects (only index values) can be used
xi <- xts( , index(x))
merge(y, xi)

xts

eXtensible Time Series

v0.12.1

GPL (>= 2)

Authors

Jeffrey A. Ryan [aut, cph], Joshua M. Ulrich [cre, aut], Ross Bennett [ctb], Corwin Joy [ctb]

Initial release