Series and qualifiers

The four qualifiers const, input, simple and series: what each means, why some arguments refuse a series value, and how to fix the errors.

Every value in ChartScript has a type (int, float, string …, see Types) and a qualifier. The qualifier says when the value is known and whether it can change from bar to bar. You rarely write qualifiers yourself, because the compiler works them out, but they explain a family of errors that otherwise look mysterious, such as "the length of ta.rsi must be the same on every bar".

#The four qualifiers

From the most fixed to the most changeable:

Each qualifier includes the ones above it: wherever a series value is accepted, a const one is accepted too. The reverse is not true.

A value gets the qualifier of the most changeable thing it is built from:

const a = 2 * 7  // const
const len = input.int(14, "Length")  // input
const double = len * 2  // input: input times const
const tick = market.tick  // simple
const mid = (high + low) / 2  // series
plot(mid)

A variable that you reassign inside a branch that depends on the bar (if (close > open)) becomes series, because its value can now differ from bar to bar. A state variable that you never reassign keeps the qualifier of its first value.

#Why it matters

Some work can only be set up once. A 14-bar RSI keeps a smoothing state sized for 14 bars; if the length could jump to 30 on the next bar, the state would be meaningless. So the length parameter of ta.rsi is declared simple int: it accepts a constant, an input or a simple value, and refuses a series.

//@chartscript 1
indicator("Changing length")
const len = bar_index % 10 + 5  // a different number on each bar: series
plot(ta.rsi(close, len))

The error, CS2101, names the argument and the qualifier it needs. The usual fix is to make the length a setting instead of a calculation:

//@chartscript 1
indicator("RSI with a setting", { precision: 2 })
const len = input.int(14, "Length", { minval: 2 })
plot(ta.rsi(close, len), "RSI", color.purple, 2)
hline(70, "Upper", color.muted, hline.style_dotted)
hline(30, "Lower", color.muted, hline.style_dotted)

#Lengths that may change

A few averages and window functions do accept a length that changes from bar to bar: ta.sma, ta.ema, ta.rma, ta.wma, ta.highest, ta.lowest, ta.stdev, ta.change and ta.roc. With a series length they keep a buffer of max_bars_back values, and the editor shows a hint (CS2102) so you know the cost.

//@chartscript 1
indicator("Adaptive average", { overlay: true })
// longer average when the bar range is small, shorter when it is large
const atr = ta.atr(14)
const len = int(math.max(5, math.min(50, 20 * ta.sma(atr, 50) / atr)))
plot(ta.ema(close, len), "Adaptive EMA", color.accent, 2)

#Static arguments of outputs

Some arguments describe the chart, not a bar, so they must be fixed before the first bar runs. The title of a plot must be a constant (CS2103); the price of an hline must be a constant or an input (CS2104).

//@chartscript 1
indicator("Moving title")
plot(close, { title: "Close " + str.tostring(close) })

//@chartscript 1
indicator("Moving level")
hline(ta.sma(close, 20), "Average")

For a level that moves, plot it instead: plot(ta.sma(close, 20), "Average"). For a level the user picks, use an input: hline(input.float(50, "Level"), "Level").

#Writing qualifiers yourself

You can put a qualifier in a type annotation, in front of the type: const tickSize: simple float = market.tick, or a parameter len: simple int. It is a promise the compiler checks.

const LENGTH: int = 20
const tickSize: simple float = market.tick
const typical: series float = hlc3
plot(ta.sma(typical, LENGTH))

Giving a declaration a value that changes more than its qualifier allows is an error (CS2405):

//@chartscript 1
indicator("Not constant")
const LAST: const float = close
plot(LAST)

In functions, a parameter without a qualifier takes the qualifier of whatever you pass, so one function works with constants, inputs and series alike. Add a qualifier only when the function needs it, for example function f(len: simple int) { return ta.rsi(close, len) }: then a caller passing a series gets a clear error at the call instead of deep inside the function.

//@chartscript 1
indicator("Smoothed RSI")
// len must be fixed for ta.rsi, so say so: callers see the rule at the call
const smoothRsi = (src: float, len: simple int, smooth: simple int) => ta.sma(ta.rsi(src, len), smooth)
const len = input.int(14, "RSI length", { minval: 2 })
plot(smoothRsi(close, len, 3), "Smoothed RSI", color.purple, 2)

#Common mistakes

• Computing a length from the bar. ta.rsi(close, bar_index % 10 + 5) fails with CS2101. Use an input, or one of the functions listed under Lengths that may change.
• Building a title from a value. Titles of plots, levels and alerts are fixed. Show changing text with a label or a table.
• The const qualifier for something read from the chart. const t: const float = market.tick fails: the tick size is only known when the script starts on a market, so it is simple. A plain const t = market.tick is fine: the const keyword only means the variable is not reassigned.
• A variable that becomes series by accident. Reassigning a variable inside if (close > open) makes it series; if you then pass it where a simple value is needed, you get CS2101. Keep a separate variable for the fixed value.