plot reference

Declare a plot at top level (plot fast = plot.line(...)) and feed it from handlers with fast.plot(value). A null value leaves a gap. fill.between shades between two plots.

Functions

fill.between

fill.between(a: PlotLine, b: PlotLine, color: color? = null) -> Fill

Creates a fill between two line plots.

a and b must be line plots on the same pane, both using subscribed bars. Other pairs are rejected before the script runs.

color sets the fill color; null uses the theme default. Call fill on each update to draw the fill, optionally passing a different color. Updating either line without calling fill leaves that span unfilled.

Returns Fill

Available in Setup only: declarations, setup and state initialisers.

plot.arrow

plot.arrow(title: string = "", colorUp: color? = null, colorDown: color? = null, minHeight: float? = null, maxHeight: float? = null, paddingPx: float? = null, shaftWidth: float? = null, headLengthPx: float? = null, headWidthRatio: float? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, on: Surface? = null) -> PlotArrow

Creates arrows whose direction and height follow a value.

Positive and negative values choose the direction. A larger absolute value makes a taller arrow. Null skips a bar.

• title names the plot.
• colorUp and colorDown set the direction colors.
• minHeight and maxHeight set the height range, each from 0.0 to 200.0 pixels.
• paddingPx and headLengthPx each accept 0.0 to 50.0 pixels.
• shaftWidth accepts 0.5 to 20.0 pixels.
• headWidthRatio accepts 1.0 to 5.0. Null geometry options use the theme default.
• offset shifts values along the bars, from -500 to 500. Other values are rejected before the script runs.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Null uses the main price pane.

Returns PlotArrow

Available in Setup only: declarations, setup and state initialisers.

plot.bar

