openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/stdlib/momentum/convergence.ts

@@ -0,0 +1,82 @@
+/**
+ * `macd` and `ppo`: the gap between a fast and a slow exponential mean, once as
+ * a difference and once as a percentage.
+ *
+ * Both return an array holding this bar's outputs, per `stdlib.md` section 2.3.
+ * One call, one state region: the alternative of three named functions would be
+ * three call sites and therefore three independent states, and the shared
+ * smoothing would be computed three times per bar.
+ *
+ * The signal average is fed the difference series, absences and all, so it
+ * seeds on the first `signal` values the difference produced. That is where the
+ * declared warmup of bar `slow + signal - 2` comes from.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
+import { emaStep } from '../averages/index.js';
+
+/**
+ * `macd(src, fast, slow, signal)`: `[macd, signal, histogram]`, element 0 from
+ * bar `slow - 1` and the other two from bar `slow + signal - 2`.
+ */
+export function macdStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  fast: number | null,
+  slow: number | null,
+  signal: number | null,
+): Value[] {
+  const near = emaStep(state, `${key}e`, value, fast);
+  const far = emaStep(state, `${key}g`, value, slow);
+  const line = isPresent(near) && isPresent(far) ? result(near - far) : NONE;
+  const trigger = emaStep(state, `${key}i`, line, signal);
+  const histogram = isPresent(line) && isPresent(trigger) ? result(line - trigger) : NONE;
+  return [line, trigger, histogram];
+}
+
+/** `macd(src, fast, slow, signal)` as a tail. */
+export function macdTail(fast = 12, slow = 26, signal = 9): Tail<Value, Value[]> {
+  return tailOf((state, value: Value) => macdStep(state, '', value, fast, slow, signal));
+}
+
+/** `macd(src, fast, slow, signal)` over a whole series. */
+export function macd(src: Series, fast = 12, slow = 26, signal = 9): Value[][] {
+  return fold(macdTail(fast, slow, signal), src);
+}
+
+/**
+ * `ppo(src, fast, slow, signal)`: `[ppo, signal, histogram]`, on the same
+ * warmups as `macd`.
+ *
+ * The same gap divided by the slow average, so the reading is a percentage and
+ * two instruments at different price levels can be compared.
+ */
+export function ppoStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  fast: number | null,
+  slow: number | null,
+  signal: number | null,
+): Value[] {
+  const near = emaStep(state, `${key}e`, value, fast);
+  const far = emaStep(state, `${key}g`, value, slow);
+  const line =
+    isPresent(near) && isPresent(far) && far !== 0
+      ? result((100 * (near - far)) / far)
+      : NONE;
+  const trigger = emaStep(state, `${key}i`, line, signal);
+  const histogram = isPresent(line) && isPresent(trigger) ? result(line - trigger) : NONE;
+  return [line, trigger, histogram];
+}
+
+/** `ppo(src, fast, slow, signal)` as a tail. */
+export function ppoTail(fast = 12, slow = 26, signal = 9): Tail<Value, Value[]> {
+  return tailOf((state, value: Value) => ppoStep(state, '', value, fast, slow, signal));
+}
+
+/** `ppo(src, fast, slow, signal)` over a whole series. */
+export function ppo(src: Series, fast = 12, slow = 26, signal = 9): Value[][] {
+  return fold(ppoTail(fast, slow, signal), src);
+}

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

@@ -0,0 +1,47 @@
+export { rsi, rsiStep, rsiTail } from './rsi.js';
+
+export { macd, macdStep, macdTail, ppo, ppoStep, ppoTail } from './convergence.js';
+
+export {
+  stoch,
+  stochRsi,
+  stochRsiStep,
+  stochRsiTail,
+  stochStep,
+  stochTail,
+  williamsR,
+  williamsRStep,
+  williamsRTail,
+} from './stochastic.js';
+
+export {
+  cmo,
+  cmoStep,
+  cmoTail,
+  dpo,
+  dpoStep,
+  dpoTail,
+  mom,
+  momTail,
+  roc,
+  rocStep,
+  rocTail,
+  trix,
+  trixStep,
+  trixTail,
+  tsi,
+  tsiStep,
+  tsiTail,
+} from './rates.js';
+
+export {
+  awesomeOsc,
+  awesomeOscStep,
+  awesomeOscTail,
+  cci,
+  cciStep,
+  cciTail,
+  ultimateOsc,
+  ultimateOscStep,
+  ultimateOscTail,
+} from './pressure.js';

