openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/stdlib/series/changes.ts

@@ -0,0 +1,177 @@
+/**
+ * Change over a distance, runs of it, and crossings.
+ *
+ * `crossUp` reads "at or below, then above" rather than "strictly below, then
+ * above", which `stdlib.md` section 9 states and gives the reason for: two
+ * series that touch and separate report one cross rather than none, and touching
+ * is common on an instrument with a coarse tick.
+ */
+import type { Flag, Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, ring, tailOf } from '../values/index.js';
+
+/** `change(src, len)`: `src - src[len]`, from bar `len`. */
+export function changeStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const lookback = ring(state, key, len === null ? null : len + 1);
+  lookback.push(value);
+  if (len === null || !lookback.filled()) return NONE;
+  const now = lookback.at(0);
+  const then = lookback.at(len);
+  if (!isPresent(now) || !isPresent(then)) return NONE;
+  return result(now - then);
+}
+
+/** `change(src, len)` as a tail. */
+export function changeTail(len = 1): Tail<Value, Value> {
+  return tailOf((state, value: Value) => changeStep(state, 'c', value, len));
+}
+
+/** `change(src, len)` over a whole series. */
+export function change(src: Series, len = 1): Value[] {
+  return fold(changeTail(len), src);
+}
+
+/** `history(src, n)`: `src` as it stood `n` bars ago, from bar `n`. */
+export function historyStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  back: number | null,
+): Value {
+  const lookback = ring(state, key, back === null ? null : back + 1);
+  lookback.push(value);
+  return back !== null && lookback.filled() ? lookback.at(back) : NONE;
+}
+
+/** `history(src, n)` as a tail. */
+export function historyTail(back: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => historyStep(state, 'h', value, back));
+}
+
+/** `history(src, n)` over a whole series. */
+export function history(src: Series, back: number): Value[] {
+  return fold(historyTail(back), src);
+}
+
+/** `rising` and `falling`: every one of the last `len` changes went one way. */
+export function runStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  wantUp: boolean,
+): Flag {
+  const lookback = ring(state, key, len === null ? null : len + 1);
+  lookback.push(value);
+  if (len === null || !lookback.filled()) return null;
+  // Oldest first, comparing each bar with the one before it.
+  for (let back = len - 1; back >= 0; back -= 1) {
+    const now = lookback.at(back);
+    const before = lookback.at(back + 1);
+    if (!isPresent(now) || !isPresent(before)) return null;
+    if (wantUp ? !(now > before) : !(now < before)) return false;
+  }
+  return true;
+}
+
+/** `rising(src, len)`: true when each of the last `len` changes was positive, from bar `len`. */
+export function risingTail(len: number): Tail<Value, Flag> {
+  return tailOf((state, value: Value) => runStep(state, 'q', value, len, true));
+}
+
+/** `rising(src, len)` over a whole series. */
+export function rising(src: Series, len: number): Flag[] {
+  return fold(risingTail(len), src);
+}
+
+/** `falling(src, len)`: true when each of the last `len` changes was negative, from bar `len`. */
+export function fallingTail(len: number): Tail<Value, Flag> {
+  return tailOf((state, value: Value) => runStep(state, 'q', value, len, false));
+}
+
+/** `falling(src, len)` over a whole series. */
+export function falling(src: Series, len: number): Flag[] {
+  return fold(fallingTail(len), src);
+}
+
+/** A pair of series read on the same bar, for the crossing tests. */
+export interface Pair {
+  readonly a: Value;
+  readonly b: Value;
+}
+
+/** Which way a crossing counts. */
+export type Direction = 'up' | 'down' | 'either';
+
+/**
+ * The crossing test, which keeps the two series apart rather than subtracting.
+ *
+ * A difference would round, and the whole test turns on whether one series was
+ * at or below the other, which is the one place a rounded zero would change the
+ * answer.
+ */
+export function crossStep(
+  state: StateRecord,
+  key: string,
+  pair: Pair,
+  direction: Direction,
+): Flag {
+  const left = ring(state, `${key}a`, 2);
+  const right = ring(state, `${key}b`, 2);
+  left.push(pair.a);
+  right.push(pair.b);
+  if (!left.filled()) return null;
+  const nowA = left.at(0);
+  const nowB = right.at(0);
+  const beforeA = left.at(1);
+  const beforeB = right.at(1);
+  if (!isPresent(nowA) || !isPresent(nowB)) return null;
+  if (!isPresent(beforeA) || !isPresent(beforeB)) return null;
+  const up = beforeA <= beforeB && nowA > nowB;
+  const down = beforeA >= beforeB && nowA < nowB;
+  if (direction === 'up') return up;
+  if (direction === 'down') return down;
+  return up || down;
+}
+
+function crossTail(direction: Direction): Tail<Pair, Flag> {
+  return tailOf((state, pair: Pair) => crossStep(state, '', pair, direction));
+}
+
+/** `crossUp(a, b)`: `a` was at or below `b` and is now above, from bar 1. */
+export function crossUpTail(): Tail<Pair, Flag> {
+  return crossTail('up');
+}
+
+/** `crossDown(a, b)`: `a` was at or above `b` and is now below, from bar 1. */
+export function crossDownTail(): Tail<Pair, Flag> {
+  return crossTail('down');
+}
+
+/** `cross(a, b)`: either direction, from bar 1. */
+export function crossEitherTail(): Tail<Pair, Flag> {
+  return crossTail('either');
+}
+
+function pairs(a: Series, b: Series): Pair[] {
+  return a.map((value, index) => ({ a: value, b: b[index] ?? NONE }));
+}
+
+/** `crossUp(a, b)` over whole series. */
+export function crossUp(a: Series, b: Series): Flag[] {
+  return fold(crossUpTail(), pairs(a, b));
+}
+
+/** `crossDown(a, b)` over whole series. */
+export function crossDown(a: Series, b: Series): Flag[] {
+  return fold(crossDownTail(), pairs(a, b));
+}
+
+/** `cross(a, b)` over whole series. */
+export function cross(a: Series, b: Series): Flag[] {
+  return fold(crossEitherTail(), pairs(a, b));
+}

