R: Merge xts Objects

merge.xts {xts} | R Documentation

## 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)

[Package xts version 0.10-1 Index]