---
title: "ichimoku: Auxiliary Functions"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{ichimoku: Auxiliary Functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7, fig.height = 5
)
```

```{r setup}
library(ichimoku)
```
## Introduction

This vignette is dedicated to the auxiliary functions exported by the ichimoku package. 

Note that these auxiliary functions are programmed for performance and hence stripped of superfluous validation and error-checking code. If they are used outside of their intended scopes then errors may be expected. In particular, input types must match exactly.

## Core Auxiliary Functions

#### tradingDays()

Used to subset a vector of dates to trading days. Note: if the argument 'holidays' is passed to `ichimoku()`, this is passed through to this function when calculating the dates for the future cloud.

Takes the following arguments:

- `x` a vector of POSIXct dates.
- `holidays` (optional) a vector, or function which outputs a vector, of dates defined as holidays. Set to NULL for a continuously-traded market. If not specified, New Year's and Christmas day are defined as holidays by default.
- `...` other arguments not used by this function.

```{r tradingDays}
dates <- seq(from = as.POSIXct("2020-01-01"), by = "1 day", length.out = 7)
dates
tradingDays(dates)
tradingDays(dates, holidays = c("2020-01-02", "2020-01-03"))
tradingDays(dates, holidays = NULL)
```

#### look()

Can be used to inspect the informational attributes of R objects.

Takes an object as an optional argument. Called without an argument, `.Last.value` will be used instead.

For objects created by the ichimoku package, a list of attributes specific to that data type is returned.

For other objects, a list of attributes that are non-standard for matrix / data.frame / xts objects is returned, or else invisible NULL if none are present.

```{r look}
cloud <- ichimoku(sample_ohlc_data, ticker = "TKR")
look(cloud)

strat <- strat(cloud)
look(strat)

grid <- mlgrid(cloud)
look(grid)
```

## Dataframe Constructors

#### xts_df()

Convert an 'xts' object to 'data.frame'. This function can be an order of magnitude faster than `as.data.frame()` for an 'xts' object.

Note that for ichimoku objects, a slightly faster, more specific version has been implemented as the S3 method for `as.data.frame()`. Hence using this utility on an ichimoku object is not necessary.

Takes the following arguments:

- `x`  the 'xts' object to convert to 'data.frame'.
- `keep.attrs` (optional) if set to TRUE, will preserve any custom attributes set on the original object.

```{r xtsdf}
cloud <- ichimoku(sample_ohlc_data)
df <- xts_df(cloud)
str(df)

# Preserving custom attributes:
df2 <- xts_df(cloud, keep.attrs = TRUE)
str(df2)
```

#### matrix_df()

Convert a matrix to 'data.frame'. This function can be twice as fast as `as.data.frame()` for a matrix.

Takes the following arguments:

- `x`  the matrix to convert to 'data.frame'.
- `keep.attrs` (optional) if set to TRUE, will preserve any custom attributes set on the original object.

```{r matrixdf}
cloud <- ichimoku(sample_ohlc_data)
mcloud <- as.matrix(cloud)
df <- matrix_df(mcloud)
str(df)
str(row.names(df))
```

## Dataframe Utilities

#### df_merge()

Full join on an arbitrary number of 'data.frame' objects passed as arguments, preserving all unique entries. Can be used to combine historical time series data where each observation is indexed by a unique timestamp and all periods are complete.

Takes an arbitrary number of arguments:

- `...`  data.frame objects to combine.

Can be used to join price dataframes retrieved by `oanda()`. The function is designed to join complete historical data. If the data to be merged contains data with incomplete periods, all entries are preserved rather than updated. If incomplete periods are detected within the data, a warning is issued, and the resulting dataframe should be manually inspected in case it contains unwanted duplicates. Use `df_append()` for updating dataframes with new values.

```{r dfmerge}
data1 <- sample_ohlc_data[1:6, ]
data1
data2 <- sample_ohlc_data[4:10, ]
data2
df_merge(data1, data2)
```

#### df_append()

Update a 'data.frame' object with new data. Can be used to append new updated time series data to an existing dataframe, where each observation is indexed by a unique timestamp/identifier in a key column.

Takes 4 arguments:

- `old`  data.frame object containing existing data.
- `new`  data.frame object containing new data.
- `key`  [default 'time'] column name used as key provided as a character string.
- `keep.attr`  [default 'timestamp'] name of an attribute in 'new' to retain, if present, provided as a character string.

Can be used to update price dataframes retrieved by `oanda()`. The function is designed to update existing data with new values as they become available. As opposed to `df_merge()`, the data in 'new' will overwrite the data in 'old' rather than create duplicates.

If the attribute specified by 'keep.attr' is present in 'new', for example the 'timestamp' in pricing data returned by `oanda()`, this is retained. If the attribute is not found in 'new', the argument has no effect. All other custom attributes are dropped.

```{r dfappend}
data1 <- sample_ohlc_data[1:8, ]
data1
data2 <- sample_ohlc_data[7:10, ]
data2
df_append(data1, data2)
```

---