plot reference

Declares plot outputs and updates them with stream or keyed rows.

Accepted values

These named values are the complete choices accepted by parameters of each type.

`CellCandles`

ValueMeaning

cellcandles.overlayThe chart's candles are drawn as usual, behind the cells.

cellcandles.sideThe chart's candles are drawn as a thin strip at the left edge of each bar, beside the cells.

cellcandles.hiddenThe chart's candles are not drawn.

`CellFormat`

ValueMeaning

cellformat.compactLarge numbers are shortened with a suffix, such as 3.21K or 53.1M.

cellformat.fixedThe number is written in full, such as 3214.56.

cellformat.percentThe value is a ratio written as a percentage, so 0.153 reads 15.3%.

`CellScale`

ValueMeaning

cellscale.barA full-width cell has the largest weight on its own bar.

cellscale.viewA full-width cell has the largest weight on the visible bars.

cellscale.unitThe weight is the width itself, as a fraction from 0 to 1.

`Extend`

PreviewValueMeaning

extend.noneEntity does not extend beyond its x-range.

extend.leftEntity extends leftward past its leftmost endpoint along its slope.

extend.rightEntity extends rightward past its rightmost endpoint along its slope.

extend.bothEntity extends in both directions.

extend.upLine or box extends upward past its topmost endpoint to the pane edge.

extend.downLine or box extends downward past its bottommost endpoint to the pane edge.

extend.verticalLine or box extends both upward and downward to the pane edges.

`LineStyle`

PreviewValueMeaning

linestyle.solidSolid line style.

linestyle.dottedDotted line style.

linestyle.dashedDashed line style.

linestyle.stepStep line style.

`Shape`

PreviewValueMeaning

shape.circleCircle marker shape.

shape.squareSquare marker shape.

shape.diamondDiamond marker shape.

shape.upUp-triangle marker shape.

shape.downDown-triangle marker shape.

shape.leftLeft-triangle marker shape.

shape.rightRight-triangle marker shape.

shape.crossCross marker shape.

shape.plusPlus marker shape.

shape.asteriskAsterisk marker shape.

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

Contracts

width: Accepted range: 0.0 to 10.0. Must be a finite number. Invalid values are rejected.
offset: Accepted range: -500 to 500. Invalid values are rejected.
capacity: Accepted range: 1 to 4096. Invalid values are rejected.

Example

script "Line Plot"
data chart = subscribe(data.ohlcv)
plot ma = plot.line(title: "MA", color: color.blue, width: 2.0)

on chart.update {
  ma.plot(ta.sma(chart.close, 20))
}

Accepted values

style: LineStyle values — 4 available.

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

Contracts

capacity: Accepted range: 1 to 4096. Invalid values are rejected.

Example

script "Venue Volume"
data bars = subscribe(data.ohlcv)
window win = window(title: "Venues") {
  byVenue: chart.panel(axis: axis.category),
}
plot vol = plot.histogram(title: "Volume", on: win.byVenue)

on bars.update {
  vol.set("OKX", bars.volume)
}

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

Contracts

size: Accepted range: 0.5 to 30.0. Must be a finite number. Invalid values are rejected.
capacity: Accepted range: 1 to 4096. Invalid values are rejected.

Example

script "Point Plot"
data chart = subscribe(data.ohlcv)
plot dots = plot.point(title: "Signal", size: 4.0)

on chart.update {
  dots.plot(chart.close)
}

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

Contracts

offset: Accepted range: -500 to 500. Invalid values are rejected.
capacity: Accepted range: 1 to 4096. Invalid values are rejected.

Example

script "Candle Plot"
data chart = subscribe(data.ohlcv)
plot ha = plot.candle(title: "HA")

on chart.update {
  ha.plot(chart.open, chart.high, chart.low, chart.close)
}

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

Contracts

offset: Accepted range: -500 to 500. Invalid values are rejected.
capacity: Accepted range: 1 to 4096. Invalid values are rejected.

Example

script "Bar Plot"
data chart = subscribe(data.ohlcv)
plot bars = plot.bar(title: "Bars")

on chart.update {
  bars.plot(chart.open, chart.high, chart.low, chart.close)
}

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

Contracts

