ichimoku: Cloud Charts - The Reference Manual

Input data requirements

The requirement on the input data is minimal: a series of prices indexed by valid timestamps.

# Sample OHLC price data is assigned to data frame 'TKR':
TKR <- sample_ohlc_data
head(TKR)
#>         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

Date-time index

• Should be POSIXct or in a format convertible to POSIXct

• In a column with name containing ‘date’, ‘time’ or ‘index’, or else the row names of the dataset

Open/High/Low/Close (OHLC) data should always be used where available.

• In columns with names containing ‘open’, ‘high’, ‘low’ and ‘close’. These are searched as regular expression patterns in the column names. For further details see the section data validation

• If only HLC price data is available, the opening price will be taken to be the closing price of the previous period. This means that the candlesticks will not be accurate, but calculation of the cloud lines is not affected

Single series price data can also be used for producing an pseudo cloud chart if, for example, OHLC data is not available or because the price is a calculated price such as VWAP.

• If HLC data is not found in the dataset, the search will then proceed for single series price data in columns with names containing ‘price’, ‘value’, or ‘close’

• A pseudo-OHLC series will then be constructed from the single price. This is done by assigning the opening price to be the closing price of the previous period, and the high and low to be the max and min respectively of the opening and closing prices

• As the constructed OHLC series does not contain real high/low values, the ichimoku cloud chart calculated in this way is not accurate and serves as an approximation only

Note on data retrieval: it is optimal to retrieve data starting from further back than the period being analysed. This is as certain cloud lines are calculated using up to 52 values and then plotted ahead up to 26 periods, and hence there will be only be a full chart with all of the ichimoku cloud values from the 78th observation onwards (using default cloud periods). Call ichimoku() on the full dataset and then subset the data window when plotting to ensure that there is a full cloud for the entire chart.

ichimoku.ichimoku()

ichimoku() may 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.

Calling ichimoku() on an ichimoku object containing a strategy will return the ichimoku object to its original state without the strategy unless keep.data = TRUE is specified. See the strategies vignette for information on strategies.

Preserving Data

The input object may contain additional data not required for ichimoku analysis, such as volume etc. To retain such data in the ichimoku object, specify keep.data = TRUE when calling ichimoku().

kumo <- ichimoku(TKR, keep.data = TRUE)

kumo[, "volume"]
#>  ichimoku   [ more() to display more rows | look() to inspect attributes ]
#>   object
#>            volume
#> 2020-01-02   1875
#> 2020-01-03   1479
#> 2020-01-06   1792
#> 2020-01-07   1977
#> 2020-01-08   2239
#> 2020-01-09   1842
#> 2020-01-10   2548
#> 2020-01-13   2946
#> 2020-01-14   2796
#> 2020-01-15   2879
#> 2020-01-16   2983
#> 2020-01-17   4080
#> 2020-01-20   3584
#> 2020-01-21   2511
#> 2020-01-22   2805
#> 2020-01-23   2853
#> 2020-01-24   2738
#> 2020-01-27   1962
#> 2020-01-28   2795
#> 2020-01-29   2850
#> 2020-01-30   2545
#> 2020-01-31   2608
#> 2020-02-03   2739
#> 2020-02-04   3456
#> 2020-02-05   4037
#> 2020-02-06   4092
#>  [ reached getOption("max.print") -- omitted 27 rows ]

This consolidates all relevant data into a single object. The additional data can now also be plotted as a sub-plot beneath the main ichimoku cloud chart (see custom sub-plots).

Note: only numeric data or data coercible to numeric type is preserved in this way, and other types will introduce NAs. This is as the core data of an ichimoku object is a numeric matrix that does not support multiple data types. Custom attributes set on the input object (such as a timestamp or data source) are also preserved.

Defining custom holidays

When calculating the future cloud for daily data, 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 if the ‘holidays’ argument is not specified. These defaults should be acceptable for general use.

To define other dates as non-trading days, a vector of custom holidays may be supplied via a ‘holidays’ argument to ichimoku() which is then passed on to the tradingDays() function.