package/src/core/stdlib/momentum/pressure.ts

@@ -0,0 +1,141 @@
+/**
+ * The readings taken from the whole bar rather than from one price: `cci`,
+ * `ultimateOsc` and `awesomeOsc`.
+ */
+import type { Bar, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, at, fold, held, hl2, hlc3, isPresent, result, tailOf } from '../values/index.js';
+import { smaStep } from '../averages/index.js';
+import { sumStep } from '../series/index.js';
+import { meanDeviationStep } from '../volatility/index.js';
+
+/**
+ * `cci(len)`: how far the typical price sits from its mean in mean-deviation
+ * units, from bar `len - 1`.
+ *
+ * The divisor is the **mean absolute deviation**, not the standard deviation.
+ * The 0.015 constant is calibrated against that quantity, and substituting a
+ * standard deviation changes every reading while still producing a plausible
+ * looking line.
+ */
+export function cciStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const typical = hlc3(bar);
+  const mean = smaStep(state, `${key}q`, typical, len);
+  const deviation = meanDeviationStep(state, `${key}v`, typical, len);
+  if (!isPresent(typical) || !isPresent(mean) || !isPresent(deviation)) return NONE;
+  if (deviation === 0) return NONE;
+  return result((typical - mean) / (0.015 * deviation));
+}
+
+/** `cci(len)` as a tail. */
+export function cciTail(len = 20): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => cciStep(state, '', bar, len));
+}
+
+/** `cci(len)` over a run of bars. */
+export function cci(bars: readonly Bar[], len = 20): Value[] {
+  return fold(cciTail(len), bars);
+}
+
+/**
+ * `ultimateOsc(len1, len2, len3)`: buying pressure blended over three lookbacks,
+ * from bar `max(len1, len2, len3)`.
+ *
+ * Buying pressure is the close above the lower of this bar's low and the
+ * previous close, over the range between the higher of this bar's high and that
+ * close and the same lower bound. Both need the previous close, so the sums
+ * start at bar 1 and the first reading is at bar `max`, not `max - 1`.
+ *
+ * The weights are 4, 2 and 1 over 7, shortest lookback heaviest, which is what
+ * stops any single length dominating the reading.
+ */
+export function ultimateOscStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len1: number | null,
+  len2: number | null,
+  len3: number | null,
+): Value {
+  const closeKey = `${key}p`;
+  const seenKey = `${key}k`;
+  const previousClose = held(state, closeKey);
+  const started = state[seenKey] === true;
+
+  let pressure: Value = NONE;
+  let range: Value = NONE;
+  if (
+    started &&
+    isPresent(previousClose) &&
+    isPresent(bar.high) &&
+    isPresent(bar.low) &&
+    isPresent(bar.close)
+  ) {
+    const floorOf = Math.min(bar.low, previousClose);
+    const ceilingOf = Math.max(bar.high, previousClose);
+    pressure = result(bar.close - floorOf);
+    range = result(ceilingOf - floorOf);
+  }
+  state[seenKey] = true;
+  state[closeKey] = bar.close;
+
+  const lengths = [len1, len2, len3];
+  const averages: Value[] = [];
+  for (let index = 0; index < 3; index += 1) {
+    const len = lengths[index] ?? null;
+    const top = sumStep(state, `${key}t${index}`, pressure, len);
+    const bottom = sumStep(state, `${key}b${index}`, range, len);
+    averages.push(
+      isPresent(top) && isPresent(bottom) && bottom !== 0 ? result(top / bottom) : NONE,
+    );
+  }
+  const fast = at(averages, 0);
+  const middle = at(averages, 1);
+  const slow = at(averages, 2);
+  if (!isPresent(fast) || !isPresent(middle) || !isPresent(slow)) return NONE;
+  return result((100 * (4 * fast + 2 * middle + slow)) / 7);
+}
+
+/** `ultimateOsc(len1, len2, len3)` as a tail. */
+export function ultimateOscTail(len1 = 7, len2 = 14, len3 = 28): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => ultimateOscStep(state, '', bar, len1, len2, len3));
+}
+
+/** `ultimateOsc(len1, len2, len3)` over a run of bars. */
+export function ultimateOsc(
+  bars: readonly Bar[],
+  len1 = 7,
+  len2 = 14,
+  len3 = 28,
+): Value[] {
+  return fold(ultimateOscTail(len1, len2, len3), bars);
+}
+
+/** `awesomeOsc(fast, slow)`: the difference of two simple means of `hl2`, from bar `slow - 1`. */
+export function awesomeOscStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  fast: number | null,
+  slow: number | null,
+): Value {
+  const midpoint = hl2(bar);
+  const near = smaStep(state, `${key}f`, midpoint, fast);
+  const far = smaStep(state, `${key}s`, midpoint, slow);
+  if (!isPresent(near) || !isPresent(far)) return NONE;
+  return result(near - far);
+}
+
+/** `awesomeOsc(fast, slow)` as a tail. */
+export function awesomeOscTail(fast = 5, slow = 34): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => awesomeOscStep(state, '', bar, fast, slow));
+}
+
+/** `awesomeOsc(fast, slow)` over a run of bars. */
+export function awesomeOsc(bars: readonly Bar[], fast = 5, slow = 34): Value[] {
+  return fold(awesomeOscTail(fast, slow), bars);
+}

