openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/stdlib/volatility/deviation.ts

@@ -0,0 +1,111 @@
+/**
+ * `variance` and `stdev`.
+ *
+ * **Population by default, the `len` divisor.** `stdlib.md` section 6 fixes it
+ * and gives the reason: that is what the band studies a chart has to reproduce
+ * use. `sample = true` switches to the `len - 1` divisor, so neither camp has
+ * to write the correction by hand and neither has to guess which one a chart
+ * drew.
+ *
+ * Two passes: the mean of the lookback first, then the deviations from it. The
+ * one pass arrangement that subtracts the square of the mean from the mean of
+ * the squares loses most of its significant digits on a price series, where the
+ * values are large and their spread is small, and can even produce a negative
+ * variance that then has to be floored at zero. A study whose implementation
+ * needs a floor to stay real is a study computing the wrong quantity.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, ring, tailOf } from '../values/index.js';
+
+/** `variance(src, len, sample)`: the squared deviation over the lookback, from bar `len - 1`. */
+export function varianceStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  sample: boolean,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null) return NONE;
+  const divisor = sample ? len - 1 : len;
+  if (!lookback.complete() || divisor <= 0) return NONE;
+  const mean = lookback.mean();
+  if (!isPresent(mean)) return NONE;
+  let squares = 0;
+  // Oldest bar first, the order of `lookback.ts`.
+  for (let back = len - 1; back >= 0; back -= 1) {
+    const deviation = (lookback.at(back) as number) - mean;
+    squares += deviation * deviation;
+  }
+  return result(squares / divisor);
+}
+
+/** `variance(src, len, sample)` as a tail. */
+export function varianceTail(len: number, sample = false): Tail<Value, Value> {
+  return tailOf((state, value: Value) => varianceStep(state, 'q', value, len, sample));
+}
+
+/** `variance(src, len, sample)` over a whole series. */
+export function variance(src: Series, len: number, sample = false): Value[] {
+  return fold(varianceTail(len, sample), src);
+}
+
+/** `stdev(src, len, sample)`: the square root of the same, from bar `len - 1`. */
+export function stdevStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  sample: boolean,
+): Value {
+  const squared = varianceStep(state, key, value, len, sample);
+  if (!isPresent(squared) || squared < 0) return NONE;
+  return result(Math.sqrt(squared));
+}
+
+/** `stdev(src, len, sample)` as a tail. */
+export function stdevTail(len: number, sample = false): Tail<Value, Value> {
+  return tailOf((state, value: Value) => stdevStep(state, 'q', value, len, sample));
+}
+
+/** `stdev(src, len, sample)` over a whole series. */
+export function stdev(src: Series, len: number, sample = false): Value[] {
+  return fold(stdevTail(len, sample), src);
+}
+
+/**
+ * The mean absolute deviation from the lookback's mean.
+ *
+ * Not a call of its own in `stdlib.md`, and here because `cci` is defined
+ * against it rather than against `stdev`: the 0.015 constant in that study is
+ * calibrated for this quantity, and substituting a standard deviation changes
+ * every reading.
+ */
+export function meanDeviationStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || !lookback.complete()) return NONE;
+  const mean = lookback.mean();
+  if (!isPresent(mean)) return NONE;
+  let total = 0;
+  for (let back = len - 1; back >= 0; back -= 1) {
+    total += Math.abs((lookback.at(back) as number) - mean);
+  }
+  return result(total / len);
+}
+
+/** The mean absolute deviation as a tail. */
+export function meanDeviationTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => meanDeviationStep(state, 'q', value, len));
+}
+
+/** The mean absolute deviation over a whole series. */
+export function meanDeviation(src: Series, len: number): Value[] {
+  return fold(meanDeviationTail(len), src);
+}

package/src/core/stdlib/volatility/index.ts