package/src/core/stdlib/series/conditions.ts

@@ -0,0 +1,74 @@
+/**
+ * The two functions that look back to the last time something happened.
+ *
+ * Both are absent, not zero, before the condition has ever been true.
+ * `stdlib.md` section 9 states it and the reason is that zero would read as "it
+ * happened on this bar", which is the one answer a reader would act on.
+ */
+import type { Flag, Flags, Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, queue, slot, tailOf } from '../values/index.js';
+
+/** `barsSince(cond)`: bars since the condition last held, 0 on the bar itself. */
+export function barsSinceStep(state: StateRecord, key: string, cond: Flag): Value {
+  let since = slot(state, key, -1);
+  if (cond === true) since = 0;
+  else if (since >= 0) since += 1;
+  state[key] = since;
+  return since < 0 ? NONE : since;
+}
+
+/** `barsSince(cond)` as a tail. */
+export function barsSinceTail(): Tail<Flag, Value> {
+  return tailOf((state, cond: Flag) => barsSinceStep(state, 's', cond));
+}
+
+/** `barsSince(cond)` over a whole series. */
+export function barsSince(cond: Flags): Value[] {
+  return fold(barsSinceTail(), cond);
+}
+
+/** A condition and the value to remember when it holds, read on the same bar. */
+export interface Occasion {
+  readonly cond: Flag;
+  readonly src: Value;
+}
+
+/**
+ * `valueWhen(cond, src, occurrence)`: `src` as it stood the last time the
+ * condition held, or the one before that.
+ *
+ * Only the `occurrence + 1` most recent hits are kept, so the memory is fixed
+ * by the argument rather than by how much history is loaded. A region whose
+ * queue grew with the dataset would not be copyable in the sense
+ * `compiled-program.md` 2.11 requires.
+ */
+export function valueWhenStep(
+  state: StateRecord,
+  key: string,
+  input: Occasion,
+  occurrence: number,
+): Value {
+  if (!Number.isInteger(occurrence) || occurrence < 0) return NONE;
+  const wanted = occurrence + 1;
+  const hits = queue(state, key);
+  if (input.cond === true) {
+    hits.push(input.src);
+    if (hits.length > wanted) hits.shift();
+  }
+  if (hits.length !== wanted) return NONE;
+  const first = hits[0];
+  return typeof first === 'number' ? first : NONE;
+}
+
+/** `valueWhen(cond, src, occurrence)` as a tail. */
+export function valueWhenTail(occurrence = 0): Tail<Occasion, Value> {
+  return tailOf((state, input: Occasion) => valueWhenStep(state, 'v', input, occurrence));
+}
+
+/** `valueWhen(cond, src, occurrence)` over whole series. */
+export function valueWhen(cond: Flags, src: Series, occurrence = 0): Value[] {
+  return fold(
+    valueWhenTail(occurrence),
+    cond.map((flag, index) => ({ cond: flag, src: src[index] ?? NONE })),
+  );
+}

