% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/chart.R
\name{chart}
\alias{chart}
\title{Create an OHLC Chart}
\usage{
chart(x, type = "candlestick", idx = NULL, title, ...)
}
\arguments{
\item{x}{An OHLC-V \link{data.frame} (or object coercible to one) with columns
named \code{open}, \code{high}, \code{low}, \code{close}, and optionally \code{volume}. Column
names are case-sensitive.}

\item{type}{A \link{character} string, either \code{"candlestick"} (default) or
\code{"ohlc"}. Candlestick charts use filled/hollow bodies with wicks; OHLC
charts use vertical bars with horizontal open/close ticks.}

\item{idx}{An optional \link{vector} with the same \link{length} as the number of
rows in \code{x}. Replaces the default x-axis labels (row names or integer
index). Useful for custom date formatting or non-standard index types.}

\item{title}{An optional \link{character} string for the chart title. If
omitted, the title is inferred from the variable name passed to \code{x}.}

\item{...}{Additional parameters passed to the backend chart constructor
(e.g., \code{\link[plotly:plot_ly]{plotly::plot_ly()}}).}
}
\value{
A chart object whose class depends on the active backend:
\itemize{
\item \code{"plotly"} backend: a \code{plotly} object (interactive HTML
widget).
\item \code{"ggplot2"} backend: a \code{gg} object (static plot).
}

When called without arguments, returns \code{NULL} invisibly.
}
\description{
\code{chart()} creates interactive candlestick or OHLC bar charts from financial
price data. It initializes the charting environment so that subsequent calls
to \code{\link[=indicator]{indicator()}} can attach technical indicators as subcharts.

Calling \code{chart()} without any arguments resets the charting environment,
clearing all stored chart state (main chart, subcharts, and data).

See \code{vignette(topic = "charting", package = "talib")} for a comprehensive
guide on building multi-panel technical analysis charts.
}
\details{
\code{chart()} acts as the entry point for the package's charting system. It
stores the OHLC data and the main price chart internally so that subsequent
\code{\link[=indicator]{indicator()}} calls can attach panels below the price chart without
requiring the data to be passed again.

The chart title is automatically inferred from the name of the object passed
to \code{x} (e.g., \code{chart(BTC)} produces the title "BTC"). The title also
displays the number of observations and, when available, the date range.

Two rendering backends are supported:
\describe{
\item{\code{"plotly"} (default)}{Produces interactive HTML charts with hover
tooltips, pan/zoom, and built-in drawing tools (lines, rectangles).
Requires the \pkg{plotly} package.}
\item{\code{"ggplot2"}}{Produces static charts suitable for reports and
publications. Requires the \pkg{ggplot2} package.}
}
\subsection{Options}{

The following \code{\link[=options]{options()}} control chart appearance and behavior:

\describe{
\item{\code{talib.chart.backend} [character]}{\code{"plotly"} by default. Set to
\code{"ggplot2"} for static charts.}
\item{\code{talib.chart.slider} [logical]}{\code{FALSE} by default. If \code{TRUE}, a
range slider is added below the x-axis for interactive zooming (plotly
backend only).}
\item{\code{talib.chart.slider.size} [numeric]}{\code{0.05} by default. Controls
the height of the range slider as a fraction of the total chart height.}
\item{\code{talib.chart.legend} [logical]}{\code{TRUE} by default. If \code{FALSE},
legends are hidden on all panels.}
\item{\code{talib.chart.scale} [numeric]}{\code{1} by default. A scaling factor
applied to all font sizes. Values greater than 1 increase font size.}
\item{\code{talib.chart.main} [numeric]}{\code{0.7} by default. The fraction of
total chart height allocated to the main price panel when subcharts
are present.}
}

Colors are controlled via \code{\link[=set_theme]{set_theme()}}. See \code{\link[=set_theme]{set_theme()}} for available
themes and color customization.
}

\subsection{State and concurrency}{

The \code{chart()} + \code{\link[=indicator]{indicator()}} pair follows the same active-target
model as base R's \code{\link[=plot]{plot()}} / \code{\link[=lines]{lines()}}. When \code{chart()} is called it
stashes a per-pipeline state object in its caller's evaluation frame;
subsequent \code{\link[=indicator]{indicator()}} calls retrieve the state by walking up the
call stack.

The practical consequences:
\itemize{
\item \code{chart()} and the subsequent \code{\link[=indicator]{indicator()}} calls must live in the
\strong{same enclosing frame} - the same REPL session, the same function
body, the same \code{renderPlot()} / \code{renderPlotly()} block, the same
\code{local({...})} expression, the same \code{testthat::test_that({...})}
block, etc. Splitting them across unrelated helpers is not
supported.
\item Two unrelated function bodies (or two parallel \code{renderPlot()}
callbacks in a Shiny app, or two \code{future::future()} blocks) each
get their own frame, so their chart states are isolated by
construction - without \code{talib} taking any dependency on Shiny,
promises, or futures.
\item Calling \code{chart()} with no arguments clears the state in the
caller's frame, mirroring a fresh \code{plot()} call on a new device.
}
}
}
\examples{
## charting OHLC data with {talib}
data(BTC, package = "talib")

## candlestick chart (default)
talib::chart(BTC)

## OHLC bar chart
talib::chart(BTC, type = "ohlc")

## chart with a custom title
talib::chart(BTC, title = "Bitcoin / USD")

## reset the charting environment
talib::chart()
}
\seealso{
\code{\link[=indicator]{indicator()}} to attach technical indicators, \code{\link[=set_theme]{set_theme()}} to
customize chart colors.

Other Charting:
\code{\link{chart_themes}},
\code{\link[=indicator]{indicator()}},
\code{\link[=set_theme]{set_theme()}}
}
\author{
Serkan Korkmaz
}
\concept{Charting}
