ichimoku: Auxiliary Functions

library(ichimoku)

Introduction

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

Note that all of the auxiliary functions are programmed for performance and are hence stripped of superfluous validation and error-checking code. If they are used outside of their intended scopes then errors can be expected. In particular, the 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:

dates <- seq(from = as.POSIXct("2020-01-01"), by = "1 day", length.out = 7)
dates
#> [1] "2020-01-01 GMT" "2020-01-02 GMT" "2020-01-03 GMT" "2020-01-04 GMT"
#> [5] "2020-01-05 GMT" "2020-01-06 GMT" "2020-01-07 GMT"
tradingDays(dates)
#> [1] FALSE  TRUE  TRUE FALSE FALSE  TRUE  TRUE
tradingDays(dates, holidays = c("2020-01-02", "2020-01-03"))
#> [1]  TRUE FALSE FALSE FALSE FALSE  TRUE  TRUE
tradingDays(dates, holidays = NULL)
#> [1] TRUE TRUE TRUE TRUE TRUE TRUE TRUE

look()

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

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.

cloud <- ichimoku(sample_ohlc_data, ticker = "TKR")
look(cloud)
#> $periods
#> [1]  9 26 52
#> 
#> $periodicity
#> [1] 86400
#> 
#> $ticker
#> [1] "TKR"

grid <- mlgrid(cloud)
look(grid)
#> $y
#> [1] "logret"
#> 
#> $direction
#> [1] "long"
#> 
#> $ticker
#> [1] "TKR"

Can also be used to extract ichimoku objects from lists returned by autostrat(). Specify the argument ‘which’, to return the corresponding element of the list created by autostrat().

stratlist <- autostrat(cloud, n = 3)
#>                        [,1]               [,2]              [,3]             
#> Strategy               "senkouB > tenkan" "cloudB > tenkan" "senkouB > kijun"
#> ---------------------  "----------"       "----------"      "----------"     
#> Strategy cuml return % 17.49              16.08             14.1             
#> Per period mean ret %  0.0906             0.0838            0.0741           
#> Periods in market      63                 51                64               
#> Total trades           3                  3                 3                
#> Average trade length   21                 17                21.33            
#> Trade success %        100                100               100              
#> Worst trade ret %      3.64               3.16              3.49             
#> ---------------------  "----------"       "----------"      "----------"     
#> Benchmark cuml ret %   5.53               5.53              5.53             
#> Per period mean ret %  0.0302             0.0302            0.0302           
#> Periods in market      178                178               178              
#> ---------------------  "----------"       "----------"      "----------"     
#> Direction              "long"             "long"            "long"           
#> Start                  2020-04-20         2020-04-20        2020-04-20       
#> End                    2020-12-23         2020-12-23        2020-12-23       
#> Ticker                 "TKR"              "TKR"             "TKR"

# Extract the ichimoku object which is the second element of 'stratlist':
strat <- look(stratlist, which = 2)

# Inspect ichimoku object:
look(strat)
#> $periods
#> [1]  9 26 52
#> 
#> $periodicity
#> [1] 86400
#> 
#> $ticker
#> [1] "TKR"
#> 
#> $strat
#>                        [,1]             
#> Strategy               "cloudB > tenkan"
#> ---------------------  "----------"     
#> Strategy cuml return % 16.08            
#> Per period mean ret %  0.0838           
#> Periods in market      51               
#> Total trades           3                
#> Average trade length   17               
#> Trade success %        100              
#> Worst trade ret %      3.16             
#> ---------------------  "----------"     
#> Benchmark cuml ret %   5.53             
#> Per period mean ret %  0.0302           
#> Periods in market      178              
#> ---------------------  "----------"     
#> Direction              "long"           
#> Start                  2020-04-20       
#> End                    2020-12-23       
#> Ticker                 "TKR"

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 marginally 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:

cloud <- ichimoku(sample_ohlc_data)
df <- xts_df(cloud)
str(df)
#> 'data.frame':    281 obs. of  13 variables:
#>  $ index  : POSIXct, format: "2020-01-02" "2020-01-03" ...
#>  $ open   : num  123 123 123 123 124 ...
#>  $ high   : num  123 123 123 124 125 ...
#>  $ low    : num  122 123 122 123 124 ...
#>  $ close  : num  123 123 123 124 125 ...
#>  $ cd     : num  -1 1 1 1 1 1 -1 0 -1 -1 ...
#>  $ tenkan : num  NA NA NA NA NA ...
#>  $ kijun  : num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ senkouA: num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ senkouB: num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ chikou : num  123 123 123 124 124 ...
#>  $ cloudT : num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ cloudB : num  NA NA NA NA NA NA NA NA NA NA ...

# Preserving custom attributes:
df2 <- xts_df(cloud, keep.attrs = TRUE)
str(df2)
#> 'data.frame':    281 obs. of  13 variables:
#>  $ index  : POSIXct, format: "2020-01-02" "2020-01-03" ...
#>  $ open   : num  123 123 123 123 124 ...
#>  $ high   : num  123 123 123 124 125 ...
#>  $ low    : num  122 123 122 123 124 ...
#>  $ close  : num  123 123 123 124 125 ...
#>  $ cd     : num  -1 1 1 1 1 1 -1 0 -1 -1 ...
#>  $ tenkan : num  NA NA NA NA NA ...
#>  $ kijun  : num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ senkouA: num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ senkouB: num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ chikou : num  123 123 123 124 124 ...
#>  $ cloudT : num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ cloudB : num  NA NA NA NA NA NA NA NA NA NA ...
#>  - attr(*, "periods")= int [1:3] 9 26 52
#>  - attr(*, "periodicity")= num 86400
#>  - attr(*, "ticker")= chr "sample_ohlc_data"

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:

cloud <- ichimoku(sample_ohlc_data)
mcloud <- as.matrix(cloud)
df <- matrix_df(mcloud)
str(df)
#> 'data.frame':    281 obs. of  12 variables:
#>  $ open   : num  123 123 123 123 124 ...
#>  $ high   : num  123 123 123 124 125 ...
#>  $ low    : num  122 123 122 123 124 ...
#>  $ close  : num  123 123 123 124 125 ...
#>  $ cd     : num  -1 1 1 1 1 1 -1 0 -1 -1 ...
#>  $ tenkan : num  NA NA NA NA NA ...
#>  $ kijun  : num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ senkouA: num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ senkouB: num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ chikou : num  123 123 123 124 124 ...
#>  $ cloudT : num  NA NA NA NA NA NA NA NA NA NA ...
#>  $ cloudB : num  NA NA NA NA NA NA NA NA NA NA ...
str(row.names(df))
#>  chr [1:281] "2020-01-02" "2020-01-03" "2020-01-06" "2020-01-07" ...

Dataframe Utilities

df_trim()

Trim rows containing NA values from a ‘data.frame’ object. This is a faster version of stats::na.omit().

Takes a single argument:

data <- data.frame(c(1:4, NA), c(NA, 2:5))
data
#>   c.1.4..NA. c.NA..2.5.
#> 1          1         NA
#> 2          2          2
#> 3          3          3
#> 4          4          4
#> 5         NA          5
df_trim(data)
#>   c.1.4..NA. c.NA..2.5.
#> 2          2          2
#> 3          3          3
#> 4          4          4

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:

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.