size: Accepted range: 1.0 to 60.0. Must be a finite number. Invalid values are rejected.
borderWidth: Accepted range: 0.0 to 10.0. Must be a finite number. Invalid values are rejected.
offset: Accepted range: -500 to 500. Invalid values are rejected.

Example

script "Marker Plot"
data chart = subscribe(data.ohlcv)
plot crossUp = plot.marker(title: "Cross", shape: shape.up, color: color.green)

on chart.update {
  if chart.close > chart.open { crossUp.plot(chart.low) }
}

Accepted values

anchor: Anchor values — 13 available.
shape: Shape values — 10 available.

`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

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

Contracts

size: Accepted range: 6.0 to 48.0. Must be a finite number. Invalid values are rejected.
offset: Accepted range: -500 to 500. Invalid values are rejected.

Example

script "Label Plot"
data chart = subscribe(data.ohlcv)
plot tag = plot.label(title: "Pivot", size: 11.0)

on chart.update {
  if chart.high > chart.high[1] { tag.plot(chart.high, "H") }
}

Accepted values

anchor: Anchor values — 13 available.

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

Contracts

minHeight: Accepted range: 0.0 to 200.0. Must be a finite number. Invalid values are rejected.
maxHeight: Accepted range: 0.0 to 200.0. Must be a finite number. Invalid values are rejected.
paddingPx: Accepted range: 0.0 to 50.0. Must be a finite number. Invalid values are rejected.
shaftWidth: Accepted range: 0.5 to 20.0. Must be a finite number. Invalid values are rejected.
headLengthPx: Accepted range: 0.0 to 50.0. Must be a finite number. Invalid values are rejected.
headWidthRatio: Accepted range: 1.0 to 5.0. Must be a finite number. Invalid values are rejected.
offset: Accepted range: -500 to 500. Invalid values are rejected.

Example

script "Arrow Plot"
data chart = subscribe(data.ohlcv)
plot flow = plot.arrow(title: "Delta", colorUp: color.green, colorDown: color.red)

on chart.update {
  flow.plot((chart.buyVolume ?? 0.0) - (chart.sellVolume ?? 0.0))
}

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

Example

script "Background Plot"
data chart = subscribe(data.ohlcv)
plot session = plot.bg(title: "US hours")

on chart.update {
  if chart.isNew { session.plot(color: color.rgb(64, 128, 255, 24)) }
}

`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 per-bar cell rows, such as a footprint or a per-bar profile.

Each bar holds rows of cells. A cell is a rectangle covering a price range inside the bar, with an optional width, colors, and a number shown as text.

title names the plot.
columns splits each bar into 1 to 4 side-by-side columns. Other values are rejected before the script runs.
scale chooses what a full-width cell means. cellscale.bar compares each cell with the largest weight on its own bar, cellscale.view with the largest weight on the visible bars, and cellscale.unit treats the weight as a fraction from 0 to 1.
color, borderColor, and textColor set the defaults for cells that do not pass their own. A null color or borderColor draws no fill or no border. A null textColor uses the chart's text color.
candles chooses how the chart's own candles are drawn while this plot is visible on the main price pane. cellcandles.overlay leaves them as they are, behind the cells. cellcandles.side draws them as a thin strip at the left edge of each bar, beside the cells. cellcandles.hidden does not draw them. The cells are drawn in the same place in every mode. It has no effect on any other pane.
format chooses how the value of a cell is written. cellformat.compact shortens large numbers with a suffix, so 3214.56 reads 3.21K. cellformat.fixed writes the number in full. cellformat.percent treats the value as a ratio, so 0.153 reads 15.3%.
decimals is the number of digits after the decimal point, from 0 to 8. Other values are rejected before the script runs. Null, the default, lets the chart choose. cellformat.fixed and cellformat.percent always write that many digits, so the cells of a column line up. cellformat.compact writes at most that many and drops trailing zeros.
sign writes a + before values above zero.
grouping separates thousands with commas, so 53100000 reads 53,100,000. It applies to cellformat.fixed and cellformat.percent only.
on chooses the pane. Null uses the main price pane. A panel with an explicit keyed axis is rejected before the script runs.

Use cell to add cells to a bar and clear to empty one. The legend shows no value for a cells plot, and cells on the price pane do not change its vertical scale.

