Formulas
Indicator formulas written the way Chinese market software writes them become indicators of the pro chart as they are: computed bar by bar in real time, listed in the indicators window, added and changed in their parameters and lines by users like the built-in indicators, and able to carry alerts. Put the formula in customIndicators (or register it later with registerIndicator()), with formula in place of an algorithm's definition:
import { createProChart, type CustomIndicator } from '@kumo-charts/pro-chart';
const MYMACD: CustomIndicator = {
name: { en: 'My MACD', zh: '我的 MACD' }, // the name after the code in the indicators window
group: 'oscillators',
formula: {
type: 'MYMACD', // the code, shown in the indicators window and the legend; it cannot be the name of a built-in indicator
name: 'MYMACD', // the name in the legend
formula: `
DIF:EMA(CLOSE,SHORT)-EMA(CLOSE,LONG);
DEA:EMA(DIF,MID);
MACD:(DIF-DEA)*2,COLORSTICK;
`,
params: { SHORT: 12, LONG: 26, MID: 9 }
}
};
const chart = createProChart(container, {
datafeed,
symbol: '600519.SH',
customIndicators: [MYMACD]
});
chart.addIndicator('MYMACD', { params: { SHORT: 6 } });The license for formula indicators is included in the commercial license. name, group and origin are as for other custom indicators.
Options
| Option | Description |
|---|---|
type |
The code, as MYMACD: used in the indicators window, the legend and the state, and it cannot be the name of a built-in indicator or of another custom indicator |
name |
The name shown in the legend |
formula |
The text of the formula |
params |
Parameters, as { N: 9 }; they can have ranges too: { N: { default: 9, min: 1, max: 100, integer: true } }, by which the indicator settings window limits what is typed |
overlay |
With true, drawn on the main pane; otherwise in a pane of its own below |
precision |
The number of decimals; price follows the price (the default when drawn on the main pane), and volume is for volume |
levels |
Horizontal reference lines, as [20, 80] |
range |
A fixed scale range for the pane below, as { min: 0, max: 100 } |
timeZone |
The time zone of the time functions, as Asia/Shanghai; by default the time zone the chart shows times in, computed again in the new time zone when the user changes it |
library |
Other formulas that can be referenced, see "Referencing other formulas" below |
When it is wrong
A formula is compiled at createProChart() or registerIndicator(), and a mistake throws a FormulaError (imported from @kumo-charts/pro-chart) right away: code says what kind of error it is, span is where it is, and describe('zh') is the description in Chinese (describe() gives it in English):
import { FormulaError } from '@kumo-charts/pro-chart';
try {
await chart.registerIndicator({ formula: { type: 'X', name: 'X', formula: 'A:MA(C,N);' } });
} catch (error) {
if (error instanceof FormulaError) {
error.span; // { line: 1, column: 8, length: 1 }
error.describe('zh'); // "N"既不是前面定义过的变量、参数,也不是 CLOSE 这样的行情数据。
}
}Syntax
name:expression;draws a line;name:=expression;only defines an intermediate variable; an expression without a name draws a line too.- Operators:
+ - * /, the comparisons> < >= <= = <>, and the logicAND OR NOT(or&& || !). Precedence from high to low:* /,+ -, comparisons,NOT,AND,OR. SoNOT C>Owithout parentheses is the same asNOT(C>O), as Chinese formulas usually write it: "not a rising bar";NOTon one side of a comparison needs parentheses, asC>NOT(O). - Names are not case sensitive and can be Chinese; full-width Chinese punctuation (
;:,()) is recognized automatically, and text in quotes is kept as it is (the full-width comma in'买入,加仓'stays). Text and references can also be enclosed in the Chinese quotes‘’and“”; enclosed in ASCII quotes, they can contain Chinese quotes. - Comments:
{ … }and// …. - Market data:
OPEN/O,HIGH/H,LOW/L,CLOSE/C,VOL/V/VOLUME. - Line attributes: colors such as
COLORRED,COLORfollowed by six digits of BBGGRR,NODRAW,STICK,COLORSTICK,VOLSTICK,DOTLINE,DASHLINE,LINETHICK1–9(the line width, see "Drawing functions").
Functions
| Kind | Functions |
|---|---|
| Averages | MA EMA EXPMA SMA MEMA DMA WMA |
| References | REF BARSLAST BARSSINCE BARSCOUNT BARSLASTCOUNT |
| Statistics | SUM HHV LLV HHVBARS LLVBARS COUNT EVERY EXIST SUMBARS STD STDP VAR VARP AVEDEV DEVSQ SLOPE FORCAST |
| Signals | CROSS LONGCROSS FILTER VALUEWHEN LAST NDAY UPNDAY DOWNNDAY |
| Indicators | SAR |
| Time | DATE TIME YEAR MONTH DAY HOUR MINUTE WEEKDAY BARPOS |
| Logic | IF IFF IFN NOT BETWEEN RANGE ISUP ISDOWN ISEQUAL |
| Math | ABS MAX MIN SQRT POW LN LOG EXP INTPART FRACPART CEILING FLOOR ROUND ROUND2 SIGN MOD REVERSE SIN COS TAN ASIN ACOS ATAN |
| Other | DRAWNULL |
Details of a few functions:
LAST(X,A,B): 1 when X holds on every bar from A bars back to B bars back (both included). A of 0 counts from the first bar, and B of 0 up to the current bar; 0 when the stretch starts before the first bar, or when A is less than B.NDAY(X,Y,N): X>Y on each of the last N bars.UPNDAY(X,M)andDOWNNDAY(X,M): each of the last M bars greater (less) than the bar before, with equal not counting.RANGE(A,B,C): 1 when A is greater than B and less than C, the ends not included;BETWEENincludes the ends.ROUND(X)rounds to an integer, andROUND2(X,N)to N decimals: both round half away from zero, negative numbers too (ROUND(-2.5)is -3), and they round the decimal as written, soROUND2(1.005,2)is 1.01. The fractional part of N is dropped, and a negative N gives an invalid value.FRACPART(X)is the fractional part, with its sign:FRACPART(-3.5)is -0.5.VALUEWHEN(COND,X): X at the bar where COND last held; an invalid value before it first holds.SUMBARS(X,A): how many bars back from the current one X must be added up to reach A or more; 1 when the current bar is enough, and the number of bars there are when all of them are not enough. Invalid values of X count as 0.SAR(N,S,M): parabolic stop and reverse, with the step S and the limit M both in percent, asSAR(10,2,20). The first N bars have no value and set the start: when the close of the bar after them is above the close of the first, it starts rising, with SAR starting from the lowest low of those N bars, and otherwise falling, starting from the highest high. Each bar after moves toward the trend's extreme, with an acceleration from S% that grows by S% at each new extreme, up to M%; it does not go inside the range of the two bars before; when the price crosses it, it reverses, starting again from the extreme of the trend before.
Periods
A period argument (the N of MA(C,N)) can be a number, a parameter or arithmetic on them, or a series: HHV(H,BARSLAST(CROSS(C,MA(C,5)))+1) is the highest high since the last cross above the 5-day moving average, and SUM(V,BARSLAST(CROSS(C,MA(C,5)))+1) the volume over that time. Except for LONGCROSS, FILTER and SAR, periods can all be series.
- Written as a number or a parameter, a period must be an integer no less than the function's lower bound (see the next item), or compiling reports
invalid-period, saying what the bound is; a negative period ofREFrefers to later bars (future data) and reportsfuture-reference. - With a series as the period, each bar uses its own value of the period, with the fractional part dropped (2.7 as 2); a period that is invalid or negative gives an invalid value.
- 0 means what it means when written as a number: an A of 0 for
SUM,HHV,LLV,HHVBARS,LLVBARS,COUNTandLASTcounts from the first bar, and a 0 forREFis the current bar. The periods of other functions are at least 1 (at least 2 forSTD,VAR,SLOPEandFORCAST), and smaller gives an invalid value. - Fewer bars than the period is also as when written as a number:
COUNTandEXISTcount the bars there are,EVERY,NDAY,UPNDAY,DOWNNDAYandLASTgive 0, and the others an invalid value. - Recursive averages such as
EMAandSMAcompute each bar with its own period, and a bar whose period is invalid gives an invalid value and takes no part in the recursion.
Drawing functions
Signals on the bars are drawn as in the formulas of Chinese market software, each in a statement of its own, optionally followed by a color:
金叉:=CROSS(MA(C,5),MA(C,10));
DRAWICON(金叉,LOW,1);
DRAWTEXT(金叉,HIGH+MA(HIGH-LOW,20),'金叉'),COLORRED;
STICKLINE(VOL>MA(VOL,20)*2,OPEN,CLOSE,0.8,0),COLORYELLOW;
DRAWBAND(MA(C,5),COLORRED,MA(C,20),COLORGREEN);
DRAWLINE(H>=HHV(H,20),H,L<=LLV(L,20),L,1),COLORMAGENTA,LINETHICK2;| Function | What it draws |
|---|---|
STICKLINE(cond,price1,price2,width,hollow) |
A bar from price 1 to price 2 on the bars where the condition holds. A width of 0 is a thin line, 0.8 is as wide as a candle's body, and 1.1 or more fills the spacing; with hollow not 0, only the outline is drawn |
DRAWTEXT(cond,price,'text') |
Text at the price (centered on it) |
DRAWNUMBER(cond,price,number) |
A number at the price (centered on it), which can be a series. Integers are written without decimals, and other numbers with the formula's decimals, as in the legend |
DRAWICON(cond,price,icon) |
Icon 1 is an up arrow, its tip pointing at the price from below; 2 is a down arrow, pointing at the price from above; other numbers draw a dot |
POLYLINE(cond,price) |
Joins the points where the condition holds into a polyline, skipping the bars in between; it can also be written PLOYLINE |
VERTLINE(cond) |
A vertical line on the bars where the condition holds, from the top of the pane to its bottom |
DRAWLINE(cond1,price1,cond2,price2,extend) |
When condition 1 holds, the start is noted (and replaced when it holds again); when condition 2 holds after it, a straight line is drawn from the start to there, using up the start, and the next line waits for condition 1 to hold again. When both conditions hold on the same bar, the line before ends there first, and a new one starts there. Extend: 0 does not extend, 1 extends to the right edge of the pane, 2 or 10 to the left, 3 or 11 both ways |
DRAWBAND(value1,color1,value2,color2) |
Fills between the two values with color 1 where value 1 is above value 2, and with color 2 otherwise. Colors are names such as COLORRED, or COLOR followed by six digits of BBGGRR; the fill is translucent, not hiding the bars |
DRAWKLINE(high,open,low,close) |
Draws candles from these four values, rising when the close is not below the open, with the up and down colors of the chart's theme |
PARTLINE(price,cond1,color1,cond2,color2,…) |
Draws a line of the price, each bar in the color of the first condition that holds, and nothing where none holds; where one color turns into another the two pieces join, so it is a single line that changes color. One pair of a condition and a color can be given, or several |
FILLRGN(price1,price2,cond1,color1,…) |
Fills between the two prices, each bar in the color of the first condition that holds, and not where none holds; the fill is translucent, as dark as DRAWBAND |
DRAWGBK(cond,color) |
Tints the background of the whole pane faintly in the color behind the bars where the condition holds, bars in a row joining into one block; it is below the bars, not hiding them |
- The arguments of drawing functions are computed on every bar, whether or not the condition holds, so functions such as
MAandREFin the arguments give the same results. - Width, hollow, the icon number and extend must be numbers or parameters; text must be in quotes.
- Without a color, arrows use the buy and sell colors of the chart's theme,
DRAWKLINEthe theme's up and down colors, and other shapes the theme's line colors in turn. In Chinese market software, icons 1 and 2 are always red and green; here they follow the theme, so that buying is not drawn red on a chart where green is up. LINETHICK1–9sets the line width, the same for ordinary lines and forPOLYLINE,DRAWLINEandVERTLINE: 1 is the default width, and 2–9 are 2–9 pixels;DOTLINEandDASHLINEdraw them dotted and dashed. A line width the user changes in the indicator settings comes first.DRAWLINEdraws no line ahead: a line is drawn when the bar where condition 2 holds appears, and does not change after it is drawn.- Drawings are not shown in the legend. The scale leaves room for the ends of bars, marks, numbers, the points of polylines, the ends of straight lines and bands, while vertical lines take no room on it; a pane below with only drawings shows properly too.
- A drawing function must be a statement of its own, and cannot be put in an expression or given to a name.
Referencing other formulas
"formula.line" reads a line of another formula, with that formula's default parameters:
XG:CROSS("MACD.DIF","MACD.DEA") AND "KDJ.J"<20;Parentheses after it give it parameters of its own, in the order of that formula's parameters, each a number or a parameter of this formula, with the defaults for those not given:
快:"MACD.DIF"(5,20); 慢:"MACD.DIF"; 金叉:CROSS("MACD.DIF"(N,20,9),"MACD.DEA"(N,20,9));- The ready-made formulas can all be referenced by name:
MA,BOLL,MACD,KDJ,RSI,CCI,WR,BIAS,TRIXandOBV. - Your own formulas can be referenced once they are in the
libraryoption, ahead of ready-made ones of the same name:{ library: { 我的均线: { formula: 'FAST:MA(C,N);', params: { N: 5 } } } }. - Names are not case sensitive; the Chinese quotes
“”work too. - A formula referenced several times with the same parameters is computed once. Formulas referencing each other in a cycle, and references to formulas or lines that do not exist, are errors that point to where they are. A formula knows itself by its code (
type): referencing a formula of the same name is referencing itself; thenameshown in the legend does not count, so a formula withname: 'MACD'can still reference the ready-made"MACD.DIF". - When a referenced formula is itself wrong,
broken-referenceis reported, pointing to where it is referenced, with a description of the line and column where that formula is wrong and what is wrong there;error.referencedis that formula's ownFormulaError.
Differences from Chinese market software
- Invalid values: when there is not enough data (the first 4 bars of
MA(C,5), say), on division by 0 and in comparisons with invalid values, the result is an invalid value, not drawn on the chart. Averages skip invalid values. HHV,LLVandSUMwith fewer bars than the period: with fewer bars than the period so far, the result here is an invalid value (the first 19 bars ofHHV(H,20)are not drawn), as for the library's built-in indicators; Chinese market software usually computes a value from the bars there are, so the two differ for this stretch at the start and are the same after it. To have values from the first bar, writeIF(BARSCOUNT(C)>=20,HHV(H,20),HHV(H,0))(a period of 0 counts from the first bar).- Not supported yet: the other drawing functions (
DRAWBMP,DRAWSL,DRAWTEXT_FIX, …), trading functions (BUY,SELL),AMOUNT(bars have no turnover, so the result is an invalid value), and references across timeframes (as"MACD.DIF#WEEK"). - Time:
DATEcounts from 1900 as in Chinese market software (2026-10-21 is1261021),TIMEisHHMMSS(9:30 is93000), and 0 inWEEKDAYis Sunday. Times are the start of the bar, while the minute bars of Chinese market software use the end: for the same 9:30–9:35 bar,TIMEis93000here and93500there. - Future functions:
ZIG,PEAK,PEAKBARS,TROUGH,TROUGHBARS,BACKSET,REFX,REFXV,CONST,XMA,CURRBARSCOUNT,TOTALBARSCOUNT,ISLASTBAR,BARSTATUS,BARSNEXTandFILTERXuse later bars: the lines and signals they draw are rewritten as new bars come (repainting), which looks good looking back but cannot be had in real time, so they are not supported. Writing one reports afuture-functionerror that points to where it is, with another way of writing it when there is one: the highs and lowsZIGfinds can be found once confirmed withHHV,LLVandBARSLAST, say, andXMAcan becomeMA. - The start of SAR: software differs in how
SARstarts, and the start here is described above; so the values and reversals of the first stretch may differ from other software, and are the same after a few reversals. Past the start (usually a few reversals within the first few dozen bars), it agrees on every bar with the library's built-in SAR (with the parameters as fractions:SAR(10,2,20)is 0.02, 0.02 and 0.2); with anNof 1, they agree from start to end.