tq_mutate: Mutates quantitative data (adds new variables to existing tibble)

Description

Mutates quantitative data (adds new variables to existing tibble)

Usage

tq_mutate(data, ohlc_fun = OHLCV, mutate_fun, col_rename = NULL, ...)
tq_mutate_(data, ohlc_fun = "OHLCV", mutate_fun, col_rename = NULL, ...)
tq_mutate_xy(data, x, y = NULL, mutate_fun, col_rename = NULL, ...)
tq_mutate_xy_(data, x, y = NULL, mutate_fun, col_rename = NULL, ...)
tq_mutate_fun_options()

Arguments

data

A tibble (tidy data frame) of data from tq_get.

ohlc_fun

The quantmod function that identifes columns to pass to the mutatation function. OHLCV is quantmod terminology for open, high, low, close, and volume. Options include c(Op, Hi, Lo, Cl, Vo, Ad, HLC, OHLC, OHLCV).

mutate_fun

The mutation function from either the xts, quantmod, or TTR package. Execute tq_mutate_fun_options() to see the full list of options by package.

col_rename

A string or character vector containing names that can be used to quickly rename columns.

...

Additional parameters passed to the appropriate mutatation function.

x, y

Column names of variables to be passed to the mutatation function (instead of OHLC functions).

Value

Returns data in the form of a tibble object.

Details

tq_mutate is a very flexible wrapper for various xts, quantmod and TTR functions. The main advantage is the results are returned as a tibble and the function can be used with the tidyverse.

ohlc_fun is one of the various quantmod Open, High, Low, Close (OHLC) functions. The function returns a column or set of columns from data that are passed to the mutate_fun. In Example 1 below, Cl returns the "close" price and sends this to the mutate function, periodReturn.

mutate_fun is the function that performs the work. In Example 1, this is periodReturn, which calculates the period returns. The ... functions are additional arguments passed to the mutate_fun. Think of the whole operation in Example 1 as the close price, obtained by ohlc_fun = Cl, is being sent to the periodReturn function along with additional arguments defining how to perform the period return, which includes period = "daily" and type = "log".

tq_mutate_xy is designed to enable working with (1) mutatation functions that require two primary inputs (e.g. EVWMA, VWAP, etc) and (2) data that is not in OHLC format. Example 2 shows the first benefit in action: using the EVWMA function that uses volume to defind the moving average period. The two variables do not fall into a single OHLC code (i.e. CV does not exist). The xy form gets us out of this problem. Example 3 shows the second benefit in action: Some functions are useful to non-OHLC data, and defining x = price allows us to mutate WTI crude prices from daily to monthly periodicity.

tq_mutate_ and tq_mutate_xy_ are setup for Non-Standard Evaluation (NSE). This enables programatically changing column names by modifying the text representations. Example 4 shows the difference in implementation. Note that character strings are being passed to the variables instead of unquoted variable names. See vignette("nse") for more information.

Examples

Run this code

# Load libraries
library(tidyquant)

##### Basic Functionality

fb_stock_prices  <- tq_get("FB", get = "stock.prices")

# Example 1: Return logarithmic daily returns using periodReturn()
fb_stock_prices %>%
    tq_mutate(ohlc_fun = Cl, mutate_fun = periodReturn,
              period = "daily", type = "log")

# Example 2: Use tq_mutate_xy to use functions with two columns required
fb_stock_prices %>%
    tq_mutate_xy(x = close, y = volume, mutate_fun = EVWMA,
                 col_rename = "EVWMA")

# Example 3: Using tq_mutate_xy to work with non-OHLC data
tq_get("DCOILWTICO", get = "economic.data") %>%
    tq_mutate_xy(x = price, mutate_fun = lag.xts, k = 1, na.pad = TRUE)

# Example 4: Non-standard evaluation:
# Programming with tq_mutate_() and tq_mutate_xy_()
col_name <- "adjusted"
mutate <- c("MACD", "SMA")
tq_mutate_xy_(fb_stock_prices, x = col_name, mutate_fun = mutate[[1]])