data1 <- sample_ohlc_data[1:6, ]
data1
#>         time  open  high   low close volume
#> 1 2020-01-02 123.0 123.1 122.5 122.7   1875
#> 2 2020-01-03 122.7 122.8 122.6 122.8   1479
#> 3 2020-01-06 122.8 123.4 122.4 123.3   1792
#> 4 2020-01-07 123.3 124.3 123.3 124.1   1977
#> 5 2020-01-08 124.1 124.8 124.0 124.8   2239
#> 6 2020-01-09 124.8 125.4 124.5 125.3   1842
data2 <- sample_ohlc_data[4:10, ]
data2
#>          time  open  high   low close volume
#> 4  2020-01-07 123.3 124.3 123.3 124.1   1977
#> 5  2020-01-08 124.1 124.8 124.0 124.8   2239
#> 6  2020-01-09 124.8 125.4 124.5 125.3   1842
#> 7  2020-01-10 125.3 125.3 124.8 125.2   2548
#> 8  2020-01-13 125.2 125.3 125.1 125.2   2946
#> 9  2020-01-14 125.2 125.2 124.3 124.4   2796
#> 10 2020-01-15 124.4 124.5 123.7 123.9   2879
df_merge(data1, data2)
#>          time  open  high   low close volume
#> 1  2020-01-02 123.0 123.1 122.5 122.7   1875
#> 2  2020-01-03 122.7 122.8 122.6 122.8   1479
#> 3  2020-01-06 122.8 123.4 122.4 123.3   1792
#> 4  2020-01-07 123.3 124.3 123.3 124.1   1977
#> 5  2020-01-08 124.1 124.8 124.0 124.8   2239
#> 6  2020-01-09 124.8 125.4 124.5 125.3   1842
#> 7  2020-01-10 125.3 125.3 124.8 125.2   2548
#> 8  2020-01-13 125.2 125.3 125.1 125.2   2946
#> 9  2020-01-14 125.2 125.2 124.3 124.4   2796
#> 10 2020-01-15 124.4 124.5 123.7 123.9   2879

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:

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 non-essential attributes are dropped.

data1 <- sample_ohlc_data[1:8, ]
data1
#>         time  open  high   low close volume
#> 1 2020-01-02 123.0 123.1 122.5 122.7   1875
#> 2 2020-01-03 122.7 122.8 122.6 122.8   1479
#> 3 2020-01-06 122.8 123.4 122.4 123.3   1792
#> 4 2020-01-07 123.3 124.3 123.3 124.1   1977
#> 5 2020-01-08 124.1 124.8 124.0 124.8   2239
#> 6 2020-01-09 124.8 125.4 124.5 125.3   1842
#> 7 2020-01-10 125.3 125.3 124.8 125.2   2548
#> 8 2020-01-13 125.2 125.3 125.1 125.2   2946
data2 <- sample_ohlc_data[7:10, ]
data2
#>          time  open  high   low close volume
#> 7  2020-01-10 125.3 125.3 124.8 125.2   2548
#> 8  2020-01-13 125.2 125.3 125.1 125.2   2946
#> 9  2020-01-14 125.2 125.2 124.3 124.4   2796
#> 10 2020-01-15 124.4 124.5 123.7 123.9   2879
df_append(data2, data1)
#>          time  open  high   low close volume
#> 1  2020-01-02 123.0 123.1 122.5 122.7   1875
#> 2  2020-01-03 122.7 122.8 122.6 122.8   1479
#> 3  2020-01-06 122.8 123.4 122.4 123.3   1792
#> 4  2020-01-07 123.3 124.3 123.3 124.1   1977
#> 5  2020-01-08 124.1 124.8 124.0 124.8   2239
#> 6  2020-01-09 124.8 125.4 124.5 125.3   1842
#> 7  2020-01-10 125.3 125.3 124.8 125.2   2548
#> 8  2020-01-13 125.2 125.3 125.1 125.2   2946
#> 9  2020-01-14 125.2 125.2 124.3 124.4   2796
#> 10 2020-01-15 124.4 124.5 123.7 123.9   2879

References

Gao, C. (2021), ichimoku: Visualization and Tools for Ichimoku Kinko Hyo Strategies. R package version 1.2.4, https://CRAN.R-project.org/package=ichimoku.