merge.xts {xts}R Documentation

Merge xts Objects

Description

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

Usage

merge.xts(...,
          all = TRUE,
          fill = NA,
          suffixes = NULL,
          join = "outer",
          retside = TRUE,
          retclass = "xts")

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

Details

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: ‘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. A solution to provide this automatically is in development.

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.

Author(s)

Jeffrey A. Ryan

References

Merge Join Discussion: http://blogs.msdn.com/craigfr/archive/2006/08/03/687584.aspx

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)

[Package xts version 0.6-4 Index]