@@ -0,0 +1,48 @@
+export type { Gap } from './range.js';
+export {
+  atr,
+  atrStep,
+  atrTail,
+  gapOf,
+  gapTrueRange,
+  gapTrueRangeStep,
+  gapTrueRangeTail,
+  natr,
+  natrStep,
+  natrTail,
+  trueRange,
+  trueRangeOf,
+  trueRangeTail,
+} from './range.js';
+
+export {
+  meanDeviation,
+  meanDeviationStep,
+  meanDeviationTail,
+  stdev,
+  stdevStep,
+  stdevTail,
+  variance,
+  varianceStep,
+  varianceTail,
+} from './deviation.js';
+
+export {
+  bbPercent,
+  bbPercentStep,
+  bbPercentTail,
+  bbWidth,
+  bbWidthStep,
+  bbWidthTail,
+  bollinger,
+  bollingerStep,
+  bollingerTail,
+  donchian,
+  donchianStep,
+  donchianTail,
+  keltner,
+  keltnerStep,
+  keltnerTail,
+} from './bands.js';
+
+export { chop, chopStep, chopTail, hv, hvStep, hvTail } from './measures.js';

package/src/core/stdlib/volatility/measures.ts

@@ -0,0 +1,96 @@
+/**
+ * `chop` and `hv`, the two readings that say how the lookback behaved rather than
+ * how wide it was.
+ *
+ * Both are written as a step over a state region and both tails are that step
+ * over a region of their own, so a live chart and a fold over a run of bars
+ * cannot disagree.
+ */
+import type { Bar, Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
+import { extremeStep, historyStep, sumStep } from '../series/index.js';
+
+import type { Gap } from './range.js';
+import { gapOf, trueRangeOf } from './range.js';
+import { stdevStep } from './deviation.js';
+
+/**
+ * `chop(len)`: a 0 to 100 reading of whether the lookback trended or chopped,
+ * from bar `len`.
+ *
+ * The distance price actually travelled over the lookback, against the outright
+ * range it covered. A market that went straight there travels its range and
+ * reads low; one that went back and forth travels several times its range and
+ * reads high.
+ *
+ * The travel is a sum of `len` true ranges, and a true range needs the bar
+ * before it, which is why the first reading is at bar `len` and not at bar
+ * `len - 1`: the gap-aware form of true range is the one used here, per the
+ * note in `range.ts`. The previous close arrives with the gap rather than being
+ * remembered here, for the reason the same note gives.
+ */
+export function chopStep(
+  state: StateRecord,
+  key: string,
+  gap: Gap,
+  len: number | null,
+): Value {
+  const distance = sumStep(state, `${key}s`, trueRangeOf(gap, false), len);
+  const upper = extremeStep(state, `${key}h`, gap.high, len, true, false);
+  const lower = extremeStep(state, `${key}l`, gap.low, len, false, false);
+  if (len === null) return NONE;
+  if (!isPresent(distance) || !isPresent(upper) || !isPresent(lower)) return NONE;
+  const span = upper - lower;
+  const scale = Math.log10(len);
+  if (!(span > 0) || !(distance > 0) || scale === 0) return NONE;
+  return result((100 * Math.log10(distance / span)) / scale);
+}
+
+/** `chop(len)` as a tail. */
+export function chopTail(len = 14): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => chopStep(state, '', gapOf(state, 'g', bar), len));
+}
+
+/** `chop(len)` over a run of bars. */
+export function chop(bars: readonly Bar[], len = 14): Value[] {
+  return fold(chopTail(len), bars);
+}
+
+/**
+ * `hv(src, len, periodsPerYear)`: the annualised standard deviation of log
+ * returns, from bar `len`.
+ *
+ * A log return needs the previous bar, so the deviation's lookback starts at bar
+ * 1 and its first value is at bar `len`, one later than a lookback over levels.
+ *
+ * The result is a proportion, not a percentage: `stdlib.md` section 6 says
+ * "annualised standard deviation of log returns" and nothing about scaling it
+ * by a hundred, so nothing here does. A study that wants a percentage axis
+ * multiplies at the plot, where a reader can see it happen.
+ */
+export function hvStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  periodsPerYear: number | null,
+): Value {
+  const previous = historyStep(state, `${key}h`, value, 1);
+  let logReturn: Value = NONE;
+  if (isPresent(value) && isPresent(previous) && value > 0 && previous > 0) {
+    logReturn = result(Math.log(value / previous));
+  }
+  const deviation = stdevStep(state, `${key}q`, logReturn, len, false);
+  if (!isPresent(deviation) || periodsPerYear === null || !(periodsPerYear > 0)) return NONE;
+  return result(deviation * Math.sqrt(periodsPerYear));
+}
+
+/** `hv(src, len, periodsPerYear)` as a tail. */
+export function hvTail(len = 20, periodsPerYear = 252): Tail<Value, Value> {
+  return tailOf((state, value: Value) => hvStep(state, '', value, len, periodsPerYear));
+}
+
+/** `hv(src, len, periodsPerYear)` over a whole series. */
+export function hv(src: Series, len = 20, periodsPerYear = 252): Value[] {
+  return fold(hvTail(len, periodsPerYear), src);
+}