If the relevant market trades continuously on a 24/7 basis, specify ‘holidays = NULL’. This will bypass the logic of tradingDays() and return all dates when calculating the future cloud.

# Holidays can be specified directly via a vector of dates:
ichimoku(TKR, holidays = c("2020-01-13", "2020-02-11", "2020-02-24"))

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

# For a market that trades 24/7:
ichimoku(TKR, holidays = NULL)

Working with ichimoku objects

The following generic functions have optimised S3 methods for ichimoku objects:

• as.data.frame() for converting an ichimoku object to a dataframe. Set the argument keep.attrs = TRUE to retain the attributes of the original ichimoku object
• index() to extract the index of an ichimoku object as a vector of POSIXct values
• coredata() to extract the columns of an ichimoku object as a numeric matrix

The below shows how to re-create an ichimoku object from its components:

index <- index(cloud)
core <- coredata(cloud)

cloud2 <- ichimoku(ichimoku(cbind(index, core), ticker = attr(cloud, "ticker")))
#> Warning: Converted numeric values in column 'index' as POSIX times - please
#> check validity
identical(cloud, cloud2)
#> [1] TRUE

Note specifically that ichimoku needs to be called twice - first to convert the matrix resulting from the cbind() operation, and then again to recalculate using the OHLC data contained within the object as the original data would have contained NAs. The ticker name should also be set explicitly as in the example.

A warning is issued about checking the validity of POSIX times, which in this case is safe to ignore as the POSIXct values in ‘index’ were simply coerced to numeric during the cbind() operation and are valid.

For additional functionality, the ‘xts’ package may be loaded to access a wide range of methods available for ‘xts’ objects, for example changing the periodicity of the data.

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.

Call plot() on an ichimoku object to visualize the cloud chart.

The example below demonstrates some of the arguments that can be supplied to customise the plot.

plot(cloud, window = "2020-05/", ticker = "SYM (JSE)", subtitle = "Sample Data Series")

The following arguments for customisation are shared across plot() and iplot():

• window (optional) indispensable in a proper workflow. ichimoku() is run on a larger dataset than that of interest and at the visualization stage the data is 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 (optional) 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
• subtitle (optional) used to specify a subtitle to display under the chart title
• theme [default ‘classic’] with further choices of ‘dark’, ‘mono’, ‘noguchi’, ‘okabe-ito’ or ‘solarized’.
• 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) with the strategy printed as the chart sustitle (if not otherwise specified). See the strategies vignette for more information on working with strategies.
• type [default ‘none’] type of sub-plot to display beneath the ichimoku cloud chart, with a choice of ‘none’, ‘r’ or ‘s’ for the corresponding oscillator type, and ‘bar’ or ‘line’ for custom plots.
• custom (optional) character string (containing a regular expression) matching the column name of the variable to be displayed as sub-plot. Specify type = 'bar' or type = 'line', otherwise other type settings will take precedence.

plot() takes additional parameters as follows:

• ... additional arguments passed along to the print method for ‘ggplot’ objects when type = 'none'.

plot() also permits a user-defined theme, in which case a vector of 12 colour values (hex codes or names) should be supplied. Each colour value corresponds to a different element of the chart. As an example, the ‘mono’ theme can be specified as:

c("#d9d9d9", "#d7d7d7", "#d1d1d1", "#737373", "#1f1f1f", "#b8b8b8", "#1a1a1a", "#1a1a1a", "#1a1a1a", "#ffffff", "#333333", "#1a1a1a")

Oscillators

Although Ichimoku Kinko Hyo is considered a complete charting system, it can at times be useful to pair it with an oscillator.

By specifying type = "r" or type = "s", the corresponding type of oscillator will be shown beneath the main ichimoku cloud chart.

An R-type oscillator is based on the formula for Relative Strength Index (RSI). This is a single line indicator with a look-back window of the ichimoku object’s medium cloud period (default 26).

The R-type line is calculated as 100 - 100 / (1 + [26] period mean open to close gain / the absolute value of the [26] period mean open to close loss).

Note that this corresponds to the usual RSI oscillator definition, although not identical as gains/losses are calculated with reference to each period’s open rather than the previous close. Note also that the R-type oscillator is calculated consistently and does not employ a roll-forward mechanism based on previous oscillator values like the RSI.

