Use the formulas from an agent

Find the docs as Markdown and the function list as JSON, enter a formula in the Calculator or a Sheet from a browser, and check its result.

What this page covers

This page is for an AI agent that writes formulas for the Calculator and the Sheet, and for a person who scripts one. It lists the files that describe the language and the way to enter a formula in each widget from a browser. It ends with the checks that catch a wrong formula. Write a formula describes the language itself.

Find the material

Every docs page and both docs data files open without signing in.

The index: /llms.txt

/llms.txt is a plain-text index of the site. It lists, in this order:

  1. The title # TickPlunge and a one-line summary of the product.
  2. ## Product: the public pages, such as About, Pricing and Terms of Service.
  3. One section per docs section, in sidebar order: Start, Guides, Measures, Widgets, Formulas, Reference and Method. Each line links to the Markdown copy of one page, with its description. The start page is listed as Start here.
  4. ## Data: the function list, the measures list and the OpenAPI document.

The Markdown copy of each page

Add .md to the address of a docs page to get the page as Markdown. For example, /docs/formulas/series has its copy at /docs/formulas/series.md. The general form is /docs/{kind}/{slug}.md, where {kind} is guides, widgets, formulas, reference or method. The start page and the measures page sit at the docs root: /docs/start.md and /docs/measures.md.

A copy starts with the page title as a # heading and the description as the first paragraph. The page text follows. A link to another docs page points to that page's copy. A picture is replaced by its caption, written as (Picture: caption).

The function list: /docs/functions.json

/docs/functions.json is one JSON array with one object per function, in the group order of the function reference. Each object has these fields:

  • name: the name as typed in a formula, such as iv30.series.
  • group: one of eight groups: Numbers, logic and math, Data functions, Series, Matrices and regression, Mean reversion, Time and countdowns, Plots and Sheet references.
  • kind: pure for a function of its arguments, slot for a data function that loads site data, const for a constant such as pi, typed without brackets. raw marks plot and if. Each evaluates its own arguments: plot samples its expression many times, and if evaluates one branch only.
  • signature: the call with its argument names in order, such as zscore(s, n). A constant's signature is its name alone.
  • summary: what the function returns, with its unit.
  • args: one object per argument, in signature order, each with name and meaning. The meaning gives the value kind the argument takes. An argument whose meaning says (optional) or gives a default (default 504) can be left out.
  • example: a formula that runs in the Calculator.
  • result: the value of example when the docs were built, rounded to 6 significant figures. A Series is written as a series of N points, last X and a Matrix as a RxC matrix [...]. The field is empty for an example that needs a Sheet on the page.
  • note: a limit or a hint for use, or an empty string.

The measures list: /docs/measures.json

/docs/measures.json has one object per measure on the Measures page, /docs/measures. Each object has the fields id, name, group, meaning, method, units, lag and read. The field appears lists the widgets, the functions and the API routes and fields where the measure appears. Some measures add thresholds, caveats and also, the other labels the site uses for the measure. Some add banned, the labels the docs do not use for the measure.

The API description: /api/v1/openapi.json

/api/v1/openapi.json describes every operation of the data API. Calls under /api/v1 need a signed-in session or an API token in the Authorization header. A call with neither returns 401.

Enter a formula in the Calculator

The Calculator takes a formula only through its formula field. No address parameter or script call fills the field. To add an empty Calculator to the open tab of Trader Dash, open /trader-dashboard?pin=calculator while signed in.

  1. Click the formula field, the element input.calc-input.
  2. Type the formula. The Calculator runs it 120 ms after the last change to the field. No key commits it.
  3. While the text before the cursor ends in part of a name, a list of matching names opens under the field. Enter and Tab insert the highlighted name. Press Escape to close the list without inserting.
  4. Take the value from the result line, the element .calc-result.

For a formula with a data function, the result line keeps its previous text until the data loads, then shows the new value.

Value Result line .calc-result
Number The number, at the setting of the precision button
Series, or a plot curve N samples, with the chart in .calc-plot
Matrix One line per row, columns padded with spaces, class calc-result-matrix
Error CODE @pos: message, class calc-result-error