package/src/core/stdlib/series/extremes.ts

@@ -0,0 +1,92 @@
+/**
+ * The lookback extremes: `highest`, `lowest` and the two that report where the
+ * extreme was set.
+ *
+ * `highestBars` and `lowestBars` count bars back, 0 being this bar, which is
+ * what `stdlib.md` section 9 says they return. A tie goes to the most recent
+ * bar: the lookback's high was set most recently at that bar, and reporting the
+ * older one would make the answer jump backwards as an equal high rolls in.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, result, ring, tailOf } from '../values/index.js';
+
+/** Where the extreme sits in a complete lookback, as bars back from this one. */
+function extremeBack(
+  read: (back: number) => Value,
+  len: number,
+  wantHigh: boolean,
+): number {
+  let best = read(len - 1) as number;
+  let bestBack = len - 1;
+  // Oldest first, so an equal value later in the lookback replaces the earlier
+  // one and the answer is the most recent bar that set the extreme.
+  for (let position = 1; position < len; position += 1) {
+    const back = len - 1 - position;
+    const value = read(back) as number;
+    if (wantHigh ? value >= best : value <= best) {
+      best = value;
+      bestBack = back;
+    }
+  }
+  return bestBack;
+}
+
+/** `highest`, `lowest` and the two that report where the extreme was set. */
+export function extremeStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  wantHigh: boolean,
+  asBars: boolean,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || !lookback.complete()) return NONE;
+  const back = extremeBack((k) => lookback.at(k), len, wantHigh);
+  return asBars ? back : result(lookback.at(back) as number);
+}
+
+function extremeTail(len: number, wantHigh: boolean, asBars: boolean): Tail<Value, Value> {
+  return tailOf((state, value: Value) => extremeStep(state, 'q', value, len, wantHigh, asBars));
+}
+
+/** `highest(src, len)`: the largest value in the last `len` bars, from bar `len - 1`. */
+export function highestTail(len: number): Tail<Value, Value> {
+  return extremeTail(len, true, false);
+}
+
+/** `highest(src, len)` over a whole series. */
+export function highest(src: Series, len: number): Value[] {
+  return fold(highestTail(len), src);
+}
+
+/** `lowest(src, len)`: the smallest value in the last `len` bars, from bar `len - 1`. */
+export function lowestTail(len: number): Tail<Value, Value> {
+  return extremeTail(len, false, false);
+}
+
+/** `lowest(src, len)` over a whole series. */
+export function lowest(src: Series, len: number): Value[] {
+  return fold(lowestTail(len), src);
+}
+
+/** `highestBars(src, len)`: how many bars back the lookback's high was set. */
+export function highestBarsTail(len: number): Tail<Value, Value> {
+  return extremeTail(len, true, true);
+}
+
+/** `highestBars(src, len)` over a whole series. */
+export function highestBars(src: Series, len: number): Value[] {
+  return fold(highestBarsTail(len), src);
+}
+
+/** `lowestBars(src, len)`: how many bars back the lookback's low was set. */
+export function lowestBarsTail(len: number): Tail<Value, Value> {
+  return extremeTail(len, false, true);
+}
+
+/** `lowestBars(src, len)` over a whole series. */
+export function lowestBars(src: Series, len: number): Value[] {
+  return fold(lowestBarsTail(len), src);
+}

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