The chart's candles keep setting the price scale, the crosshair, and the legend whatever candles is; only their drawing changes. A chart that does not draw its main series as candles or bars is not affected, and neither is a plot.candle plot. When several visible cells plots on the main price pane ask for different modes, cellcandles.hidden wins over cellcandles.side, which wins over cellcandles.overlay.

The number format applies to every cell of the plot. It is the most detail a cell shows: when the text does not fit, the chart writes the cells of that bar with fewer digits, and shows no text only when nothing fits. Numbers are rounded half away from zero, and a value that rounds to zero is written without a sign. A cell stores its value with about seven significant digits.

Limits

Each bar holds at most 1024 cells per plot; further cells on that bar are not drawn. A script keeps a limited total number of cells across all of its cells plots, set by your plan. When the total is reached the oldest bars lose their cells first, so the most recent bars always stay drawn.

Contracts

columns: Accepted range: 1 to 4. Invalid values are rejected.
decimals: Accepted range: 0 to 8. Invalid values are rejected.

Example

script "Cells Plot"
data chart = subscribe(data.ohlcv)
plot fp = plot.cells(title: "Range", columns: 2)

on chart.update {
  let mid = (chart.high + chart.low) / 2.0
  fp.clear()
  fp.cell(chart.low, mid, weight: chart.sellVolume, color: color.red,
          column: 0, align: align.right)
  fp.cell(mid, chart.high, weight: chart.buyVolume, color: color.green, column: 1)
}

Accepted values

candles: CellCandles values — 3 available.
format: CellFormat values — 3 available.
scale: CellScale values — 3 available.

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

Example

script "Line Fill"
data chart = subscribe(data.ohlcv)
plot upper = plot.line(title: "Upper")
plot lower = plot.line(title: "Lower")
fill band = fill.between(upper, lower, color: color.rgb(33, 150, 243, 32))

on chart.update {
  upper.plot(chart.high)
  lower.plot(chart.low)
  band.fill()
}

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

Example

script "Line Emit"
data chart = subscribe(data.ohlcv)
plot ma = plot.line(title: "MA")

on chart.update {
  ma.plot(ta.sma(chart.close, 20), color: color.blue)
}

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

Example

script "Histogram Emit"
data chart = subscribe(data.ohlcv)
plot delta = plot.histogram(title: "Delta")

on chart.update {
  let net = (chart.buyVolume ?? 0.0) - (chart.sellVolume ?? 0.0)
  delta.plot(net, color: net >= 0.0 ? color.green : color.red)
}

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

Contracts

size: Accepted range: 0.5 to 30.0. Must be a finite number. Invalid values are rejected.

Example

script "Point Emit"
data chart = subscribe(data.ohlcv)
plot dots = plot.point(title: "VWAP Band")

on chart.update {
  dots.plot(chart.close, size: 2.0)
}

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

Example

script "Candle Emit"
data chart = subscribe(data.ohlcv)
plot candles = plot.candle(title: "Source")

on chart.update {
  candles.plot(chart.open, chart.high, chart.low, chart.close)
}

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

Example

script "Bar Emit"
data chart = subscribe(data.ohlcv)
plot bars = plot.bar(title: "Dual-color bars")

on chart.update {
  let barColor = chart.close >= chart.open ? color.up : color.down
  bars.plot(chart.open, chart.high, chart.low, chart.close, color: barColor)
}

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

Contracts

size: Accepted range: 1.0 to 60.0. Must be a finite number. Invalid values are rejected.
borderWidth: Accepted range: 0.0 to 10.0. Must be a finite number. Invalid values are rejected.

Example

script "Marker Emit"
data chart = subscribe(data.ohlcv)
plot crossUp = plot.marker(title: "Cross", shape: shape.up)

on chart.update {
  if chart.close > chart.open { crossUp.plot(chart.low, shape: shape.up) }
}

Accepted values

shape: Shape values — 10 available.

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

Contracts

size: Accepted range: 6.0 to 48.0. Must be a finite number. Invalid values are rejected.

Example

script "Label Emit"
data chart = subscribe(data.ohlcv)
plot tag = plot.label(title: "Range")

on chart.update {
  tag.plot(chart.high, str.format("range={0}", chart.high - chart.low))
}

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

Example

script "Arrow Emit"
data chart = subscribe(data.ohlcv)
plot flow = plot.arrow(title: "Flow")

