Perform merge operations on xts objects by time index.
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
Suffix to be added to merged column names.
- join
Type of database join. One of 'outer', 'inner', 'left', or 'right'.
- retside
Which side of the merged object should be returned (2-case only)?
- retclass
Either a logical value indicating whether the result should have a 'class' attribute, or the name of the desired class for the result.
- tzone
Time zone to use for the merged result.
- drop
Not currently used.
- check.names
Use
make.names()to ensure column names are vaild R object names?
Details
This xts method is compatible with zoo's merge() method but implemented almost entirely in C-level code for efficiency.
The function can perform all common database join operations along the time index by setting 'join' to one of the values below. Note that 'left' and 'right' are only implemented for two objects.
outer: full outer (all rows in all objects)
inner: only rows with common indexes in all objects
left: all rows in the first object, and rows from the second object that have the same index as the first object
right: all rows in the second object, and rows from the first object that have the same index as the second object
The above join types can also be accomplished by setting 'all' to one of the values below.
outer:
all = TRUEorall = c(TRUE, TRUE)inner:
all = FALSEorall = c(FALSE, FALSE)left:
all = c(TRUE, FALSE)right:
all = c(FALSE, TRUE)
The result will have the timezone of the leftmost argument if available. Use the 'tzone' argument to override the default behavior.
When retclass = 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, but unused by xts. When retclass = FALSE
the object will be stripped of its class attribute. This is for internal use.
See the examples in order to join using an 'all' argument that is the same
arguments to join, like you can do with merge.zoo().
Note
This is a highly optimized merge, specifically designed for ordered data. The only supported merging is based on the underlying time index.
References
Merge Join Discussion: https://learn.microsoft.com/en-us/archive/blogs/craigfr/merge-join
Examples
(x <- xts(4:10, Sys.Date()+4:10))
#> [,1]
#> 2026-03-09 4
#> 2026-03-10 5
#> 2026-03-11 6
#> 2026-03-12 7
#> 2026-03-13 8
#> 2026-03-14 9
#> 2026-03-15 10
(y <- xts(1:6, Sys.Date()+1:6))
#> [,1]
#> 2026-03-06 1
#> 2026-03-07 2
#> 2026-03-08 3
#> 2026-03-09 4
#> 2026-03-10 5
#> 2026-03-11 6
merge(x,y)
#> x y
#> 2026-03-06 NA 1
#> 2026-03-07 NA 2
#> 2026-03-08 NA 3
#> 2026-03-09 4 4
#> 2026-03-10 5 5
#> 2026-03-11 6 6
#> 2026-03-12 7 NA
#> 2026-03-13 8 NA
#> 2026-03-14 9 NA
#> 2026-03-15 10 NA
merge(x,y, join='inner')
#> x y
#> 2026-03-09 4 4
#> 2026-03-10 5 5
#> 2026-03-11 6 6
merge(x,y, join='left')
#> x y
#> 2026-03-09 4 4
#> 2026-03-10 5 5
#> 2026-03-11 6 6
#> 2026-03-12 7 NA
#> 2026-03-13 8 NA
#> 2026-03-14 9 NA
#> 2026-03-15 10 NA
merge(x,y, join='right')
#> x y
#> 2026-03-06 NA 1
#> 2026-03-07 NA 2
#> 2026-03-08 NA 3
#> 2026-03-09 4 4
#> 2026-03-10 5 5
#> 2026-03-11 6 6
merge.zoo(zoo(x),zoo(y),zoo(x), all=c(TRUE, FALSE, TRUE))
#> x.zoo(x) x.zoo(y) x.zoo(x)
#> 2026-03-09 4 4 4
#> 2026-03-10 5 5 5
#> 2026-03-11 6 6 6
#> 2026-03-12 7 NA 7
#> 2026-03-13 8 NA 8
#> 2026-03-14 9 NA 9
#> 2026-03-15 10 NA 10
merge(merge(x,x),y,join='left')[,c(1,3,2)]
#> x y x.1
#> 2026-03-09 4 4 4
#> 2026-03-10 5 5 5
#> 2026-03-11 6 6 6
#> 2026-03-12 7 NA 7
#> 2026-03-13 8 NA 8
#> 2026-03-14 9 NA 9
#> 2026-03-15 10 NA 10
# zero-width objects (only index values) can be used
xi <- xts( , index(x))
merge(y, xi)
#> y
#> 2026-03-06 1
#> 2026-03-07 2
#> 2026-03-08 3
#> 2026-03-09 4
#> 2026-03-10 5
#> 2026-03-11 6
#> 2026-03-12 NA
#> 2026-03-13 NA
#> 2026-03-14 NA
#> 2026-03-15 NA