ichimoku: User Reference

Ichimoku Kinko Hyo

The system consists of the following chart lines added to a candlestick chart:

  1. Tenkan-sen: [conversion line] the mid-point of the highest high and lowest low for the past 9 periods.

  2. Kijun-sen: [base line] the mid-point of the highest high and lowest low for the past 26 periods.

  3. Senkou span A: [leading span A] the mid-point of Tenkan-sen and Kijun-sen plotted ahead 26 periods.

  4. Senkou span B: [leading span B] the mid-point of the highest high and lowest low for the past 52 periods, plotted ahead 26 periods.

  5. Chikou span: [lagging span] the current closing price plotted 26 periods behind.

The kumo [cloud] is the area between Senkou span A and Senkou span B (usually shaded on a chart).

Interpretation

Ichimoku Kinko Hyo translates roughly to ‘one-glance equilibrium chart’. It is designed to allow the price action and market structure of financial securities to be determined ‘at-a-glance’ in a highly visual fashion.

For example in a strongly upwards-trending market, the candlesticks will be above the Tenkan-sen, which will be above the Kijun-sen, which will be above the cloud, and the Chikou span may not have anything above it.

The lines and the cloud represent dynamic support and resistance zones relative to the price candles. Generally the thicker the cloud, the tougher the support/resistance. In our previous example, if the price now reverts downwards, it can expect support first at the Kijun-sen, then the Tenkan-sen and finally the cloud itself.

More subtle interpretations involve the Chikou span in particular and its action in relation to the cloud lines as well as the candles.

It is outside the scope of this vignette to provide a full tutorial on the use of Ichimoku Kinko Hyo.

Context

Ichimoku analysis is the latest evolution in refining candlestick charting techniques, which also originated from Japan in the 18th century. Actually developed during the mid-20th century, it gained popularity especially from the late 1990s onwards, and is now used on trading floors worldwide.

The time periods have traditionally been calculated as 9, 26 and 52 based on manual data analysis performed in Japan in a pre-computer age where there was a 6-day working week resulting in 26 average trading days in a month. Although this bears little relevance to the current day, the use of these time periods has persisted as an ‘industry norm’ or ‘accepted practice’. To use other periods would be meaningless in a sense as everyone uses these parameters and ‘market psychology’ can and often does create its own realities, independent of any fundamentals.

However, there is no reason for the technique not to evolve, and to reflect changing trading realities perhaps other parameters will become more relevant in the collective psychology. For this reason, the length of these periods is allowed to be set by the user. However please do so with a strong sense of caution and note that using other periods invalidates the traditional interpretations of Ichimoku Kinko Hyo.

Finally, the use originated with daily candlesticks, and the most valid interpretation remains for daily data. However, it is equally used today for both shorter intra-day, e.g. 4-hour or hourly, and longer, e.g. weekly or monthly, charts.

A Typical Workflow

library(ichimoku)

data

ichimoku works with data frames and tabular data, and interfaces well with other R packages providing financial pricing data. The ichimoku() function is able to handle as input ‘xts’, ‘data.frame’, ‘data.table’, ‘tibble’, ‘matrix’ and possibly other ‘data.frame’ compatible objects. For further detail see the section file formats.

# ichimoku is designed to interface well with other packages, for example the following works:
cloud <- ichimoku(quantmod::getSymbols("C"))

The requirement on the input data is minimal, but it should contain an unambiguous date-time index and also at least High/Low/Close (HLC) price values for each time period. This is as the calculations of the cloud lines use variously the closing price as well as the midpoint between the highs/lows. It is not possible to calculate the ichimoku cloud correctly using just a single price per time period.

Full Open/High/Low/Close (OHLC) data should be used where available as this also allows accurate plotting of the candlesticks. If only HLC price data is available, ichimoku will take the opening price to be the closing price of the previous period, which may or may not be a good assumption depending on type of security.

# Synthetic OHLC pricing data is assigned to data frame 'TKR':
TKR <- sample_ohlc_data
head(TKR)
#>         Date  Open  High   Low Close
#> 1 2020-02-02 144.1 144.3 144.1 144.1
#> 2 2020-02-03 144.1 144.2 143.2 143.4
#> 3 2020-02-04 143.4 143.7 142.9 143.1
#> 4 2020-02-05 143.1 143.4 142.5 142.5
#> 5 2020-02-06 142.5 143.0 141.9 142.0
#> 6 2020-02-07 142.0 143.7 141.8 143.4