For a syntax, name, arity or argument-kind error, @pos is the character position, counted from 1. An error raised inside a function shows @0. A Series shows no values as text. To get one value as text, reduce the Series to a number, such as iloc(s, -1) for the latest point or mean(s) for its average. The precision button, .calc-precision, cycles auto, fixed2, fixed4 and fixed6 and changes only the display of the last value.

Trader Dash saves the formula with the layout. When the page opens again, the Calculator runs the formula on the latest data. Calculator describes the other controls.

Enter a formula in a Sheet

To add an empty Sheet to the open tab of Trader Dash, open /trader-dashboard?pin=sheet while signed in. The grid is drawn on a canvas, .sheet-canvas, so a cell has no element of its own. The selection starts at A1. The element .sheet-formula-cell shows the address of the selected cell, and .sheet-name shows the workbook name, such as Book1.

  1. Click the cell on the grid. Or click the grid, .sheet-grid-wrap, and move the selection with the arrow keys.
  2. Click the formula bar, input.sheet-formula-input, and type the formula with a leading =, such as =iv30.series("SPY").
  3. Press Enter. The Sheet stores the formula in the selected cell and moves the selection one row down.

You can also type on the grid. A printable key opens the cell editor, input.sheet-edit, with that character. In the cell editor, Enter commits and moves down, Tab commits and moves right, and Escape discards the edit. In both fields, an open list of names takes Enter and Tab first, as in the Calculator.

Get a value back from a Sheet

The formula bar shows what was typed in the selected cell. It does not show the value. Use one of these ways to get the value as text:

  • A Calculator on the same page: type sheet("Book1", "B2") to get the number in B2. Without a tab name, the reference uses the first tab. Write sheet("Book1", "Tab2!B2") for another tab. sheet("Book1", "A1:A10") returns the range as a Series. A cell with an error returns E_REF, a text cell E_TYPE, and an empty cell E_NO_DATA.
  • The footer: select a range by dragging or with Shift and the arrow keys. The element .sheet-aggs shows n=, sum= and avg= over the number cells of the range.
  • An error message: move the pointer over a cell that shows an error. The title attribute of .sheet-grid-wrap becomes CODE: message.

Sheet describes names, ranges and the format controls. Sheet cells describes what a cell formula accepts beyond the Calculator.

Check a formula before you use it

Work through these checks for every function in the formula. The error in each step is the one the Calculator shows when the check fails. The error reference gives the fix for each code.

  1. Function: find the name in /docs/functions.json. Names are not case sensitive. A name that is not in the list returns E_UNKNOWN_NAME.
  2. Argument order and count: write the arguments in signature order. Leave out only an argument whose meaning says (optional) or gives a default. Too many or too few arguments return E_ARITY.
  3. Symbol: when kind is slot, type each argument as a literal. Type the symbol in double quotes, such as "SPY", and a tenor or window as digits. A cell reference or a formula as an argument returns E_SLOT_ARGS. The symbol is converted to upper case, so "spy" and "SPY" load the same data. A symbol without data on the site returns E_NO_DATA. The API call /api/v1/symbols lists the symbols.
  4. Value kind of each argument: give each argument the kind its meaning asks for: a number, a Series or a Matrix. A wrong kind returns E_TYPE. E_DIM: see Series.
  5. Result kind: compare the result with the result field of the function's own example. The field gives the result kind of the example. An argument of another kind, such as roll(...), can change it: see the meaning of each argument. a series of means a Series and matrix means a Matrix. Check the result line in the Calculator against the table above.

Text in a formula takes double quotes only. Run a formula in the Calculator before you put it in a Sheet cell.

These formulas pass every check. The first returns the latest value, the second the daily history, and the last two reduce the history to one number:

iv30("SPY") => a number
iv30.series("SPY") => a Series of daily values
iloc(iv30.series("SPY"), -1) => a number
zscore(iv30.series("SPY"), 252) => a number

Get the same data through the API

Make your first API call creates a token and sends the first request. The API reference lists every operation and the meaning of each field. Use the API when a program needs the stored values as JSON without a browser. Use the Calculator or a Sheet when the analysis needs a function of the formula language. These functions run in the browser only.