tind (version 0.2.4)

merge: Merging Time-indexed Data

Description

merge method for tind allows to join two (or more) time-indexed datasets also in cases when the indices are of different types. The method is intended for advanced users.

The method takes two tind vectors (x and y) and returns a three-element list containing resulting indices and mappings (integer indices) from the original indices to the final ones allowing to select appropriate rows from dataset indexed by x and y, see Examples.

Usage

# S3 method for tind
merge(x, y, ..., all = FALSE, all.x = all, all.y = all)

Value

A three-element list with the first element (index) containing the final time indices, and the remaining two (xi and yi) mappings from x and y to these indices. If additional time indices are provided, the length of the returned list equals the number of all arguments (including x and y) plus one (for the final index at the beginning of the list).

Arguments

x, y

an object of tind class.

...

(optional) further time indices.

all

a logical value, equivalent to setting both all.x and all.y to the same value. Alternatively, a logical vector in case of more than 2 arguments. See Details.

all.x

a logical value, if TRUE, all x observations are included in the result even if there are no corresponding time indices in y.

all.y

a logical value, analogous to all.x.

Details

By default (all = FALSE), inner join is performed. x and y can be indices of different types but conversion of the higher resolution to the lower should be possible.

If all.x = TRUE, left join is performed. All indices from x are preserved. y can then be of the same or lower resolution than x.

If all.y = TRUE, right join is performed. All indices from y are preserved. x can then be of the same or lower resolution than y.

If all = TRUE, outer join is performed. All indices from x and y are preserved. Indices in x and y have to be of the same type in this case.

Setting all argument silently overrides both all.x and all.y.

NAs are never matched.

The method is optimized in case both indices are strictly increasing without NAs (time series applications). In other cases, it employs merge method for specially constructed data frames.

The method also accepts more than two arguments (time indices). In this case, it is expected that all are strictly increasing without NAs (time series applications only). all.x and all.y cannot be used with more than two arguments.

all can be a vector of logical values indicating which indices have to always be included in the result (TRUE) and which have to be matched (FALSE). In 2-argument case, for example, all = c(TRUE, FALSE) is equivalent to all.x = TRUE and all = c(FALSE, TRUE) to all.y = TRUE.

See Also

match_t for matching time indices.

Examples

# construct sample data frames
(dates1 <- tind(y = 2023, m = rep(1:4, each = 2), d = c(1, 16)))
(dates2 <- dates1 %+m% 1)
(mnths <- as.month("2022-12") + 0:3)
(df1 <- data.frame(dates1, nd1 = as.numeric(dates1),
                   downame = day_of_week(dates1, labels = TRUE, abbreviate = FALSE)))
(df2 <- data.frame(dates2, nd2 = as.numeric(dates2), dow = day_of_week(dates2)))
(df3 <- data.frame(mnths, nm = as.numeric(mnths),
                   mname = month(mnths, labels = TRUE, abbreviate = FALSE)))
# inner join - dates
(mti <- merge(df1[[1L]], df2[[1L]]))
data.frame(index = mti[[1L]],
           df1[mti[[2L]], -1L, drop = FALSE],
           df2[mti[[3L]], -1L, drop = FALSE])
# inner join - dates and months
(mti <- merge(df1[[1L]], df3[[1L]]))
data.frame(index = mti[[1L]],
           df1[mti[[2L]], -1L, drop = FALSE],
           df3[mti[[3L]], -1L, drop = FALSE])
# left join - dates
(mti <- merge(df1[[1L]], df2[[1L]], all.x = TRUE))
data.frame(index = mti[[1L]],
           df1[mti[[2L]], -1L, drop = FALSE],
           df2[mti[[3L]], -1L, drop = FALSE])
# left join - dates and months
(mti <- merge(df1[[1L]], df3[[1L]], all.x = TRUE))
data.frame(index = mti[[1L]],
           df1[mti[[2L]], -1L, drop = FALSE],
           df3[mti[[3L]], -1L, drop = FALSE])
# right join - dates
(mti <- merge(df1[[1L]], df2[[1L]], all.y = TRUE))
data.frame(index = mti[[1L]],
           df1[mti[[2L]], -1L, drop = FALSE],
           df2[mti[[3L]], -1L, drop = FALSE])
# right join - months and dates
(mti <- merge(df3[[1L]], df2[[1L]], all.y = TRUE))
data.frame(index = mti[[1L]],
           df3[mti[[2L]], -1L, drop = FALSE],
           df2[mti[[3L]], -1L, drop = FALSE])
# outer join - dates
(mti <- merge(df1[[1L]], df2[[1L]], all = TRUE))
data.frame(index = mti[[1L]],
           df1[mti[[2L]], -1L, drop = FALSE],
           df2[mti[[3L]], -1L, drop = FALSE])