ichimoku recognises data in columns containing “Open”, “High”, “Low” and “Close”, which do not have to be as nicely-formatted as in the example above and could also contain the ticker name etc. For further details see the section data validation.

Note: always retrieve as much data as possible, or at least slightly further back than the window desired. Call ichimoku() on the full dataset and then susbset the data when plotting to ensure there is a full ichimoku cloud for all of the desired period. This is better than first subsetting the data and then calculating the ichimoku cloud as there will be NAs and hence no cloud at the start given some of the cloud lines need several values to be calculated.

ichimoku()

ichimoku() is the main function of the ichimoku package. It takes the input data object and returns an ichimoku object, which inherits the classes ‘ichimoku’ and ‘data.frame’.

The returned object is of a consistent format, with the following 11 columns:

The following attributes are also set:

cloud <- ichimoku(TKR)

print(cloud[100:110,], plot = FALSE, row.names = FALSE, digits = 4)
#>        date  open  high   low close candle tenkan kijun senkouA senkouB chikou
#>  2020-05-27 150.9 152.7 150.8 152.6     up  149.6 149.6   147.4   147.1  157.0
#>  2020-05-28 152.6 153.1 151.9 152.1   down  149.8 149.8   147.4   147.1  157.2
#>  2020-05-29 152.1 153.0 151.6 152.8     up  149.9 149.8   147.4   147.1  157.6
#>  2020-05-31 152.8 153.1 152.7 153.1     up  150.3 149.8   148.3   147.4  158.0
#>  2020-06-01 153.1 153.2 151.9 152.1   down  151.1 149.8   148.4   147.4  159.0
#>  2020-06-02 152.1 152.9 152.1 152.3     up  151.4 149.8   148.4   147.4  160.2
#>  2020-06-03 152.3 152.5 151.3 152.4     up  151.4 149.8   148.4   147.4  159.6
#>  2020-06-04 152.4 152.7 152.1 152.5     up  151.4 149.8   148.4   147.4  159.7
#>  2020-06-05 152.5 153.6 152.4 152.8     up  152.2 150.0   148.4   147.5  161.4
#>  2020-06-07 152.8 153.0 152.7 152.9     up  152.4 150.0   148.4   147.5  161.5
#>  2020-06-08 152.9 153.3 152.4 153.0     up  152.4 150.0   148.4   147.5  162.6

A section (rows 100 to 110) of the cloud object is shown above. Note that print is called setting ‘plot = FALSE’ to return the data frame without the plot.

ichimoku objects employ a custom S3 print method which by default plots the cloud chart in the graphical device as well as returning the dataframe to the console. As ichimoku is primarily a visual charting technique, this is almost always the desired outcome.

# to view data as well as chart, simply issue:
cloud

Note: in assignment operations, where the output of ichimoku() is assigned to an object, the behaviour is quiet and nothing is printed (or plotted), as is the usual practice in R.

ichimoku() may also be used on an ichimoku object to re-set its ticker to a new value, but will otherwise just invoke its print() method without re-calculating the cloud values.

As an ichimoku object fully inherits the ‘data.frame’ class, all the existing methods for data frames should work seamlessly.

plot()

ichimoku offers the choice of 2 plotting systems: static (default) and interactive.

1. Static Plots

The default produces publication-ready static plots, which have the advantage of being easily exportable to pdf or image formats in high resolution.

ichimoku implements a custom S3 method for ggplot2’s autoplot() function for objects of class ‘ichimoku’. Although autoplot can be called directly on an ichimoku object, it is practically always better to call plot() instead as it is not only more convenient to type, but also able to mute most of ggplot2’s verbose messaging.

plot(cloud)

As the implementation is via ggplot2, the user is able to further amend or customise the resulting plot using any ggplot2 methods. The easiest way to do this would be to assign the output of plot() to an object, which will inherit the classes ‘gg’ and ‘ggplot’. Further elements or layers can then easily be added or amended using ggplot2’s + and %+replace% operators.

# The following would work if you wanted to add/replace ggplot2 layers:
plot <- plot(cloud)
plot + ggplot2::theme_classic()

2. Interactive Plots

