xts (version 0.13.0)

merge.xts: 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 xts
merge(...,
      all = TRUE,
      fill = NA,
      suffixes = NULL,
      join = "outer",
      retside = TRUE,
      retclass = "xts",
      tzone = NULL,
      drop=NULL,
      check.names=NULL)

Value

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

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

Author

Jeffrey A. Ryan

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.

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)