package/src/core/stdlib/volatility/range.ts

@@ -0,0 +1,143 @@
+/**
+ * True range, and the two averages of it.
+ *
+ * **Bar 0 is the one deliberate exception to absence propagation in this
+ * library**, and `stdlib.md` section 6 puts it there rather than leaving it to
+ * an engine. `trueRange()` on bar 0 is `high - low`: the other two terms need
+ * the previous close, which does not exist there, and propagating absence would
+ * start `atr` one bar later than every reference implementation while adding
+ * nothing, because the bar's own range is a true statement about that bar.
+ *
+ * The exception is granted to `trueRange` and therefore to `atr` and `natr`.
+ * It is not granted to every function that happens to use a range: where a
+ * function's declared warmup shows it counts changes rather than levels,
+ * `gapTrueRange` is the form it uses, and that one is absent on bar 0 like any
+ * other change. `chop` and `adx` are the two, and both of their warmups in
+ * `stdlib.md` are one bar later than the plain reading would give, which is how
+ * the specification says which form they take.
+ *
+ * **Where the previous close comes from is a host fact, not an arithmetic one.**
+ * A run of bars has it in the bar before; an engine is handed it with the bar,
+ * and that is the one it must use, because a call inside a branch does not see
+ * every bar and the close of the bar it last ran on is a different number. So
+ * the arithmetic below takes it as an argument and `gapOf` is the small piece
+ * that remembers it for a caller folding over a series.
+ */
+import type { Bar, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
+import { rmaStep } from '../averages/index.js';
+
+/** A bar's two extremes and the close before it, which is what a range needs. */
+export interface Gap {
+  readonly high: Value;
+  readonly low: Value;
+  /** The close of the bar before this one, absent on the first bar. */
+  readonly previousClose: Value;
+  /** Whether this is the first bar of the run. */
+  readonly isFirstBar: boolean;
+}
+
+/** `trueRange()`: the bar's range including any gap from the previous close. */
+export function trueRangeOf(gap: Gap, allowFirstBar: boolean): Value {
+  if (gap.isFirstBar) {
+    return allowFirstBar && isPresent(gap.high) && isPresent(gap.low)
+      ? result(gap.high - gap.low)
+      : NONE;
+  }
+  if (!isPresent(gap.high) || !isPresent(gap.low) || !isPresent(gap.previousClose)) return NONE;
+  const within = gap.high - gap.low;
+  const upGap = Math.abs(gap.high - gap.previousClose);
+  const downGap = Math.abs(gap.low - gap.previousClose);
+  return result(Math.max(within, upGap, downGap));
+}
+
+/**
+ * The previous close remembered in a region, for a caller folding over a run of
+ * bars rather than being handed one at a time.
+ */
+export function gapOf(state: StateRecord, key: string, bar: Bar): Gap {
+  const closeKey = `${key}p`;
+  const seenKey = `${key}k`;
+  const held = state[closeKey];
+  const gap: Gap = {
+    high: bar.high,
+    low: bar.low,
+    previousClose: typeof held === 'number' ? held : NONE,
+    isFirstBar: state[seenKey] !== true,
+  };
+  state[seenKey] = true;
+  state[closeKey] = bar.close;
+  return gap;
+}
+
+/** `trueRange()` as a tail. */
+export function trueRangeTail(): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => trueRangeOf(gapOf(state, 'g', bar), true));
+}
+
+/**
+ * True range with no exception on bar 0, as a step: absent there, like any
+ * other quantity that needs the bar before it. Not a call a script can make;
+ * see this file's opening note for which functions use it and why.
+ */
+export function gapTrueRangeStep(state: StateRecord, key: string, bar: Bar): Value {
+  return trueRangeOf(gapOf(state, `${key}g`, bar), false);
+}
+
+/** `trueRange()` over a run of bars. */
+export function trueRange(bars: readonly Bar[]): Value[] {
+  return fold(trueRangeTail(), bars);
+}
+
+/** The gap-aware true range as a tail. */
+export function gapTrueRangeTail(): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => gapTrueRangeStep(state, '', bar));
+}
+
+/** The gap-aware true range over a run of bars. */
+export function gapTrueRange(bars: readonly Bar[]): Value[] {
+  return fold(gapTrueRangeTail(), bars);
+}
+
+/** `atr(len)`: the smoothed mean of true range, from bar `len - 1`. */
+export function atrStep(
+  state: StateRecord,
+  key: string,
+  gap: Gap,
+  len: number | null,
+): Value {
+  return rmaStep(state, `${key}a`, trueRangeOf(gap, true), len);
+}
+
+/** `atr(len)` as a tail. */
+export function atrTail(len: number): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => atrStep(state, '', gapOf(state, 'g', bar), len));
+}
+
+/** `atr(len)` over a run of bars. */
+export function atr(bars: readonly Bar[], len = 14): Value[] {
+  return fold(atrTail(len), bars);
+}
+
+/** `natr(len)`: `atr` as a percentage of close, from bar `len - 1`. */
+export function natrStep(
+  state: StateRecord,
+  key: string,
+  gap: Gap,
+  close: Value,
+  len: number | null,
+): Value {
+  const average = atrStep(state, key, gap, len);
+  if (!isPresent(average) || !isPresent(close) || close === 0) return NONE;
+  return result((100 * average) / close);
+}
+
+/** `natr(len)` as a tail. */
+export function natrTail(len: number): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => natrStep(state, '', gapOf(state, 'g', bar), bar.close, len));
+}
+
+/** `natr(len)` over a run of bars. */
+export function natr(bars: readonly Bar[], len = 14): Value[] {
+  return fold(natrTail(len), bars);
+}