on chart.update {
  flow.plot((chart.buyVolume ?? 0.0) - (chart.sellVolume ?? 0.0))
}

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

Example

script "Background Emit"
data chart = subscribe(data.ohlcv)
plot session = plot.bg(title: "Open")

on chart.update {
  if chart.isNew { session.plot() }
}

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

Example

script "Fill Emit"
data chart = subscribe(data.ohlcv)
plot upper = plot.line(title: "Upper")
plot lower = plot.line(title: "Lower")
fill band = fill.between(upper, lower)

on chart.update {
  upper.plot(chart.high)
  lower.plot(chart.low)
  band.fill(color: color.rgb(33, 150, 243, 32))
}

`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 set the cell's price range, in either order. The call does nothing when either is null or not finite, or when they are equal.

weight sets the width, compared as the plot's scale says. Null fills the column. A weight that is zero, negative, or not finite draws no fill; the border and text still draw.
color, borderColor, and textColor override the plot defaults. Null keeps each default.
value is shown as text inside the cell when it fits. Null shows no text.
column chooses the column, counting from 0. A column the plot does not have stops the script with an error.
align chooses the edge the width grows from: align.left, align.right, or align.center to grow both ways.
time chooses the bar. Null uses the current bar. Any other time selects the bar whose period contains it. A time after the current bar stops the script with an error. A time outside the bars still kept does nothing.

The first cell or clear for a bar during one calculation step discards the cells that bar had from earlier steps. Further cell calls in the same step add to it. A script whose bar can go from having cells to having none calls clear, otherwise the earlier cells stay.

A handler that runs when a period closes writes to the bar that opens next. To draw on the closed period, pass that period's own time.

Contracts

column: Accepted range: 0 to 3. Invalid values are rejected.

Example

script "Cell Emit"
data chart = subscribe(data.ohlcv)
data vol = subscribe(data.volume)
plot fp = plot.cells(title: "Footprint", columns: 2)

on chart.update {
  let rows = vol.bucketsByStep(25.0)
  if rows != null {
    fp.clear(time: rows.time)
    for r in rows {
      fp.cell(r.from, r.to, weight: r.sell, value: r.sell, color: color.red,
              column: 0, align: align.right, time: rows.time)
      fp.cell(r.from, r.to, weight: r.buy, value: r.buy, color: color.green,
              column: 1, time: rows.time)
    }
  }
}

Accepted values

align: Align values — 3 available.

`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 uses the current bar. A time after the current bar stops the script with an error. A time outside the bars still kept does nothing.

cell calls after clear in the same calculation step add to the emptied bar.

Example

script "Cell Clear"
data chart = subscribe(data.ohlcv)
plot fp = plot.cells(title: "Up bars")

on chart.update {
  fp.clear()
  if chart.close > chart.open {
    fp.cell(chart.open, chart.close, color: color.green)
  }
}

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

Example

script "Line Set"
data bars = subscribe(data.ohlcv)
window win = window(title: "Curve") {
  term: chart.panel(axis: axis.index),
}
plot iv = plot.line(title: "IV", on: win.term)

on bars.update {
  iv.set(bars.index, bars.close)
}

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

Example

script "Histogram Set"
data bars = subscribe(data.ohlcv)
window win = window(title: "Venues") {
  venues: chart.panel(axis: axis.category),
}
plot vol = plot.histogram(title: "Volume", on: win.venues)

on bars.update {
  vol.set("OKX", bars.volume, color: color.blue)
}

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

Contracts

size: Accepted range: 0.5 to 30.0. Must be a finite number. Invalid values are rejected.

Example

script "Point Set"
data bars = subscribe(data.ohlcv)
window win = window(title: "Spreads") {
  venues: chart.panel(axis: axis.category),
}
plot spread = plot.point(title: "Spread", on: win.venues)

on bars.update {
  spread.set("OKX", bars.high - bars.low, size: 3.0)
}

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

Example

script "Candle Set"
data bars = subscribe(data.ohlcv)
window win = window(title: "Renko") {
  rk: chart.panel(axis: axis.time),
}
plot bricks = plot.candle(title: "Renko", on: win.rk)

on bars.update {
  let t = bars.time
  if t != null { bricks.set(t, bars.open, bars.high, bars.low, bars.close) }
}