package/src/core/stdlib/momentum/rates.ts

@@ -0,0 +1,188 @@
+/**
+ * The readings taken from change rather than from level: `mom`, `roc`, `cmo`,
+ * `trix`, `tsi` and `dpo`.
+ *
+ * Each one's warmup carries the extra bar a change costs, and `stdlib.md`
+ * section 5 states it in the entry rather than leaving it to be derived.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
+import { emaStep, smaStep } from '../averages/index.js';
+import { changeStep, changeTail, historyStep, sumStep } from '../series/index.js';
+
+/** `mom(src, len)`: `src - src[len]`, from bar `len`. */
+export function momTail(len = 10): Tail<Value, Value> {
+  return changeTail(len);
+}
+
+/** `mom(src, len)` over a whole series. */
+export function mom(src: Series, len = 10): Value[] {
+  return fold(momTail(len), src);
+}
+
+/** `roc(src, len)`: the same change as a percentage of the older value, from bar `len`. */
+export function rocStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const then = historyStep(state, `${key}h`, value, len);
+  const delta = changeStep(state, `${key}c`, value, len);
+  if (!isPresent(then) || !isPresent(delta) || then === 0) return NONE;
+  return result((100 * delta) / then);
+}
+
+/** `roc(src, len)` as a tail. */
+export function rocTail(len = 9): Tail<Value, Value> {
+  return tailOf((state, value: Value) => rocStep(state, '', value, len));
+}
+
+/** `roc(src, len)` over a whole series. */
+export function roc(src: Series, len = 9): Value[] {
+  return fold(rocTail(len), src);
+}
+
+/**
+ * `cmo(src, len)`: up sum less down sum over their total, -100 to 100, from bar
+ * `len`.
+ *
+ * Unsmoothed, which is the whole point of it: the sums are taken over the
+ * lookback outright rather than through an average, so a turn shows on the bar it
+ * happens.
+ */
+export function cmoStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const delta = changeStep(state, `${key}c`, value, 1);
+  const up = isPresent(delta) ? result(Math.max(delta, 0)) : NONE;
+  const down = isPresent(delta) ? result(Math.max(-delta, 0)) : NONE;
+  const rise = sumStep(state, `${key}u`, up, len);
+  const fall = sumStep(state, `${key}d`, down, len);
+  if (!isPresent(rise) || !isPresent(fall)) return NONE;
+  const total = rise + fall;
+  if (total === 0) return NONE;
+  return result((100 * (rise - fall)) / total);
+}
+
+/** `cmo(src, len)` as a tail. */
+export function cmoTail(len = 9): Tail<Value, Value> {
+  return tailOf((state, value: Value) => cmoStep(state, '', value, len));
+}
+
+/** `cmo(src, len)` over a whole series. */
+export function cmo(src: Series, len = 9): Value[] {
+  return fold(cmoTail(len), src);
+}
+
+/**
+ * `trix(src, len)`: the rate of change of a triple exponential mean, from bar
+ * `3 * len - 2`.
+ *
+ * `stdlib.md` section 5 says rate of change, so this is the percentage change
+ * of the smoothed series over one bar. The other reading in circulation takes
+ * the change of the logarithm of the average instead; it is a different number
+ * and it is not what the entry describes.
+ */
+export function trixStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const once = emaStep(state, `${key}a`, value, len);
+  const twice = emaStep(state, `${key}b`, once, len);
+  const smoothed = emaStep(state, `${key}c`, twice, len);
+  const before = historyStep(state, `${key}h`, smoothed, 1);
+  if (!isPresent(smoothed) || !isPresent(before) || before === 0) return NONE;
+  return result((100 * (smoothed - before)) / before);
+}
+
+/** `trix(src, len)` as a tail. */
+export function trixTail(len = 18): Tail<Value, Value> {
+  return tailOf((state, value: Value) => trixStep(state, '', value, len));
+}
+
+/** `trix(src, len)` over a whole series. */
+export function trix(src: Series, len = 18): Value[] {
+  return fold(trixTail(len), src);
+}
+
+/**
+ * `tsi(src, longLen, shortLen)`: double smoothed momentum, from bar
+ * `longLen + shortLen - 1`.
+ *
+ * The change smoothed twice, over the size of the change smoothed the same way
+ * twice, so the result is a direction rather than a magnitude and the noise
+ * `mom` carries is gone.
+ */
+export function tsiStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  longLen: number | null,
+  shortLen: number | null,
+): Value {
+  const delta = changeStep(state, `${key}c`, value, 1);
+  const size = isPresent(delta) ? result(Math.abs(delta)) : NONE;
+  const direction = emaStep(
+    state,
+    `${key}n`,
+    emaStep(state, `${key}m`, delta, longLen),
+    shortLen,
+  );
+  const magnitude = emaStep(
+    state,
+    `${key}z`,
+    emaStep(state, `${key}y`, size, longLen),
+    shortLen,
+  );
+  if (!isPresent(direction) || !isPresent(magnitude) || magnitude === 0) return NONE;
+  return result((100 * direction) / magnitude);
+}
+
+/** `tsi(src, longLen, shortLen)` as a tail. */
+export function tsiTail(longLen = 25, shortLen = 13): Tail<Value, Value> {
+  return tailOf((state, value: Value) => tsiStep(state, '', value, longLen, shortLen));
+}
+
+/** `tsi(src, longLen, shortLen)` over a whole series. */
+export function tsi(src: Series, longLen = 25, shortLen = 13): Value[] {
+  return fold(tsiTail(longLen, shortLen), src);
+}
+
+/**
+ * `dpo(src, len)`: price with its displaced mean removed, from bar
+ * `len + floor(len / 2)`.
+ *
+ * The mean is read `floor(len / 2) + 1` bars back rather than at this bar,
+ * which is what "displaced" means here and what the declared warmup requires:
+ * the average's own first value at bar `len - 1`, plus the displacement, is
+ * exactly `len + floor(len / 2)`. Removing an undisplaced mean would be a
+ * different study with a warmup of `len - 1`.
+ */
+export function dpoStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const average = smaStep(state, `${key}q`, value, len);
+  const back = len === null ? null : Math.floor(len / 2) + 1;
+  const mean = historyStep(state, `${key}h`, average, back);
+  if (!isPresent(value) || !isPresent(mean)) return NONE;
+  return result(value - mean);
+}
+
+/** `dpo(src, len)` as a tail. */
+export function dpoTail(len = 21): Tail<Value, Value> {
+  return tailOf((state, value: Value) => dpoStep(state, '', value, len));
+}
+
+/** `dpo(src, len)` over a whole series. */
+export function dpo(src: Series, len = 21): Value[] {
+  return fold(dpoTail(len), src);
+}

