ichimoku: Reference

Ichimoku Kinko Hyo

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

Tenkan-sen: [conversion line] the mid-point of the highest high and lowest low for the past 9 periods
Kijun-sen: [base line] the mid-point of the highest high and lowest low for the past 26 periods
Senkou span A: [leading span A] the mid-point of Tenkan-sen and Kijun-sen plotted ahead 26 periods
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
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 can be translated as ‘one-glance equilibrium chart’. It is designed to allow the price action and market structure of financial securities to be determined visually ‘at-a-glance’.

For example in a strongly upwards-trending market, the candlesticks would be above the Tenkan-sen, which would be above the Kijun-sen, which in turn would 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.

When the price enters the cloud, i.e. it is between the cloud base and cloud top, it is an important area to guage whether there is sufficient momentum for the price to break through the cloud or whether the cloud eventually provokes a reversal.

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 refinement in candlestick charting techniques, which also originated from Japan back in the 18th century. Actually developed during the mid-20th century, it gained popularity especially from the late 1990s onward, and is now used on trading floors worldwide.

The ichimoku 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 can be freely set in the ‘ichimoku’ package. However please do so only 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 price 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 details see the section file formats.

# ichimoku is designed to interface well with other packages, for example:
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 the type of security.

# Simulated OHLC price data is assigned to data frame 'TKR':
TKR <- sample_ohlc_data
head(TKR)
#>         date  open  high   low close
#> 1 2020-01-02 123.0 123.1 122.5 122.7
#> 2 2020-01-03 122.7 122.8 122.6 122.8
#> 3 2020-01-05 122.8 123.4 122.4 123.3
#> 4 2020-01-06 123.3 124.3 123.3 124.1
#> 5 2020-01-07 124.1 124.8 124.0 124.8
#> 6 2020-01-08 124.8 125.4 124.5 125.3

ichimoku recognises data in columns containing “open”, “high”, “low” and “close”, which do not have to be nicely-formatted as in the example above and could also contain other text such as the ticker name. For further details see the section data validation.

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

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’, ‘xts’ and ‘zoo’.

Optional arguments:

ticker: a ticker to identify the instrument, otherwise this is set to the name of the input object
periods: [default c(9, 26, 52)] a vector defining the length of periods used for the cloud. This parameter should not normally be changed as using other values would be invalid in the context of traditional Ichimoku analysis
… other arguments to be passed along. For instance, to the tradingDays() function, which is used by ichimoku to exclude weekend and holiday dates when calculating the future cloud

The returned object has the following specification:

Index
- date-time index of class ‘POSIXct’
Numeric matrix of 12 columns:
- open, high, low, close (candlestick values)
- cd (candle direction -1 = down, 0 = flat, 1 = up)
- tenkan, kijun, senkouA, senkouB, chikou (ichimoku cloud values)
- cloudTop, cloudBase (note: these are simply the respective max and min of SenkouA and SenkouB at each point in time)
Attributes:
- periods (vector of periods used for calculating the cloud values)
- periodicity (periodicity of the data in seconds)
- ticker (identifier set by default to the input object name or overridden by specifying the ‘ticker’ argument to ichimoku())

cloud <- ichimoku(TKR)

print(cloud[100:110,], plot = FALSE, digits = 4)
#>             open  high   low close cd tenkan kijun senkouA senkouB chikou
#> 2020-04-27 122.7 122.7 121.8 122.4 -1  120.5 123.3   125.6   124.8  135.6
#> 2020-04-28 122.4 122.6 121.1 121.9 -1  120.5 123.3   125.7   124.8  134.5
#> 2020-04-29 121.9 123.7 121.7 123.3  1  120.8 123.2   125.7   124.8  134.3
#> 2020-04-30 123.3 124.0 123.0 124.0  1  121.0 123.2   125.7   124.8  135.9
#> 2020-05-01 124.2 124.3 124.0 124.1 -1  121.4 123.1   125.7   124.8  135.2
#> 2020-05-03 124.1 124.1 123.4 123.9 -1  122.2 123.1   126.0   124.8  135.7
#> 2020-05-04 123.9 124.7 123.7 124.5  1  122.9 123.1   126.5   124.8  135.4
#> 2020-05-05 124.5 124.7 123.9 124.2 -1  122.9 123.0   126.6   124.8  135.7
#> 2020-05-06 124.2 125.2 124.0 124.7  1  123.2 123.0   126.2   124.8  135.6
#> 2020-05-07 124.7 129.8 124.7 129.6  1  125.5 123.9   126.1   124.8  136.2
#> 2020-05-08 129.9 130.6 129.9 130.2  1  126.2 124.3   125.7   124.8  136.5
#>            cloudTop cloudBase
#> 2020-04-27    125.6     124.8
#> 2020-04-28    125.7     124.8
#> 2020-04-29    125.7     124.8
#> 2020-04-30    125.7     124.8
#> 2020-05-01    125.7     124.8
#> 2020-05-03    126.0     124.8
#> 2020-05-04    126.5     124.8
#> 2020-05-05    126.6     124.8
#> 2020-05-06    126.2     124.8
#> 2020-05-07    126.1     124.8
#> 2020-05-08    125.7     124.8

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 data frame to the console.

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

ichimoku() may also be used on an ichimoku object to re-calculate the cloud values using the price data contained within. If ‘ticker’ is specified as an argument, this will overwrite the ticker stored in the original ichimoku object. Running ichimoku() on an ichimoku object containing a strategy will return the ichimoku object to its original state without the strategy. See the strategies vignette for information on strategies.

As an ichimoku object inherits the ‘xts’ and ‘zoo’ classes, all the existing methods for these classes should work seamlessly.

Defining custom holidays

