R: Mutates quantitative data

tq_mutate {tidyquant} | R Documentation

## Mutates quantitative data

### Description

`tq_mutate()` adds new variables to an existing tibble; `tq_transmute()` returns only newly created columns and is typically used when periodicity changes

### Usage

    tq_mutate(
      data,
      select = NULL,
      mutate_fun,
      col_rename = NULL,
      ohlc_fun = NULL,
      ...
    )

    tq_mutate_(data, select = NULL, 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()

    tq_transmute(
      data,
      select = NULL,
      mutate_fun,
      col_rename = NULL,
      ohlc_fun = NULL,
      ...
    )

    tq_transmute_(data, select = NULL, mutate_fun, col_rename = NULL, ...)

    tq_transmute_xy(data, x, y = NULL, mutate_fun, col_rename = NULL, ...)

    tq_transmute_xy_(data, x, y = NULL, mutate_fun, col_rename = NULL, ...)

    tq_transmute_fun_options()

### Arguments

`data` | A `tibble` (tidy data frame) of data typically from `tq_get()`.
`select` | The columns to send to the mutation function.
`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.
`ohlc_fun` | Deprecated. Use `select`.
`...` | Additional parameters passed to the appropriate mutatation function.
`x, y` | Parameters used with `_xy` that consist of column names of variables to be passed to the mutatation function (instead of OHLC functions).

### Details

`tq_mutate` and `tq_transmute` are very flexible wrappers 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`. `tq_mutate` is used when additional columns are added to the return data frame. `tq_transmute` works exactly like `tq_mutate` except it only returns the newly created columns. This is helpful when changing periodicity where the new columns would not have the same number of rows as the original tibble.

`select` specifies the columns that get passed to the mutation function. Select works as a more flexible version of the OHLC extractor functions from `quantmod` where non-OHLC data works as well. When `select` is `NULL`, all columns are selected. In Example 1 below, `close` 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 `...` are additional arguments passed to the `mutate_fun`. Think of the whole operation in Example 1 as the close price, obtained by `select = close`, being sent to the `periodReturn` function along with additional arguments defining how to perform the period return, which includes `period = "daily"` and `type = "log"`. Example 4 shows how to apply a rolling regression.

`tq_mutate_xy` and `tq_transmute_xy` are designed to enable working with mutatation functions that require two primary inputs (e.g. EVWMA, VWAP, etc). Example 2 shows this benefit in action: using the EVWMA function that uses volume to define the moving average period.

`tq_mutate_`, `tq_mutate_xy_`, `tq_transmute_`, and `tq_transmute_xy_` are setup for Non-Standard Evaluation (NSE). This enables programatically changing column names by modifying the text representations. Example 5 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.

`tq_mutate_fun_options` and `tq_transmute_fun_options` return a list of various financial functions that are compatible with `tq_mutate` and `tq_transmute`, respectively.

### Value

Returns mutated data in the form of a `tibble` object.

### See Also

`tq_get()`

### Examples

    # Load libraries
    library(tidyquant)
    library(dplyr)

    ##### Basic Functionality

    fb_stock_prices  <- tq_get("FB",
                               get  = "stock.prices",
                               from = "2016-01-01",
                               to   = "2016-12-31")

    # Example 1: Return logarithmic daily returns using periodReturn()
    fb_stock_prices %>%
        tq_mutate(select = close, 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 to work with non-OHLC data
    tq_get("DCOILWTICO", get = "economic.data") %>%
        tq_mutate(select = price, mutate_fun = lag.xts, k = 1, na.pad = TRUE)

    # Example 4: Using tq_mutate to apply a rolling regression
    fb_returns <- fb_stock_prices %>%
        tq_transmute(adjusted, periodReturn, period = "monthly", col_rename = "fb.returns")
    xlk_returns <- tq_get("XLK", from = "2016-01-01", to = "2016-12-31") %>%
        tq_transmute(adjusted, periodReturn, period = "monthly", col_rename = "xlk.returns")
    returns_combined <- left_join(fb_returns, xlk_returns, by = "date")
    regr_fun <- function(data) {
        coef(lm(fb.returns ~ xlk.returns, data = as_tibble(data)))
    }
    returns_combined %>%
        tq_mutate(mutate_fun = rollapply,
                  width      = 6,
                  FUN        = regr_fun,
                  by.column  = FALSE,
                  col_rename = c("coef.0", "coef.1"))

    # Example 5: 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]])

[Package tidyquant version 0.5.10 Index]