package/src/core/stdlib/volume/accumulation.ts

@@ -0,0 +1,152 @@
+/**
+ * The running totals: `obv`, `ad`, `adOsc` and `pvt`.
+ *
+ * Every function in this module returns absence on every bar when the host
+ * supplies no volume, because `volume` is absent rather than zero there
+ * (`stdlib.md` sections 3.1 and 7). A script tests `chart.hasVolume` to branch
+ * on that rather than inspecting the result, and nothing here substitutes a
+ * zero to keep a line drawing.
+ *
+ * A running total is the one thing a lookback cannot stand in for, so each of
+ * these carries its total in the state region rather than in a closure: that is
+ * what lets an engine roll one back with the rest of a moving bar's state.
+ */
+import type { Bar, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, held, isPresent, result, slot, tailOf } from '../values/index.js';
+import { emaStep } from '../averages/index.js';
+
+/**
+ * Where the close sat inside the bar, as -1 at the low to 1 at the high, times
+ * the volume behind it.
+ *
+ * A bar whose high and low are equal has no position inside it to report, and
+ * the settled treatment is that such a bar contributes nothing rather than
+ * ending the running total.
+ */
+export function moneyFlow(bar: Bar): Value {
+  if (!isPresent(bar.high) || !isPresent(bar.low)) return NONE;
+  if (!isPresent(bar.close) || !isPresent(bar.volume)) return NONE;
+  const span = bar.high - bar.low;
+  if (!(span > 0)) return 0;
+  return result((((bar.close - bar.low) - (bar.high - bar.close)) / span) * bar.volume);
+}
+
+/** `obv()`: the running total of volume signed by the close's direction, from bar 0, seeded 0. */
+export function obvStep(state: StateRecord, key: string, bar: Bar): Value {
+  const totalKey = `${key}t`;
+  const closeKey = `${key}p`;
+  const seenKey = `${key}k`;
+  const previousClose = held(state, closeKey);
+  const started = state[seenKey] === true;
+
+  if (!isPresent(bar.volume) || !isPresent(bar.close)) {
+    state[seenKey] = true;
+    state[closeKey] = bar.close;
+    return NONE;
+  }
+
+  let total = slot(state, totalKey, 0);
+  if (started && isPresent(previousClose)) {
+    if (bar.close > previousClose) total += bar.volume;
+    else if (bar.close < previousClose) total -= bar.volume;
+  }
+  state[seenKey] = true;
+  state[closeKey] = bar.close;
+  state[totalKey] = total;
+  return result(total);
+}
+
+/** `obv()` as a tail. */
+export function obvTail(): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => obvStep(state, '', bar));
+}
+
+/** `obv()` over a run of bars. */
+export function obv(bars: readonly Bar[]): Value[] {
+  return fold(obvTail(), bars);
+}
+
+/** `ad()`: the running total of volume weighted by where the close sat, from bar 0. */
+export function adStep(state: StateRecord, key: string, bar: Bar): Value {
+  const flow = moneyFlow(bar);
+  if (!isPresent(flow)) return NONE;
+  const total = slot(state, `${key}t`, 0) + flow;
+  state[`${key}t`] = total;
+  return result(total);
+}
+
+/** `ad()` as a tail. */
+export function adTail(): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => adStep(state, '', bar));
+}
+
+/** `ad()` over a run of bars. */
+export function ad(bars: readonly Bar[]): Value[] {
+  return fold(adTail(), bars);
+}
+
+/**
+ * `adOsc(fast, slow)`: the difference of two means of `ad`, from bar `slow - 1`.
+ *
+ * The averages run over the running total, not over the per-bar term, so what
+ * this measures is acceleration in accumulation rather than the flow itself.
+ */
+export function adOscStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  fast: number | null,
+  slow: number | null,
+): Value {
+  const total = adStep(state, `${key}a`, bar);
+  const near = emaStep(state, `${key}f`, total, fast);
+  const far = emaStep(state, `${key}s`, total, slow);
+  if (!isPresent(near) || !isPresent(far)) return NONE;
+  return result(near - far);
+}
+
+/** `adOsc(fast, slow)` as a tail. */
+export function adOscTail(fast = 3, slow = 10): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => adOscStep(state, '', bar, fast, slow));
+}
+
+/** `adOsc(fast, slow)` over a run of bars. */
+export function adOsc(bars: readonly Bar[], fast = 3, slow = 10): Value[] {
+  return fold(adOscTail(fast, slow), bars);
+}
+
+/**
+ * `pvt()`: the running total of volume weighted by percentage change, from bar
+ * 1, seeded 0.
+ *
+ * The total starts at zero before the first change, and the first change is at
+ * bar 1, so bar 0 is absent and bar 1 already carries its own term. Reporting a
+ * zero at bar 0 would claim a reading on a bar where the quantity is not
+ * defined.
+ */
+export function pvtStep(state: StateRecord, key: string, bar: Bar): Value {
+  const totalKey = `${key}t`;
+  const closeKey = `${key}p`;
+  const seenKey = `${key}k`;
+  const before = held(state, closeKey);
+  const started = state[seenKey] === true;
+  state[seenKey] = true;
+  state[closeKey] = bar.close;
+
+  if (!started) return NONE;
+  if (!isPresent(before) || before === 0) return NONE;
+  if (!isPresent(bar.close) || !isPresent(bar.volume)) return NONE;
+  const total = slot(state, totalKey, 0) + ((bar.close - before) / before) * bar.volume;
+  state[totalKey] = total;
+  return result(total);
+}
+
+/** `pvt()` as a tail. */
+export function pvtTail(): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => pvtStep(state, '', bar));
+}
+
+/** `pvt()` over a run of bars. */
+export function pvt(bars: readonly Bar[]): Value[] {
+  return fold(pvtTail(), bars);
+}