plot.bar(title: string = "", color: color? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotBar

Creates an OHLC bar plot.

• title names the plot.
• color sets the bar color. Null uses the theme default.
• offset shifts values along the bars, from -500 to 500. Other values are rejected before the script runs.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Null uses the main price pane.
• capacity accepts 1 to 4096, but does not affect this plot: OHLC bars only support subscribed bars.

Use plot to draw each bar. Placement on a panel with an explicit keyed axis is rejected before the script runs.

Returns PlotBar

Available in Setup only: declarations, setup and state initialisers.

plot.bg

plot.bg(title: string = "", color: color? = null, on: Surface? = null) -> PlotBg

Creates background highlights behind the chart.

title names the plot. color sets the tint; null uses the theme default. on chooses the pane, with null using the main price pane.

Call plot to tint a bar across the full pane height, behind other drawings. Skip the call to leave the bar clear. Background plots only support subscribed bars.

Returns PlotBg

Available in Setup only: declarations, setup and state initialisers.

plot.candle

plot.candle(title: string = "", bodyColor: color? = null, wickColor: color? = null, borderColor: color? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotCandle

Creates a candlestick plot.

• title names the plot.
• bodyColor, wickColor, and borderColor set the candle colors. Null uses the theme default.
• offset shifts values along the bars, from -500 to 500. Other values are rejected before the script runs.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Null uses the main price pane.

Use plot for candles along subscribed bars. On a time-axis panel, use set with your own candle times.

capacity limits keys to 512 by default, with a maximum of 4096. Adding a new key when full stops the script with an error.

Returns PlotCandle

Available in Setup only: declarations, setup and state initialisers.

plot.cells

plot.cells(title: string = "", columns: int = 1, scale: CellScale = cellscale.bar, color: color? = null, borderColor: color? = null, textColor: color? = null, candles: CellCandles = cellcandles.overlay, format: CellFormat = cellformat.compact, decimals: int? = null, sign: bool = false, grouping: bool = false, on: Surface? = null) -> PlotCells

Creates a plot of rows of cells inside each bar, such as a footprint or a per-bar profile.

A cell is a rectangle over a price range inside a bar, with an optional width, colours and a number.

• columns splits each bar into 1 to 4 columns side by side. Other values are rejected before the script runs.
• scale says what a full-width cell means: cellscale.bar the largest weight on its own bar, cellscale.view the largest on the visible bars, cellscale.unit the weight is the width, from 0 to 1.
• color, borderColor and textColor are the defaults of cells that pass none. Without a color or borderColor there is no fill or no border; without a textColor the chart’s text colour is used.
• candles says how the chart’s own candles are drawn while the plot shows on the price pane: cellcandles.overlay as they are, cellcandles.side as a thin strip at the left of each bar, cellcandles.hidden not at all. With several cells plots, hidden wins over side, side over overlay.
• format, decimals (0 to 8), sign and grouping say how a cell’s value is written: 3.21K (compact), 3214.56 (fixed), 15.3% (percent, of a ratio), +3,215 with a sign and grouping. A number that does not fit its cell is written shorter, and left out when nothing fits.
• on chooses the pane. Null is the price pane.

Add cells with cell and empty a bar with clear. A cells plot has no value in the legend and does not change the price scale.

Limits

A bar holds at most 1024 cells per plot. A script keeps 400 000 cells over all its cells plots; beyond that the oldest bars lose theirs first.

Returns PlotCells

Available in Setup only: declarations, setup and state initialisers.

plot.histogram

plot.histogram(title: string = "", color: color? = null, horizontal: bool = false, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotHistogram

Creates a histogram or bar chart.

• title names the plot.
• color sets the bar color. Null uses the theme default.
• horizontal draws sideways bars. It requires an explicit category-axis panel; other placements are rejected before the script runs.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Without it, a vertical histogram uses the script’s shared value pane on the main chart, named after the script.

Use plot(value) for bars along subscribed data or set(key, value) on a panel with an explicit axis. Null leaves a gap with plot or deletes the key with set. Multiple histograms on the same keyed panel form grouped bars. Stacking is not supported.

capacity limits keys to 512 by default, with a maximum of 4096. Adding a new key when full stops the script with an error.

Returns PlotHistogram

Available in Setup only: declarations, setup and state initialisers.

plot.label

plot.label(title: string = "", color: color? = null, size: float? = null, offset: int = 0, on: Surface? = null, anchor: Anchor? = null) -> PlotLabel

Creates a plot of text labels.

• title names the plot.
• color and size set the text appearance. Null uses the theme default. size must be from 6.0 to 48.0, inclusive.
• offset shifts values along the bars, from -500 to 500. Other values are rejected before the script runs.
• on chooses the panel or pane. Null uses the main price pane.

Position

Leave anchor null to position each mark at its plotted value. Use anchor.top or anchor.bottom to pin it to that pane edge instead. The plotted value then sets the distance inward from the edge in logical pixels. Negative distances are allowed, but marks outside the pane are clipped. Edge-anchored marks do not affect the vertical scale or show a legend value. Other anchors are rejected before the script runs.

Use plot to place labels along subscribed bars. For persistent text placed independently of a bar, use a label entity instead.

Returns PlotLabel

Available in Setup only: declarations, setup and state initialisers.

plot.line

plot.line(title: string = "", color: color? = null, width: float? = null, style: LineStyle? = null, area: bool = false, offset: int = 0, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotLine

Creates a line plot.

• title names the plot.
• color, width, and style set its appearance. Null uses the theme default. width must be from 0.0 to 10.0, inclusive.
• area fills between the line and zero, using the line color.
• offset shifts values along the bars, from -500 to 500. Other values are rejected before the script runs.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Null uses the main price pane.

Use plot(value) for values along subscribed bars. On a panel with an explicit axis, use set(key, value). Null leaves a gap with plot or deletes the key with set.

capacity limits keys to 512 by default, with a maximum of 4096. Adding a new key when full stops the script with an error.

Returns PlotLine

Available in Setup only: declarations, setup and state initialisers.

plot.marker

plot.marker(title: string = "", color: color? = null, shape: Shape? = null, size: float? = null, borderWidth: float? = null, borderColor: color? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, on: Surface? = null, anchor: Anchor? = null) -> PlotMarker

Creates a plot of shaped markers.

• title names the plot.
• color, shape, size, borderWidth, and borderColor set the appearance. Null uses the theme default. size must be from 1.0 to 60.0 and borderWidth from 0.0 to 10.0, inclusive.
• offset shifts values along the bars, from -500 to 500. Other values are rejected before the script runs.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Null uses the main price pane.

Position

Leave anchor null to position each mark at its plotted value. Use anchor.top or anchor.bottom to pin it to that pane edge instead. The plotted value then sets the distance inward from the edge in logical pixels. Negative distances are allowed, but marks outside the pane are clipped. Edge-anchored marks do not affect the vertical scale or show a legend value. Other anchors are rejected before the script runs. showLabel and showValue are ignored when anchored to an edge.

Use plot along subscribed bars. Null skips a bar. For a panel with an explicit keyed axis, use a point plot instead.

Returns PlotMarker

Available in Setup only: declarations, setup and state initialisers.

plot.point

plot.point(title: string = "", color: color? = null, size: float? = null, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotPoint

Creates a scatter plot of dots.

• title names the plot.
• color and size set the dots’ appearance. Null uses the theme default. size must be from 0.5 to 30.0, inclusive. Shape and border options are not supported.
• showLabel and showValue control the legend label and value.
• on chooses the panel or pane. Null uses the main price pane.

Use plot(value) for dots along subscribed bars or set(key, value) on a panel with an explicit axis. Null skips a dot with plot or deletes the key with set.

capacity limits keys to 512 by default, with a maximum of 4096. Adding a new key when full stops the script with an error.

Returns PlotPoint

Available in Setup only: declarations, setup and state initialisers.

Methods

fill.fill

fill.fill(color: color? = null, topValue: float? = null, bottomValue: float? = null, topColor: color? = null, bottomColor: color? = null) -> void

Fills between the two lines on the current bar.

Pass color for a solid fill. For a vertical gradient, use topValue and bottomValue to set its positions and topColor and bottomColor for its colors.

Do not mix solid and gradient colors in one call; this is rejected before the script runs. Null colors use the fill default.

Available in Handlers and functions called from handlers.

plot.arrow.plot

plot.arrow.plot(value: float?, colorUp: color? = null, colorDown: color? = null) -> void

Draws an arrow on the current bar.

value sets the arrow’s height and direction; null skips the arrow. colorUp and colorDown override the direction colors, with null keeping each plot default. The plot declaration sets the arrow’s shape and size limits.

Available in Handlers and functions called from handlers.

plot.bar.plot

plot.bar.plot(open: float?, high: float?, low: float?, close: float?, color: color? = null) -> void

Draws an OHLC bar on the current bar.

open, high, low, and close set the bar prices. If any is null, the whole bar is skipped. color overrides its color; null keeps the plot default.

Available in Handlers and functions called from handlers.

plot.bg.plot

plot.bg.plot(color: color? = null) -> void

Tints the pane background on the bar being processed.

color sets the tint for this bar, and null keeps the default. Calling plot marks the bar; not calling it leaves the bar clear.

Available in Handlers and functions called from handlers.

plot.candle.plot

plot.candle.plot(open: float?, high: float?, low: float?, close: float?, bodyColor: color? = null, wickColor: color? = null, borderColor: color? = null) -> void

Draws a candle on the current bar.

open, high, low, and close set the candle prices. If any is null, the whole candle is skipped.

bodyColor, wickColor, and borderColor override its colors. Null keeps each plot default.

Available in Handlers and functions called from handlers.

plot.candle.set

plot.candle.set(key: Key, open: float?, high: float?, low: float?, close: float?, bodyColor: color? = null, wickColor: color? = null, borderColor: color? = null) -> void

Adds or updates a candle at a time key.

key sets the candle time. open, high, low, and close set its prices. If any price is null, the candle is deleted.

bodyColor, wickColor, and borderColor override its colors. Null keeps each plot default. Reuse the same time key to update a custom candle while it forms.

Available in Handlers and functions called from handlers.

plot.cells.cell

plot.cells.cell(from: float?, to: float?, weight: float? = null, color: color? = null, borderColor: color? = null, value: float? = null, textColor: color? = null, column: int = 0, align: Align = align.left, time: time? = null) -> void

Adds a cell to a bar.

from and to are the cell’s price range, in either order. Nothing happens when either is null or they are equal.

• weight is the width, compared as the plot’s scale says. Null fills the column. A weight of zero or less draws no fill; border and text still draw.
• color, borderColor and textColor replace the plot’s defaults.
• value is written in the cell when it fits.
• column chooses the column, from 0. A column the plot does not have stops the script with an error.
• align is the edge the width grows from: align.left, align.right, or align.center for both ways.
• time chooses the bar: null the current one, else the bar whose period contains it. A time after the current bar stops the script with an error.

The first cell or clear for a bar in one calculation step discards what the bar held from earlier steps; further cell calls in the step add to it. A script whose bar can go from having cells to having none calls clear.

Available in Handlers and functions called from handlers.

plot.cells.clear

plot.cells.clear(time: time? = null) -> void

Removes every cell this plot has on a bar.

time chooses the bar as for cell: null the current one. cell calls after clear in the same calculation step add to the emptied bar.

Available in Handlers and functions called from handlers.

plot.histogram.plot

plot.histogram.plot(value: float?, color: color? = null) -> void

Draws a histogram bar on the current bar.

value sets the height from zero; null skips the bar. color overrides its color, with null keeping the plot default.

Available in Handlers and functions called from handlers.

plot.histogram.set

plot.histogram.set(key: Key, value: float?, color: color? = null) -> void

Adds or updates a histogram bar at a key.

key sets the position on the panel’s axis. value sets the height; null deletes the key. color overrides this bar’s color, with null keeping the plot default.

Category axes create bar charts; horizontal makes sideways bars. Multiple histograms on the same panel form grouped bars. Stacking is not supported.

Available in Handlers and functions called from handlers.

plot.label.plot

plot.label.plot(price: float?, text: string, color: color? = null, size: float? = null) -> void

Draws a text label on the current bar.

price sets the position, or the pixel distance from the pane edge when the plot uses an edge anchor. Null skips the label. text supplies the label text; several labels can use the same text.

color and size override its appearance. Null keeps each plot default. A size outside its allowed range stops the script with an error.

Available in Handlers and functions called from handlers.

plot.line.plot

plot.line.plot(value: float?, color: color? = null) -> void

Draws a line value on the current bar.

value sets the price; null leaves a gap. color overrides this point’s color; null keeps the plot default.

Values follow the panel’s time axis: the main chart’s timeframe on the main chart, or the panel’s subscription timeframe in a window. A close handler places the value at the closing candle’s end time.

Available in Handlers and functions called from handlers.

plot.line.set

plot.line.set(key: Key, value: float?, color: color? = null) -> void

Adds or updates a line value at a key.

key sets the position on the panel’s axis. value sets the price; null deletes the key. color overrides this point’s color, with null keeping the plot default.

Plots on the same panel share the axis. Use time keys for a custom time series.

Available in Handlers and functions called from handlers.

plot.marker.plot

plot.marker.plot(value: float?, color: color? = null, shape: Shape? = null, size: float? = null, borderWidth: float? = null, borderColor: color? = null) -> void

Draws a marker on the current bar.

value sets the price, or the pixel distance from the pane edge when the plot uses an edge anchor. Null skips the marker.

color, shape, size, borderWidth, and borderColor override its appearance. Null keeps each plot default. A size or borderWidth outside its allowed range stops the script with an error.

Available in Handlers and functions called from handlers.

plot.point.plot

plot.point.plot(value: float?, color: color? = null, size: float? = null) -> void

Draws a dot on the current bar.

value sets the price; null skips the dot. color and size override the dot’s appearance, with null keeping each plot default. A size outside its allowed range stops the script with an error.

Calling again on the same bar replaces the dot; the last call wins.

Available in Handlers and functions called from handlers.

plot.point.set

plot.point.set(key: Key, value: float?, color: color? = null, size: float? = null) -> void

Adds or updates a dot at a key.

key sets the position on the panel’s axis. value sets the price; null deletes the key. color and size override this dot’s appearance, with null keeping each plot default. A size outside its allowed range stops the script with an error.

Each key has one dot. Calling again with the same key replaces the dot.

Available in Handlers and functions called from handlers.

Constants