When calculating the future cloud, ichimoku() makes a call to the tradingDays() helper function to ensure that future dates fall on trading days (i.e. not weekends or holidays). By default, New Year’s and Christmas day are defined as holidays as these are practically universal across markets. These defaults should be acceptable for general use.

However, if a particular strategy relies on the specific timing of the future cloud, and for the particular market under consideration other holidays are non-trading days, custom holidays may be defined via a ‘holidays’ argument to ichimoku which is then passed on to the tradingDays() function.

# Holidays can be specified directly via a vector of dates:
ichimoku(TKR, holidays = c("2021-12-25", "2022-01-01"))

# Or via a functions that returns a vector of dates (e.g. from the 'timeDate' package):
ichimoku(TKR, holidays = timeDate::holidayLONDON())
ichimoku(TKR, holidays = timeDate::holidayNYSE())

plot()

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

1. Static Plots

The default plot function produces 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 preferable to call plot() instead, as not only is it more convenient to type but also able to mute the verbose messaging that is otherwise output.

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 most straightforward method would be to assign the output of plot() to a ‘ggplot’ object, after which further elements or layers can be added or modified using ggplot2’s + operator.

# Example code for incrementally updating 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 an informational message. The ‘plotly’ package will not be automatically installed. In this way, interactive charting remains an optional part of the package as it is recognised that plotly may not always be available in all environments.

To produce an interactive plot, use ichimoku’s iplot() function. The interactive plot will be almost identical in format to the equivalent static plot.

# For interactive charting:
iplot(cloud)

In a live analysis environment, as opposed to creating charts for reports, it is usually 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, window = "2020-05-01/2020-11-01", ticker = "TKR Co.", theme = "dark", gaps = TRUE)

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

window: indispensable in a proper workflow. ichimoku() is run on a larger dataset than that of interest and then at the visualization stage, the data can be subset to the window of interest. Supply as an ISO-8601 compatible range string in the format used for ‘xts’ objects, for example the range ‘2020-02-15/2020-08-15’ or ‘2020-02-15/’ (from 15 Feb 2020) or ‘/2020-08’ (until end-Aug 2020) or simply ‘2020’ to select all of the year 2020
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 ‘original’] the following themes are also available: ‘dark’, ‘solarized’ and ‘mono’
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

plot() has the following additional argument, currently unavailable for interactive charting:

strat: [default TRUE] if true, the periods for which a strategy results in a market position will be shaded (if the ichimoku object contains a strategy). See the strategies vignette for more information on working with strategies.

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’ that also inherit the class ‘data.frame’ should also work with ichimoku().

ichimoku has been designed to be fully pipeable and interfaces well with other R packages that return financial data. As an 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 a chart can be created without the need to save intermediate objects:

# Using R 4.1's new pipe operator:
quantmod::getSymbols("C") |> ichimoku() |> plot()
# Or equally using the 'magrittr' pipe:
quantmod::getSymbols("C") %>% ichimoku() %>% plot()

For reading external raw data into R, if the file uses a form of custom delimited format, the fread() function from the ‘data.table’ package on default settings is often successful.

Alternatively, the ‘datapasta’ package allows data copied from website tables 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 price data is of type ‘numeric’ and not coerced to type ‘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.

Searches the row names 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 time-stamp and ichimoku handles this automatically

If not found: searches in column names containing ‘index’, ‘date’ or ‘time’ (not case-dependent) for a time index that is in, or can readily be convertible into, POSIXct format

Searches for HLC price data in columns with names containing ‘high’, ‘low’ and ‘close’ (not case-dependent) respectively
Checks that the length of the medium cloud period is less than that of the dataset. If this is not the case then none of the cloud lines can be calculated
Searches for opening price data in a column with name containing ‘open’ (not case-dependent)

If not found: sets the opening prices to be the closing prices of the previous period

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

The date-time index is in a headerless column, or in a column where the column name does not contain “index”, date“, or”time" (not case-dependent). Please rename the column to “index” in such cases
HLC price data is in headerless columns or in columns labelled, for example, “Op”, Hi“,”Lo“,”Cl“. Please rename the columns”open“,”high“,”low" and “close” in such cases
Imported price data is stored as type ‘character’ rather than ‘numeric’. Please convert the price data to ‘numeric’ in such cases
There are NA values within the price data. This will affect the algorithm calculating the cloud lines in the window immediately following such NA values. Please check the data and manually correct NA values before invoking ichimoku()

Changes since version 0.1

‘ichimoku’ objects now inherit ‘xts’ and ‘zoo’ classes instead of ‘data.frame’. This means that columns extracted from ‘ichimoku’ objects are able to work seamlessly in packages expecting ‘xts’ indexed time series. Conversely for use with packages that only accept data frames then ‘ichimoku’ objects must first be wrapped in as.data.frame()
For candle direction, the column has been renamed from ‘candle’ to ‘cd’ and is now stored as numeric values -1 for ‘down’, 0 for ‘flat’, and 1 for ‘up’, rather than as a factor
plot() now references the new ‘cd’ column as well as new ‘cloudTop’ and ‘cloudBase’ columns to eliminate potential artefacts when drawing the cloud. This means that using plot() on an ichimoku object created in version 0.1.* will no longer work. The solution is to run ichimoku() on the old object to re-create the object according to the new specification (all data is preserved)
The ‘i = TRUE’ argument has been retired from plot() so that both plot() and iplot() now take exactly the same sequence of arguments for ease of use. Use plot() for static charting, iplot() for interactive charting
The ‘from’ and ‘to’ arguments of the plot() and iplot() functions have been replaced by a single argument ‘window’ which takes an ISO-8601 compatible range string and is much more flexible in use, taking full advantage of ichimoku’s switch to the ‘xts’ format