To use fully-interactive charts, the ‘plotly’ package must first be installed. If ‘plotly’ is not available, ichimoku will fall back to a static chart and issue a message, but not automatically install it for you. In this way, interactive charting is a fully optional part of the package as we recognise that ‘plotly’ may not be available in all environments.

To produce an interactive plot, it is possible simply to supply an argument i = TRUE to the plot() function. The interactive plot will be almost identical in format to the equivalent static plot.

Alternatively, directly call ichimoku’s iplot() function, which is (marginally) faster to type and possibly easier to remember. Calling iplot() will prove more reliable over time than having to remember to set a parameter for each plot.

# For interactive charting, take your pick of:
iplot(cloud)
# which is equivalent to:
plot(cloud, i = TRUE)
# which is also equivalent to, using argument position matching and abbreviation of TRUE:
plot(cloud, T)

In a live analysis environment, as opposed to creating charts for reports, it is usually always preferable to work with interactive plots. This is simply due to the ease of use of being able to directly manipulate the chart:

  • hover over the candles or cloud lines to read off values at any given date-time
  • select an area of interest to zoom into
  • double click anywhere to quickly reset

Plot customisation

A plot with default parameters is shown above, but the plot functions contain built-in customisations to allow for most envisioned use cases. The example below demonstrates the arguments that can be supplied to customise the plot.

plot(cloud, from = "2020-05-01", to = "2020-11-01", ticker = "TKR Co.", theme = "dark", gaps = TRUE)

The same arguments are used across plot() and iplot() functions:

  • ‘from’ and ‘to’: indispensible in a proper workflow. ichimoku() is run on a larger dataset than that of interest and then at the plotting stage, the data can be subset to the window of interest
  • ‘ticker’: used to supply a different ticker to that stored in the ichimoku object, or alternatively a longer-form name or other text that will appear in the chart heading
  • ‘theme’: [default ‘default’] the following themes are currently also available: ‘dark’ and ‘solarized’
  • ‘gaps’: [default FALSE] Financial charts are conventionally shown without weekend or holiday gaps for non-trading days. Set to TRUE to use a true continuous time scale which does show these gaps

Troubleshooting

File formats

ichimoku() is a generic function that provides S3 methods for objects of class ‘xts’, ‘data.frame’ and ‘matrix’. Other popular formats such as ‘data.table’ and ‘tibble’ also inherit the class ‘data.frame’ and hence also work with ichimoku().

ichimoku has been designed to be fully pipeable and interfaces well with popular packages that return financial data from the internet. For example, the getSymbols() function from the ‘quantmod’ package exhibits non-standard R behaviour which assigns the data into an object but returns a text string containing the name of the object. ichimoku handles such behaviour automatically such that the following works, allowing us to get from zero to a chart without the need to save intermediate objects:

# The following works:
quantmod::getSymbols("C") %>% ichimoku() %>% plot()

For reading external raw data into R, if the file uses some form of custom delimited format, the fread() function on default settings from the ‘data.table’ package is often successful. Alternatively, the ‘datapasta’ package allows data copied from tables on webpages or in spreadsheets etc. to be pasted into R as a data frame. After importing data, please check that the date-time index is in an unambiguous format (ideally POSIXct), and that the pricing data is of type ‘numeric’ and not ‘character’.

Data validation

ichimoku performs the following data validation steps before attempting to compute the cloud values. Failure at any step causes ichimoku() to halt.

  1. Searches the rownames of the data object for a time index that is in, or can readily be convertible into, POSIXct format. Note: ‘xts’ objects are always indexed by a valid timestamp and ichimoku handles this automatically.

  1. Searches for HLC price data in columns with names containing ‘High’, ‘Low’ and ‘Close’ (not case-dependent) respectively.

  2. Searches for opening price data in a column with name containing ‘Open’ (not case-dependent).

There may be other issues with the input data that prevent the cloud values from being computed, not handled explicitly by ichimoku(). For example:

Please ensure the relevant data columns are appropriately labelled before invoking ichimoku().

Dependencies

The dependency on other packages is designed to be minimised to the extent possible. ichimoku has the following package dependencies:

Optional dependency:

Further resources

Package website: https://shikokuchuo.net/ichimoku/

The most recent version of the package may be found at https://github.com/shikokuchuo/ichimoku/