@@ -0,0 +1,83 @@
+export {
+  extremeStep,
+  highest,
+  highestBars,
+  highestBarsTail,
+  highestTail,
+  lowest,
+  lowestBars,
+  lowestBarsTail,
+  lowestTail,
+} from './extremes.js';
+
+export type { Direction, Pair } from './changes.js';
+export {
+  change,
+  changeStep,
+  changeTail,
+  cross,
+  crossDown,
+  crossDownTail,
+  crossEitherTail,
+  crossStep,
+  crossUp,
+  crossUpTail,
+  falling,
+  fallingTail,
+  history,
+  historyStep,
+  historyTail,
+  rising,
+  risingTail,
+  runStep,
+} from './changes.js';
+
+export {
+  avgSkip,
+  avgSkipStep,
+  avgSkipTail,
+  count,
+  countPresent,
+  countPresentStep,
+  countPresentTail,
+  countStep,
+  countTail,
+  cum,
+  cumStep,
+  cumTail,
+  sum,
+  sumSkip,
+  sumSkipStep,
+  sumSkipTail,
+  sumStep,
+  sumTail,
+} from './totals.js';
+
+export type { Occasion } from './conditions.js';
+export {
+  barsSince,
+  barsSinceStep,
+  barsSinceTail,
+  valueWhen,
+  valueWhenStep,
+  valueWhenTail,
+} from './conditions.js';
+
+export { pivotHigh, pivotHighTail, pivotLow, pivotLowTail, pivotStep } from './pivots.js';
+
+export {
+  correlation,
+  correlationStep,
+  correlationTail,
+  covariance,
+  covarianceStep,
+  covarianceTail,
+  median,
+  medianTail,
+  percentRank,
+  percentRankStep,
+  percentRankTail,
+  percentile,
+  percentileStep,
+  percentileTail,
+} from './statistics.js';

package/src/core/stdlib/series/pivots.ts

@@ -0,0 +1,63 @@
+/**
+ * `pivotHigh` and `pivotLow`.
+ *
+ * The answer lands on the bar `right` bars after the pivot, which is the first
+ * bar on which the pivot is knowable. Returning it at the pivot bar would be a
+ * lookahead: the value would appear on history at a bar where no script could
+ * have had it, and a backtest built on that is a backtest of a strategy nobody
+ * could have run.
+ *
+ * Comparisons are strict on both sides, so an equal neighbour means there is no
+ * pivot there. A run of equal highs has no single highest bar, and picking one
+ * of them would make the answer depend on which end the scan started from.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, ring, tailOf } from '../values/index.js';
+
+/** `pivotHigh` and `pivotLow`, answered on the bar the pivot becomes knowable. */
+export function pivotStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  left: number | null,
+  right: number | null,
+  wantHigh: boolean,
+): Value {
+  const span = left === null || right === null ? null : left + right + 1;
+  const lookback = ring(state, key, span);
+  lookback.push(value);
+  if (span === null || right === null || !lookback.filled()) return NONE;
+  const candidate = lookback.at(right);
+  if (!isPresent(candidate)) return NONE;
+  for (let back = span - 1; back >= 0; back -= 1) {
+    if (back === right) continue;
+    const other = lookback.at(back);
+    if (!isPresent(other)) return NONE;
+    if (wantHigh ? other >= candidate : other <= candidate) return NONE;
+  }
+  return result(candidate);
+}
+
+function pivotTail(left: number, right: number, wantHigh: boolean): Tail<Value, Value> {
+  return tailOf((state, value: Value) => pivotStep(state, 'q', value, left, right, wantHigh));
+}
+
+/** `pivotHigh(src, left, right)`: the value of a local high, from bar `left + right`. */
+export function pivotHighTail(left: number, right: number): Tail<Value, Value> {
+  return pivotTail(left, right, true);
+}
+
+/** `pivotHigh(src, left, right)` over a whole series. */
+export function pivotHigh(src: Series, left: number, right: number): Value[] {
+  return fold(pivotHighTail(left, right), src);
+}
+
+/** `pivotLow(src, left, right)`: the value of a local low, from bar `left + right`. */
+export function pivotLowTail(left: number, right: number): Tail<Value, Value> {
+  return pivotTail(left, right, false);
+}
+
+/** `pivotLow(src, left, right)` over a whole series. */
+export function pivotLow(src: Series, left: number, right: number): Value[] {
+  return fold(pivotLowTail(left, right), src);
+}

