1\name{chartSeries}
2\alias{chartSeries}
3\alias{barChart}
4\alias{candleChart}
5\alias{matchChart}
6\alias{lineChart}
7\alias{reChart}
8\alias{current.chob}
9\title{ Create Financial Charts }
10\description{
11Charting tool to create standard financial charts
12given a time series like object. Serves as the base function for
13future technical analysis additions. Possible chart
14styles include candles, matches (1 pixel candles), bars,
15and lines. Chart may have white or black background.
16
17\code{reChart} allows for dynamic changes to the chart without
18having to respecify the full chart parameters.
19}
20\usage{
21chartSeries(x,
22           type = c("auto", "candlesticks", "matchsticks", "bars","line"),
23           subset = NULL,
24           show.grid = TRUE,
25           name = NULL,
26           time.scale = NULL,
27           log.scale = FALSE,
28           TA = 'addVo()',
29           TAsep=';',
30           line.type = "l",
31           bar.type = "ohlc",
32           theme = chartTheme("black"),
33           layout = NA,
34           major.ticks='auto', minor.ticks=TRUE,
35           yrange=NULL,
36           plot=TRUE,
37           up.col,dn.col,color.vol = TRUE, multi.col = FALSE,
38           ...)
39
40reChart(type = c("auto", "candlesticks", "matchsticks", "bars","line"),
41       subset = NULL,
42       show.grid = TRUE,
43       name = NULL,
44       time.scale = NULL,
45       line.type = "l",
46       bar.type = "ohlc",
47       theme = chartTheme("black"),
48       major.ticks='auto', minor.ticks=TRUE,
49       yrange=NULL,
50       up.col,dn.col,color.vol = TRUE, multi.col = FALSE,
51       ...)
52}
53%- maybe also 'usage' for other objects documented here.
54\arguments{
55  \item{x}{ an OHLC object - see details }
56  \item{type}{ style of chart to draw }
57  \item{subset}{ xts style date subsetting argument }
58  \item{show.grid}{ display price grid lines? }
59  \item{name}{ name of chart }
60  \item{time.scale}{ what is the timescale? automatically deduced (broken) }
61  \item{log.scale}{ should the y-axis be log-scaled? }
62  \item{TA}{ a vector of technical indicators and params, or character strings }
63  \item{TAsep}{ TA delimiter for TA strings }
64  \item{line.type}{ type of line in line chart }
65  \item{bar.type}{ type of barchart - ohlc or hlc }
66  \item{theme}{ a chart.theme object }
67  \item{layout}{ if \code{NULL} bypass internal layout }
68  \item{major.ticks}{ where should major ticks be drawn}
69  \item{minor.ticks}{ should minor ticks be draw? }
70  \item{yrange}{ override y-scale }
71  \item{plot}{ should plot be drawn }
72  \item{up.col}{ up bar/candle color }
73  \item{dn.col}{ down bar/candle color }
74  \item{color.vol}{ color code volume? }
75  \item{multi.col}{ 4 color candle pattern }
76  \item{\dots}{ additional parameters }
77}
78\details{
79Currently displays standard style OHLC charts familiar
80in financial applications, or line charts when
81not passes OHLC data. Works with objects having explicit
82time-series properties.
83
84Line charts are created with close data, or from single
85column time series.
86
87The \code{subset} argument can be used to specify a
88particular area of the series to view.  The underlying
89series is left intact to allow for TA functions to
90use the full data set.  Additionally, it is possible
91to use syntax borrowed from the \code{first} and \code{last}
92functions, e.g. \sQuote{last 4 months}.
93
94\code{TA} allows for the inclusion of a variety of
95chart overlays and tecnical indicators.  A full list is
96available from \code{addTA}. The default TA argument is
97\code{addVo()} - which adds volume, if available, to the
98chart being drawn.
99
100\code{theme} requires an object of class \code{chart.theme}, created
101by a call to \code{chartTheme}.  This function can be used to modify the
102look of the resulting chart.  See \code{chart.theme} for details.
103
104\code{line.type} and \code{bar.type} allow further fine tuning of
105chart styles to user tastes.
106
107\code{multi.col} implements a color coding scheme used in some
108charting applications, and follows the following rules:
109
110\itemize{
111  \item{grey}{ => Op[t] < Cl[t] and Op[t] < Cl[t-1]}
112  \item{white}{ => Op[t] < Cl[t] and Op[t] > Cl[t-1]}
113  \item{red}{   => Op[t] > Cl[t] and Op[t] < Cl[t-1]}
114  \item{black}{ => Op[t] > Cl[t] and Op[t] > Cl[t-1]}
115}
116
117\code{reChart} takes any number of arguments from the original
118chart call --- and redraws the chart with the updated parameters.
119One item of note: if multiple color bars/candles are desired,
120it is necessary to respecify the \code{theme} argument. Additionally
121it is not possible to change TA parameters at present.  This must be
122done with addTA/dropTA/swapTA/moveTA commands.
123}
124\value{
125Returns a standard chart plus volume, if available, suitably scaled.
126
127If \code{plot=FALSE} a chob object will be returned.
128}
129\author{ Jeffrey A. Ryan }
130\references{ Josh Ulrich - \pkg{TTR} package and multi.col coding }
131\note{
132Most details can be fine-tuned within the function, though the code
133does a reasonable job of scaling and labelling axes for the user.
134
135The current implementation maintains a record of actions carried
136out for any particular chart.  This is used to recreate the original when
137adding new indicator.  A list of applied TA actions is available with a call
138to \code{listTA}. This list can be assigned to a variable and used in new
139chart calls to recreate a set of technical indicators.  It is also possible
140to force all future charts to use the same indicators by calling \code{setTA}.
141
142Additional motivation to add outlined candles to allow
143for scaling and advanced color coding is owed to Josh Ulrich, as
144are the base functions (from \pkg{TTR}) for the yet to be
145released technical analysis charting code.
146
147Many improvements in the current version were the result of conversations with
148Gabor Grothendieck.  Many thanks to him.
149}
150\seealso{ \code{\link{getSymbols}}, \code{\link{addTA}}, \code{\link{setTA}},
151          \code{\link{chartTheme}} }
152\examples{
153\dontrun{
154getSymbols("YHOO")
155chartSeries(YHOO)
156chartSeries(YHOO, subset='last 4 months')
157chartSeries(YHOO, subset='2007::2008-01')
158chartSeries(YHOO,theme=chartTheme('white'))
159chartSeries(YHOO,TA=NULL)   #no volume
160chartSeries(YHOO,TA=c(addVo(),addBBands()))  #add volume and Bollinger Bands from TTR
161
162addMACD()   #  add MACD indicator to current chart
163
164setTA()
165chartSeries(YHOO)   #draws chart again, this time will all indicators present
166}
167}
168% Add one or more standard keywords, see file 'KEYWORDS' in the
169% R documentation directory.
170\keyword{ utilities }
171