package/src/core/stdlib/momentum/rsi.ts

@@ -0,0 +1,49 @@
+/**
+ * `rsi(src, len)`.
+ *
+ * **The first value is at bar `len`, not at bar `len - 1`.** `rsi` needs `len`
+ * changes and a change needs two bars, so the smoothing's lookback is bars 1 to
+ * `len`. `stdlib.md` section 5 states this warmup rather than leaving a reader
+ * to work it out, and every entry in that section which consumes changes rather
+ * than levels carries the same extra bar.
+ *
+ * The smoothing is `rma`, seeded with the simple average of the first `len`
+ * changes, which is what makes this the classic reading rather than one of the
+ * several averages that also produce a number between 0 and 100.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
+import { rmaStep } from '../averages/index.js';
+import { changeStep } from '../series/index.js';
+
+/** `rsi(src, len)`: from bar `len`. */
+export function rsiStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const delta = changeStep(state, `${key}c`, value, 1);
+  const up = isPresent(delta) ? result(Math.max(delta, 0)) : NONE;
+  const down = isPresent(delta) ? result(Math.max(-delta, 0)) : NONE;
+  const averageUp = rmaStep(state, `${key}u`, up, len);
+  const averageDown = rmaStep(state, `${key}d`, down, len);
+  if (!isPresent(averageUp) || !isPresent(averageDown)) return NONE;
+  // No down bar in the lookback is the top of the scale. This also catches a
+  // lookback that never moved at all, where both averages are zero and the
+  // ratio has no value; every reference implementation reads 100 there, and
+  // disagreeing with all of them on a flat lookback would be a worse answer
+  // than the one they give.
+  if (averageDown === 0) return 100;
+  return result(100 - 100 / (1 + averageUp / averageDown));
+}
+
+/** `rsi(src, len)` as a tail. */
+export function rsiTail(len = 14): Tail<Value, Value> {
+  return tailOf((state, value: Value) => rsiStep(state, '', value, len));
+}
+
+/** `rsi(src, len)` over a whole series. */
+export function rsi(src: Series, len = 14): Value[] {
+  return fold(rsiTail(len), src);
+}