package/src/core/stdlib/series/statistics.ts

@@ -0,0 +1,207 @@
+/**
+ * Order statistics and the two joint statistics.
+ *
+ * `percentile` interpolates linearly between the two ranks either side, which
+ * `stdlib.md` section 9 states. The nearest rank method, which returns an
+ * actual member of the lookback, is the other common choice and gives a visibly
+ * different answer for an even length lookback; it is not what is specified here.
+ *
+ * `covariance` and `correlation` are the population forms, and both are taken
+ * in two passes: the mean first, then the deviations from it. The single pass
+ * arrangement, summing squares and cross products and subtracting at the end,
+ * needs one fewer pass and loses most of its significant digits when the values
+ * are large and their spread is small, which is exactly what a price series is.
+ * `stdlib.md` fixes neither arrangement, so this one is chosen and stated.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, result, ring, tailOf } from '../values/index.js';
+
+import type { Pair } from './changes.js';
+
+/** The lookback's values, oldest first, as plain numbers. */
+function ordered(read: (back: number) => Value, len: number): number[] {
+  const values: number[] = [];
+  for (let back = len - 1; back >= 0; back -= 1) values.push(read(back) as number);
+  return values;
+}
+
+/**
+ * `percentile(src, len, p)`: the value at percentile `p` of the lookback,
+ * linearly interpolated, from bar `len - 1`.
+ */
+export function percentileStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  p: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || p === null || !lookback.complete()) return NONE;
+  if (!(p >= 0 && p <= 100)) return NONE;
+  const sorted = ordered((back) => lookback.at(back), len).sort((a, b) => a - b);
+  const rank = (p / 100) * (len - 1);
+  const below = Math.floor(rank);
+  const above = below + 1;
+  const low = sorted[below] as number;
+  if (above >= len) return result(low);
+  const high = sorted[above] as number;
+  return result(low + (rank - below) * (high - low));
+}
+
+/** `percentile(src, len, p)` as a tail. */
+export function percentileTail(len: number, p: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => percentileStep(state, 'q', value, len, p));
+}
+
+/** `percentile(src, len, p)` over a whole series. */
+export function percentile(src: Series, len: number, p: number): Value[] {
+  return fold(percentileTail(len, p), src);
+}
+
+/**
+ * `median(src, len)`: the middle value of the lookback, from bar `len - 1`.
+ *
+ * The 50th percentile by the same interpolation, so an even length lookback is
+ * the mean of its two middles rather than one of them chosen by a rule nobody
+ * remembers.
+ */
+export function medianTail(len: number): Tail<Value, Value> {
+  return percentileTail(len, 50);
+}
+
+/** `median(src, len)` over a whole series. */
+export function median(src: Series, len: number): Value[] {
+  return fold(medianTail(len), src);
+}
+
+/**
+ * `percentRank(src, len)`: what percentage of the lookback this bar's value
+ * exceeds, from bar `len - 1`.
+ *
+ * The lookback is the last `len` bars including this one, which is what the
+ * declared warmup of bar `len - 1` says: a lookback of the `len` bars before this
+ * one would not have its first answer until bar `len`. This bar is therefore
+ * one of the values counted, so the reading runs from `100 / len` to 100 rather
+ * than from 0.
+ */
+export function percentRankStep(
+  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 current = lookback.at(0) as number;
+  let counted = 0;
+  for (let back = len - 1; back >= 0; back -= 1) {
+    if ((lookback.at(back) as number) <= current) counted += 1;
+  }
+  return result((counted * 100) / len);
+}
+
+/** `percentRank(src, len)` as a tail. */
+export function percentRankTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => percentRankStep(state, 'q', value, len));
+}
+
+/** `percentRank(src, len)` over a whole series. */
+export function percentRank(src: Series, len: number): Value[] {
+  return fold(percentRankTail(len), src);
+}
+
+interface Moments {
+  readonly covariance: number;
+  readonly varianceA: number;
+  readonly varianceB: number;
+}
+
+function moments(a: readonly number[], b: readonly number[], len: number): Moments {
+  let sumA = 0;
+  let sumB = 0;
+  for (let index = 0; index < len; index += 1) {
+    sumA += a[index] as number;
+    sumB += b[index] as number;
+  }
+  const meanA = sumA / len;
+  const meanB = sumB / len;
+  let cross = 0;
+  let squaresA = 0;
+  let squaresB = 0;
+  for (let index = 0; index < len; index += 1) {
+    const deviationA = (a[index] as number) - meanA;
+    const deviationB = (b[index] as number) - meanB;
+    cross += deviationA * deviationB;
+    squaresA += deviationA * deviationA;
+    squaresB += deviationB * deviationB;
+  }
+  return { covariance: cross / len, varianceA: squaresA / len, varianceB: squaresB / len };
+}
+
+function jointStep(
+  state: StateRecord,
+  key: string,
+  pair: Pair,
+  len: number | null,
+  want: 'covariance' | 'correlation',
+): Value {
+  const left = ring(state, `${key}a`, len);
+  const right = ring(state, `${key}b`, len);
+  left.push(pair.a);
+  right.push(pair.b);
+  if (len === null || !left.complete() || !right.complete()) return NONE;
+  const a = ordered((back) => left.at(back), len);
+  const b = ordered((back) => right.at(back), len);
+  const m = moments(a, b, len);
+  if (want === 'covariance') return result(m.covariance);
+  const scale = Math.sqrt(m.varianceA) * Math.sqrt(m.varianceB);
+  if (scale === 0) return NONE;
+  return result(m.covariance / scale);
+}
+
+/** `covariance(a, b, len)`: the population covariance, from bar `len - 1`. */
+export function covarianceStep(
+  state: StateRecord,
+  key: string,
+  pair: Pair,
+  len: number | null,
+): Value {
+  return jointStep(state, key, pair, len, 'covariance');
+}
+
+/** `correlation(a, b, len)`: linear correlation, -1 to 1, from bar `len - 1`. */
+export function correlationStep(
+  state: StateRecord,
+  key: string,
+  pair: Pair,
+  len: number | null,
+): Value {
+  return jointStep(state, key, pair, len, 'correlation');
+}
+
+/** `covariance(a, b, len)` as a tail. */
+export function covarianceTail(len: number): Tail<Pair, Value> {
+  return tailOf((state, pair: Pair) => covarianceStep(state, 'q', pair, len));
+}
+
+/** `correlation(a, b, len)` as a tail. */
+export function correlationTail(len: number): Tail<Pair, Value> {
+  return tailOf((state, pair: Pair) => correlationStep(state, 'q', pair, len));
+}
+
+function pairs(a: Series, b: Series): Pair[] {
+  return a.map((value, index) => ({ a: value, b: b[index] ?? NONE }));
+}
+
+/** `covariance(a, b, len)` over whole series. */
+export function covariance(a: Series, b: Series, len: number): Value[] {
+  return fold(covarianceTail(len), pairs(a, b));
+}
+
+/** `correlation(a, b, len)` over whole series. */
+export function correlation(a: Series, b: Series, len: number): Value[] {
+  return fold(correlationTail(len), pairs(a, b));
+}