# To plot an R-type oscillator:
plot(cloud, type = "r")

An S-type oscillator is based on the formula for the stochastic indicator. This is a 2-line indicator with fast and slow lines with look-back windows corresponding to the fast and medium cloud periods respectively (default 9 and 26). The fast line is quicker to react to price changes and the slow line can be used for confirmation / divergence.

The fast S-type line is calculated as 100 times the ratio of the closing price minus the [9] period low to the [9] period high minus the [9] period low. The slow S-type line is calculated as 100 times the ratio of the closing price minus the [26] period low to the [26] period high minus the [26] period low.

Note the difference to the usual stochastic oscillator definition where the slow line is a 3-period moving average of the fast line.

plot(cloud, window = "2020-04-01/2020-12-01", theme = "solarized", type = "s")

Custom Sub-plots

Additional data preserved within the ichimoku object, for example volume data, can be plotted as a sub-plot by specifying the ‘custom’ argument.

The character string supplied to ‘custom’ is a regular expression pattern that is matched to the column name and hence does not need to match exactly, nor is case considered.

To view a custom sub-plot, type must be specified as either ‘bar’ or ‘line’ as the type setting takes precedence (with a default of ‘none’).

plot(kumo, window = "2020-04/2020-11", theme = "mono", type = "bar", custom = "volume")

Further Options

Internally, ichimoku’s plot() method is a wrapper for autoplot(). To access the ggplot2 object, call autoplot() directly as plot() returns the original ichimoku object (invisibly).

2. Interactive Plots

To produce an interactive plot, use ichimoku’s iplot() function, which launches a Shiny app.

# For an interactive plot:
iplot(cloud)

Further arguments are optional as full customisation of the chart can be done interactively in-app, including selecting the time window, theme, chart type, sub-plot etc.

The cursor infotip provides intuitive access to the data:

• hover over the chart to read off data values at any given point in time
• cursor guides provide easy calibration of date/time and price levels

iplot() takes the following additional parameters for customisation:

• ... additional parameters passed along to the ‘options’ argument of shiny::shinyApp().
• launch.browser [default TRUE] If TRUE, the system’s default web browser will be launched automatically after the app is started. The value of this argument can also be a function to call with the application’s URL. To use the default Shiny viewer in RStudio, specify getOption("shiny.launch.browser").

Implementation notes

The column names of the ichimoku object are automatically populated in a drop-down menu, and a selection can be made to view any variable as a custom sub-plot. Chart type must be set to either ‘bar’ or ‘line’ as the type setting takes precedence.

Writing

archive() for write operations will take 2 arguments: the object to be written, and the file path/name of the file to be stored. If the second argument is left empty, a system dialog will be opened allowing the file save location to be set interactively. A confirmation is printed to the console that the file has been written.

# Write object to file:
archive(object, "path/filename")
# Leave second argument empty to choose file save location from a system dialog:
archive(object, )

Reading

archive() for read operations takes a single argument: the file path/name of the file to be read. Alternatively, if no arguments are specified, a system dialog will be opened allowing a file to be chosen interactively. The return value of the function can be assigned to an object. A confirmation is printed to the console once the file has been read.

# Read from file to object:
object <- archive("path/filename")
# Choose a file from an interactive system dialog:
object <- archive()

Data Integrity Verification

Data integrity verification is performed by the SHA256 cryptographic hash algorithm from the ‘secretbase’ package.

When an archive is written, the serialised object is hashed and the hash is also stored in the archive. The SHA256 hash value is printed to the console as confirmation.

When an archive is read back, the SHA256 hash of the restored object is checked against the hash of the original stored in the archive. If identical, a ‘data verified’ message is printed to the console along with the authenticated SHA256 hash.

Since version 0.x

• ichimoku objects created in v0.x are no longer accepted in v1.0.0 and later of the package. To ensure compatibility with the ichimoku object specification v1, please upgrade to the latest package version and run ichimoku() on previously-created objects to re-create them according to the new specification (data is preserved)