ichimoku: 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).


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.


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



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
#>         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() 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:

The returned object has the following specification:

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:

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())


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.


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:

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.


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.

  1. 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
  1. Searches for HLC price data in columns with names containing ‘high’, ‘low’ and ‘close’ (not case-dependent) respectively

  2. 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

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

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:

Changes since version 0.1


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


Further resources

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

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