package/src/core/stdlib/momentum/stochastic.ts

@@ -0,0 +1,147 @@
+/**
+ * Where a value sits inside a lookback's range: `stoch`, `stochRsi` and
+ * `williamsR`.
+ *
+ * All three are the same test with different sources and different scales.
+ * They are written once, as `position`, so the three cannot drift apart.
+ */
+import type { Bar, Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
+import { smaStep } from '../averages/index.js';
+import { extremeStep } from '../series/index.js';
+
+import { rsiStep } from './rsi.js';
+
+/** Where `value` sits between `low` and `high`, as 0 to 100. Absent on a flat range. */
+function position(value: Value, high: Value, low: Value): Value {
+  if (!isPresent(value) || !isPresent(high) || !isPresent(low)) return NONE;
+  const span = high - low;
+  if (span === 0) return NONE;
+  return result((100 * (value - low)) / span);
+}
+
+/** The largest value in the last `len` bars, as the three studies here read it. */
+function topStep(state: StateRecord, key: string, value: Value, len: number | null): Value {
+  return extremeStep(state, key, value, len, true, false);
+}
+
+/** The smallest value in the last `len` bars. */
+function bottomStep(state: StateRecord, key: string, value: Value, len: number | null): Value {
+  return extremeStep(state, key, value, len, false, false);
+}
+
+/** The raw range position of a series against its own lookback. */
+function rawStep(state: StateRecord, key: string, value: Value, len: number | null): Value {
+  const high = topStep(state, `${key}t`, value, len);
+  const low = bottomStep(state, `${key}b`, value, len);
+  return position(value, high, low);
+}
+
+/**
+ * `stoch(len, smoothK, smoothD)`: `[k, d]`, element 0 from bar
+ * `len + smoothK - 2` and element 1 from bar `len + smoothK + smoothD - 3`.
+ *
+ * The close against the lookback's outright high and low, which are the bars'
+ * highs and lows and not the close's own extremes.
+ */
+export function stochStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+  smoothK: number | null,
+  smoothD: number | null,
+): Value[] {
+  const high = topStep(state, `${key}t`, bar.high, len);
+  const low = bottomStep(state, `${key}b`, bar.low, len);
+  const raw = position(bar.close, high, low);
+  const k = smaStep(state, `${key}k`, raw, smoothK);
+  const d = smaStep(state, `${key}d`, k, smoothD);
+  return [k, d];
+}
+
+/** `stoch(len, smoothK, smoothD)` as a tail. */
+export function stochTail(len = 14, smoothK = 1, smoothD = 3): Tail<Bar, Value[]> {
+  return tailOf((state, bar: Bar) => stochStep(state, '', bar, len, smoothK, smoothD));
+}
+
+/** `stoch(len, smoothK, smoothD)` over a run of bars. */
+export function stoch(bars: readonly Bar[], len = 14, smoothK = 1, smoothD = 3): Value[][] {
+  return fold(stochTail(len, smoothK, smoothD), bars);
+}
+
+/**
+ * `stochRsi(src, rsiLen, stochLen, smoothK, smoothD)`: `[k, d]`, element 0 from
+ * bar `rsiLen + stochLen + smoothK - 2`.
+ *
+ * The same position test applied to `rsi` rather than to price, so the lookback
+ * is the range the strength reading itself covered.
+ */
+export function stochRsiStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  rsiLen: number | null,
+  stochLen: number | null,
+  smoothK: number | null,
+  smoothD: number | null,
+): Value[] {
+  const strength = rsiStep(state, `${key}r`, value, rsiLen);
+  const raw = rawStep(state, `${key}p`, strength, stochLen);
+  const k = smaStep(state, `${key}k`, raw, smoothK);
+  const d = smaStep(state, `${key}d`, k, smoothD);
+  return [k, d];
+}
+
+/** `stochRsi(src, rsiLen, stochLen, smoothK, smoothD)` as a tail. */
+export function stochRsiTail(
+  rsiLen = 14,
+  stochLen = 14,
+  smoothK = 3,
+  smoothD = 3,
+): Tail<Value, Value[]> {
+  return tailOf((state, value: Value) =>
+    stochRsiStep(state, '', value, rsiLen, stochLen, smoothK, smoothD),
+  );
+}
+
+/** `stochRsi(src, rsiLen, stochLen, smoothK, smoothD)` over a whole series. */
+export function stochRsi(
+  src: Series,
+  rsiLen = 14,
+  stochLen = 14,
+  smoothK = 3,
+  smoothD = 3,
+): Value[][] {
+  return fold(stochRsiTail(rsiLen, stochLen, smoothK, smoothD), src);
+}
+
+/**
+ * `williamsR(len)`: the same position scaled 0 to -100, from bar `len - 1`.
+ *
+ * Zero at the top of the range and -100 at the bottom, which is the sign
+ * convention the reading has always carried.
+ */
+export function williamsRStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const high = topStep(state, `${key}t`, bar.high, len);
+  const low = bottomStep(state, `${key}b`, bar.low, len);
+  if (!isPresent(bar.close) || !isPresent(high) || !isPresent(low)) return NONE;
+  const span = high - low;
+  if (span === 0) return NONE;
+  return result((-100 * (high - bar.close)) / span);
+}
+
+/** `williamsR(len)` as a tail. */
+export function williamsRTail(len = 14): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => williamsRStep(state, '', bar, len));
+}
+
+/** `williamsR(len)` over a run of bars. */
+export function williamsR(bars: readonly Bar[], len = 14): Value[] {
+  return fold(williamsRTail(len), bars);
+}