oakscriptjs 0.9.5 → 0.9.6

package/src/ta/index.ts

@@ -10,13 +10,13 @@
 
 import type { series_float, series_bool, series_int, int, Source, simple_int, simple_float, simple_bool } from '../types/index.js';
 import { eq, ge, gt, le, lt } from '../compare/index.js';
-import { runningSum, runningVariance } from './running-sum.js';
+import { runningSum, runningSumSeries, runningVariance, runningVarianceSeries } from './running-sum.js';
 
 /**
  * Simple Moving Average - returns the moving average (sum of last y values divided by y).
  *
  * @param source - Series of values to process
- * @param length - Number of bars (length)
+ * @param length - Number of bars (length), or one length per bar (a series length)
  * @returns Simple moving average of source for length bars back
  *
  * @remarks
@@ -25,30 +25,26 @@ import { runningSum, runningVariance } from './running-sum.js';
  * - Returns NaN until `length` non-`na` values are available
  * - The sum is a compensated running sum, as in PineScript, so the result can differ from the exact window mean in
  *   the last bits (bit for bit with PineScript)
+ * - With a series length, the running sum is moved to the new length when the length changes, as PineScript does
+ *   (see {@link math.sum}); a bar with an `na` source gives the mean of the last `length` earlier values
  *
  * @example
  * ```typescript
  * const closePrices = [10, 11, 12, 13, 14];
  * const sma5 = ta.sma(closePrices, 5); // Returns: [NaN, NaN, NaN, NaN, 12]
+ * const smaVar = ta.sma(closePrices, [2, 2, 2, 3, 2]); // Returns: [NaN, 10.5, 11.5, 12, 13.5]
  * ```
  */
-export function sma(source: Source, length: simple_int): series_float {
+export function sma(source: Source, length: simple_int | ArrayLike<number>): series_float {
+  if (typeof length !== 'number') {
+    const sums = runningSumSeries(source, length, 'ta.sma');
+    return sums.map((sum, i) => sum / Math.floor(length[i]!));
+  }
   // Floor the length to match PineScript's auto-truncation of float to int
   const len = Math.floor(length);
   return runningSum(source, len).map((sum) => sum / len);
 }
 
-/** Mean of the last `length` bars; na when the window holds an na value (used by ta.dev). */
-function strictWindowMean(source: Source, length: simple_int): series_float {
-  const len = Math.floor(length);
-  return Array.from({ length: source.length }, (_, i) => {
-    if (i < len - 1) return NaN;
-    let sum = 0;
-    for (let j = 0; j < len; j++) sum += source[i - j]!;
-    return sum / len;
-  });
-}
-
 /**
  * Exponential Moving Average - returns the exponentially weighted moving average.
  *
@@ -256,7 +252,7 @@ export function bb(
  * Standard deviation over the last `length` non-na values.
  *
  * @param source - Series of values to process
- * @param length - Number of values
+ * @param length - Number of values, or one length per bar (a series length, see {@link sma})
  * @param biased - true (default): biased estimate (divides by `length`); false: unbiased (by `length - 1`)
  * @returns Standard deviation series (na until `length` non-na values exist)
  *
@@ -266,8 +262,12 @@ export function bb(
  * The result is the square root of {@link variance} (0 when the variance is not positive), computed from
  * compensated running sums of the values and of their squares, bit for bit as PineScript.
  */
-export function stdev(source: Source, length: simple_int, biased: simple_bool = true): series_float {
-  return variance(source, length, biased).map((v) => (Number.isNaN(v) ? NaN : v > 0 ? Math.sqrt(v) : 0));
+export function stdev(
+  source: Source,
+  length: simple_int | ArrayLike<number>,
+  biased: simple_bool = true
+): series_float {
+  return varianceOf(source, length, biased, 'ta.stdev').map((v) => (Number.isNaN(v) ? NaN : v > 0 ? Math.sqrt(v) : 0));
 }
 
 /**
@@ -677,7 +677,8 @@ export function supertrend(
  * @remarks
  * - Moving average used in RSI calculation
  * - Alpha = 1 / length (different from EMA which uses alpha = 2 / (length + 1))
- * - First value is initialized with SMA, then uses exponential smoothing
+ * - First value is initialized with SMA, then uses exponential smoothing. As in PineScript, the seed is the
+ *   `ta.sma` value (its compensated running sum), so it can differ from the exact mean in the last bits
  * - Formula: `RMA = (source + (length - 1) * RMA[1]) / length`, evaluated in this order as in PineScript
  *   (equal to `alpha * source + (1 - alpha) * RMA[1]`, but bit for bit)
  * - `na` values (also +/-Infinity) in the source series are ignored
@@ -700,23 +701,18 @@ export function rma(source: Source, length: simple_int): series_float {
   // An infinite value is na, as in PineScript.
   let firstValidIndex = -1;
   let validCount = 0;
-  let initSum = 0;
 
   for (let i = 0; i < source.length; i++) {
     const val = source[i];
-    if (val !== undefined && Number.isFinite(val)) {
-      initSum += val;
-      validCount++;
-      if (validCount === len) {
-        firstValidIndex = i;
-        break;
-      }
+    if (val !== undefined && Number.isFinite(val) && ++validCount === len) {
+      firstValidIndex = i;
+      break;
     }
   }
 
-  // Initialize RMA value with SMA of first `length` non-NaN values
-  let rmaValue = validCount > 0 ? initSum / validCount : NaN;
   const rmaInitialized = firstValidIndex >= 0;
+  // The seed is ta.sma on that bar: the running sum of math.sum (PineScript bits), not a plain loop sum
+  let rmaValue = rmaInitialized ? runningSum(source.slice(0, firstValidIndex + 1), len)[firstValidIndex]! / len : NaN;
 
   for (let i = 0; i < source.length; i++) {
     if (!rmaInitialized || i < firstValidIndex) {
@@ -742,6 +738,15 @@ export function rma(source: Source, length: simple_int): series_float {
   return result;
 }
 
+/**
+ * One step of the PineScript ta.wma sum: `a + b`, or 0 when `|a + b| <= 1e-10 * max(1, |a| + |b|)`.
+ * Measured bit for bit: a sum that cancels to a tiny residue (relative to the operands, or below 1e-10) is 0.
+ */
+function wmaAdd(a: number, b: number): number {
+  const sum = a + b;
+  return Math.abs(sum) <= 1e-10 * Math.max(1, Math.abs(a) + Math.abs(b)) ? 0 : sum;
+}
+
 /**
  * Weighted Moving Average (WMA) - moving average with linearly decreasing weights.
  *
@@ -755,6 +760,8 @@ export function rma(source: Source, length: simple_int): series_float {
  * - Formula: `sum(source[i]! * (length - i)) / sum(length - i)` for i = 0 to length-1
  * - As in PineScript: na on a bar whose source is `na` (also +/-Infinity) and until `length` non-`na` values were
  *   received; an `na` value inside the window is replaced by the previous non-`na` value
+ * - Summed from the oldest value to the newest; as PineScript, a partial sum `s + t` with
+ *   `|s + t| <= 1e-10 * max(1, |s| + |t|)` is 0 (a cancellation residue, or values below 1e-10)
  * - More responsive to recent price changes than SMA
  *
  * @example
@@ -789,7 +796,7 @@ export function wma(source: Source, length: simple_int): series_float {
     let weightSum = 0;
     for (let j = len - 1; j >= 0; j--) {
       const weight = len - j;
-      sum += filled[i - j]! * weight;
+      sum = wmaAdd(sum, filled[i - j]! * weight);
       weightSum += weight;
     }
     result.push(sum / weightSum);
@@ -864,11 +871,12 @@ export function cum(source: Source): series_float {
  * @returns Boolean series (true at cross points)
  *
  * @remarks
- * - True when: (source1[i] > source2[i] AND source1[j] <= source2[j]) OR
- *              (source1[i] < source2[i] AND source1[j] >= source2[j]),
- *   where j is the last bar before i where both values were not na
- * - First value is always false (no previous value to compare)
- * - Detects any crossing (either over or under)
+ * PineScript rule (measured bit for bit; not `crossover or crossunder`):
+ * - The call keeps the side of the last bar where `source1` was strictly above or strictly below `source2` (no
+ *   side before such a bar). Equal bars and bars with an `na` value do not change it.
+ * - True when the values are strictly on the other side of the kept side: so a run of equal values is passed, and
+ *   a series that starts equal and then moves away is not a cross
+ * - False on a bar with an `na` value
  * - Use `ta.crossover()` or `ta.crossunder()` for directional crosses
  *
  * @example
@@ -878,25 +886,37 @@ export function cum(source: Source): series_float {
  * ```
  */
 export function cross(source1: Source, source2: Source): series_bool {
-  return crossTest(source1, source2, (a, b, pa, pb) => (a > b && pa <= pb) || (a < b && pa >= pb));
+  const result: series_bool = [];
+  let side = 0; // -1: last strictly below, 1: last strictly above, 0: none yet
+  for (let i = 0; i < source1.length; i++) {
+    const a = source1[i]!;
+    const b = source2[i]!;
+    if (Number.isNaN(a) || Number.isNaN(b)) {
+      result.push(false);
+      continue;
+    }
+    result.push((side < 0 && a > b) || (side > 0 && a < b));
+    if (a < b) side = -1;
+    else if (a > b) side = 1;
+  }
+  return result;
 }
 
 /**
- * ta.rising / ta.falling: true when each of the `length` steps between the last `length + 1` non-na values (up to
- * the current bar) passes `step(newer, older)`; false when there are fewer non-na values.
+ * ta.rising / ta.falling: a counter of the steps from one bar to the next that pass `step(newer, older)`, reset to 0
+ * by a step that does not pass; a step with an na value (on either bar) leaves the counter unchanged. True when the
+ * counter is at least `length`.
  *
  * @internal
  */
 function monotonic(source: Source, length: simple_int, step: (newer: number, older: number) => boolean): series_bool {
   const result: series_bool = [];
-  const values: number[] = []; // non-na values so far
+  let count = 0;
   for (let i = 0; i < source.length; i++) {
     const v = source[i]!;
-    if (!Number.isNaN(v)) values.push(v);
-    const n = values.length;
-    let ok = n > length;
-    for (let j = 1; ok && j <= length; j++) ok = step(values[n - j]!, values[n - j - 1]!);
-    result.push(ok);
+    const prev = i > 0 ? source[i - 1]! : NaN;
+    if (!Number.isNaN(v) && !Number.isNaN(prev)) count = step(v, prev) ? count + 1 : 0;
+    result.push(count >= length);
   }
   return result;
 }
@@ -910,10 +930,11 @@ function monotonic(source: Source, length: simple_int, step: (newer: number, old
  *
  * @remarks
  * PineScript rules:
- * - each of the `length` steps is a rise larger than the 1e-10 tolerance
- * - `na` values are skipped: the steps are between the last `length + 1` non-`na` values up to the current bar
- *   (on an `na` bar, the result of the last non-`na` bar)
- * - false while there are fewer than `length + 1` non-`na` values
+ * - a counter of rises from the previous bar (a rise is larger than the 1e-10 tolerance); a step that is not a rise
+ *   resets it to 0
+ * - a step from or to an `na` bar leaves the counter unchanged (so an `na` bar, and the bar after it, keep the
+ *   result of the bar before the `na`)
+ * - true when the counter is at least `length` (false at the start)
  *
  * @example
  * ```typescript
@@ -934,10 +955,11 @@ export function rising(source: Source, length: simple_int): series_bool {
  *
  * @remarks
  * PineScript rules:
- * - each of the `length` steps is a fall larger than the 1e-10 tolerance
- * - `na` values are skipped: the steps are between the last `length + 1` non-`na` values up to the current bar
- *   (on an `na` bar, the result of the last non-`na` bar)
- * - false while there are fewer than `length + 1` non-`na` values
+ * - a counter of falls from the previous bar (a fall is larger than the 1e-10 tolerance); a step that is not a fall
+ *   resets it to 0
+ * - a step from or to an `na` bar leaves the counter unchanged (so an `na` bar, and the bar after it, keep the
+ *   result of the bar before the `na`)
+ * - true when the counter is at least `length` (false at the start)
  *
  * @example
  * ```typescript
@@ -1037,10 +1059,11 @@ export function mom(source: Source, length: simple_int): series_float {
  *
  * @remarks
  * - Measures average absolute distance from the mean
- * - Formula: `sum(abs(source[i]! - sma)) / length` for i in 0 to length-1
  * - Less sensitive to outliers than standard deviation
- * - `na` values in the source series are ignored
- * - The function calculates on the `length` quantity of non-`na` values
+ * - PineScript rule (bit for bit): `sum(abs(source[i] - mean)) / length` for `i = 0 .. length - 1`, added newest
+ *   first, with `mean = ta.sma(source, length)` (its compensated running sum, so a flat window can give a tiny
+ *   non-zero deviation)
+ * - The loop reads the last `length` bars: an `na` among them gives `na`
  *
  * @example
  * ```typescript
@@ -1049,25 +1072,13 @@ export function mom(source: Source, length: simple_int): series_float {
  * ```
  */
 export function dev(source: Source, length: simple_int): series_float {
-  const result: series_float = [];
-  // PineScript: na when the window of `length` bars holds an na value
-  const meanValues = strictWindowMean(source, length);
-
-  for (let i = 0; i < source.length; i++) {
-    if (i < length - 1 || isNaN(meanValues[i]!)) {
-      result.push(NaN);
-    } else {
-      let sum = 0;
-      for (let j = 0; j < length; j++) {
-        if (!isNaN(source[i - j]!)) {
-          sum += Math.abs(source[i - j]! - meanValues[i]!);
-        }
-      }
-      result.push(sum / length);
-    }
-  }
-
-  return result;
+  const len = Math.floor(length);
+  return sma(source, len).map((mean, i) => {
+    if (i < len - 1 || Number.isNaN(mean)) return NaN;
+    let sum = 0;
+    for (let k = 0; k < len; k++) sum += Math.abs(source[i - k]! - mean);
+    return sum / len;
+  });
 }
 
 /**
@@ -1096,7 +1107,25 @@ export function dev(source: Source, length: simple_int): series_float {
  * const sampleVariance = ta.variance(closePrices, 20, false);
  * ```
  */
-export function variance(source: Source, length: simple_int, biased: simple_bool = true): series_float {
+export function variance(
+  source: Source,
+  length: simple_int | ArrayLike<number>,
+  biased: simple_bool = true
+): series_float {
+  return varianceOf(source, length, biased, 'ta.variance');
+}
+
+/** {@link variance} with a fixed or a series length; `name` is used in the error messages. */
+function varianceOf(
+  source: Source,
+  length: simple_int | ArrayLike<number>,
+  biased: boolean,
+  name: string
+): series_float {
+  if (typeof length !== 'number') {
+    const result = runningVarianceSeries(source, length, biased, name);
+    return biased ? result : result.map((v, i) => (Math.floor(length[i]!) > 1 ? v : NaN));
+  }
   const len = Math.floor(length);
   // PineScript: the last `len` non-na values (also +/-Infinity skipped), as ta.sma
   if ((biased ? len : len - 1) <= 0) return source.map(() => NaN);
@@ -1168,7 +1197,7 @@ export function median(source: Source, length: simple_int): series_float {
  * @remarks
  * - Fixed length of 4 bars
  * - Weights: [1/6, 2/6, 2/6, 1/6] (symmetric)
- * - Formula: `source[3] * 1/6 + source[2] * 2/6 + source[1] * 2/6 + source[0] * 1/6`
+ * - Formula, in this order as in PineScript (bit for bit): `(source + 2 * source[1] + 2 * source[2] + source[3]) / 6`
  * - More weight given to middle values
  * - `na` values in the source series are included in calculations and will produce an `na` result
  * - Returns NaN for the first 3 bars
@@ -1180,27 +1209,9 @@ export function median(source: Source, length: simple_int): series_float {
  * ```
  */
 export function swma(source: Source): series_float {
-  const result: series_float = [];
-
-  for (let i = 0; i < source.length; i++) {
-    if (i < 3) {
-      result.push(NaN);
-    } else {
-      // Check for any NaN values in the window
-      if (isNaN(source[i]!) || isNaN(source[i - 1]!) || isNaN(source[i - 2]!) || isNaN(source[i - 3]!)) {
-        result.push(NaN);
-      } else {
-        const value = 
-          source[i - 3]! * (1 / 6) +
-          source[i - 2]! * (2 / 6) +
-          source[i - 1]! * (2 / 6) +
-          source[i]! * (1 / 6);
-        result.push(value);
-      }
-    }
-  }
-
-  return result;
+  return Array.from({ length: source.length }, (_, i) =>
+    i < 3 ? NaN : (source[i]! + 2 * source[i - 1]! + 2 * source[i - 2]! + source[i - 3]!) / 6
+  );
 }
 
 /**
@@ -1269,6 +1280,9 @@ export function vwma(source: Source, length: simple_int, volume?: Source): serie
  * @remarks
  * - Calculates line of best fit using least squares method
  * - Formula: `linreg = intercept + slope * (length - 1 - offset)`
+ * - As PineScript (bit for bit): x = 1 (oldest) .. length (newest), sums from the oldest value,
+ *   `slope = (length * sumXY - sumX * sumY) / (length * sumX2 - sumX * sumX)`,
+ *   `intercept = sumY / length - slope * sumX / length + slope`
  * - offset=0 gives current fitted value, offset<0 gives future projection
  * - `na` values in the source series are included in calculations and will produce an `na` result
  * - Useful for trend detection and prediction
@@ -1300,27 +1314,23 @@ export function linreg(source: Source, length: simple_int, offset: simple_int =
       if (hasNaN) {
         result.push(NaN);
       } else {
-        // Calculate least squares regression
+        // Least squares as PineScript: x = 1 (oldest) .. len (newest), summed from the oldest value; the intercept
+        // is the fitted value at x = 1
         let sumX = 0;
         let sumY = 0;
         let sumXY = 0;
         let sumX2 = 0;
-
-          for (let j = 0; j < len; j++) {
-          const x = j;
-              const y = source[i - (len - 1 - j)]!;
+        for (let j = 0; j < len; j++) {
+          const x = j + 1;
+          const y = source[i - (len - 1 - j)]!;
           sumX += x;
           sumY += y;
           sumXY += x * y;
           sumX2 += x * x;
         }
-
-          const slope = (len * sumXY - sumX * sumY) / (len * sumX2 - sumX * sumX);
-          const intercept = (sumY - slope * sumX) / len;
-
-        // Calculate linreg value at offset
-          const x = len - 1 - offset;
-        result.push(intercept + slope * x);
+        const slope = (len * sumXY - sumX * sumY) / (len * sumX2 - sumX * sumX);
+        const intercept = sumY / len - (slope * sumX) / len + slope;
+        result.push(intercept + slope * (len - 1 - offset));
       }
     }
   }
@@ -1342,8 +1352,9 @@ export function linreg(source: Source, length: simple_int, offset: simple_int =
  * - -1 = perfect negative correlation
  * - 0 = no correlation
  * - Measures linear relationship between two series
- * - `na` values in the source series are ignored
- * - The function calculates on the `length` quantity of non-`na` values
+ * - As PineScript: `cov = sma(x * y) - sma(x) * sma(y)`, `r = cov / sqrt(variance(x) * variance(y))` with the
+ *   compensated running sums of `ta.sma` / `ta.variance` (each skips its own `na` values); `|cov| <= 1e-10` gives 0, a
+ *   zero variance gives `na`
  *
  * @example
  * ```typescript
@@ -1352,59 +1363,26 @@ export function linreg(source: Source, length: simple_int, offset: simple_int =
  * ```
  */
 export function correlation(source1: Source, source2: Source, length: simple_int): series_float {
-  const result: series_float = [];
-  // the non-NaN pairs of the window, newest first (reused on every bar)
-  const span = length > 0 ? Math.ceil(length) : 0;
-  const a = new Float64Array(span);
-  const b = new Float64Array(span);
-
-  for (let i = 0; i < source1.length; i++) {
-    if (i < length - 1) {
-      result.push(NaN);
-      continue;
-    }
-    let m = 0;
-    for (let j = 0; j < length; j++) {
-      const v1 = source1[i - j]!;
-      const v2 = source2[i - j]!;
-      if (!isNaN(v1) && !isNaN(v2)) {
-        a[m] = v1;
-        b[m] = v2;
-        m++;
-      }
-    }
-    if (m === 0) {
-      result.push(NaN);
-      continue;
-    }
-
-    // Calculate means
-    let sum1 = 0;
-    let sum2 = 0;
-    for (let k = 0; k < m; k++) {
-      sum1 += a[k]!;
-      sum2 += b[k]!;
-    }
-    const mean1 = sum1 / m;
-    const mean2 = sum2 / m;
-
-    // Calculate correlation components
-    let numerator = 0;
-    let sum1Sq = 0;
-    let sum2Sq = 0;
-    for (let k = 0; k < m; k++) {
-      const dev1 = a[k]! - mean1;
-      const dev2 = b[k]! - mean2;
-      numerator += dev1 * dev2;
-      sum1Sq += dev1 * dev1;
-      sum2Sq += dev2 * dev2;
-    }
-
-    const denominator = Math.sqrt(sum1Sq * sum2Sq);
-    result.push(denominator === 0 ? NaN : numerator / denominator);
-  }
-
-  return result;
+  // PineScript: from compensated running sums, cov = sma(x * y) - sma(x) * sma(y), r = cov / sqrt(var(x) * var(y))
+  // (biased variances); each running sum skips its own na values
+  const product = Array.from({ length: source1.length }, (_, i) => {
+    const v1 = source1[i];
+    const v2 = source2[i];
+    return v1 === null || v1 === undefined || v2 === null || v2 === undefined ? NaN : v1 * v2;
+  });
+  const meanXY = sma(product, length);
+  const meanX = sma(source1, length);
+  const meanY = sma(source2, length);
+  const varX = variance(source1, length);
+  const varY = variance(source2, length);
+  return meanXY.map((mxy, i) => {
+    const cov = mxy - meanX[i]! * meanY[i]!;
+    if (Number.isNaN(cov)) return NaN;
+    // a covariance within 1e-10 of 0 gives 0; a zero denominator gives na (a division by zero)
+    if (Math.abs(cov) <= 1e-10) return 0;
+    const denominator = Math.sqrt(varX[i]! * varY[i]!);
+    return denominator === 0 ? NaN : cov / denominator;
+  });
 }
 
 /**
@@ -1466,10 +1444,14 @@ export function percentrank(source: Source, length: simple_int): series_float {
  * - Typical Price = (High + Low + Close) / 3
  * - Mean Deviation = Average of absolute differences from mean
  * - Scaled by 0.015 to provide more readable numbers
- * - As in PineScript: when the mean deviation is 0 (1e-10 tolerance, a flat window), the CCI of the previous bar
  * - Values above +100 indicate overbought conditions
  * - Values below -100 indicate oversold conditions
- * - \`na\` values in the source series are ignored
+ *
+ * PineScript rules (bit for bit):
+ * - `(source - ta.sma(source, length)) / (0.015 * ta.dev(source, length))`
+ * - when the mean deviation is 0 (1e-10 tolerance, a flat window), the last CCI value; 0 when there is none yet
+ *   (a flat first window)
+ * - \`na\` when the mean or the deviation is \`na\` (an \`na\` in the last \`length\` bars)
  *
  * @example
  * \`\`\`typescript
@@ -1479,22 +1461,15 @@ export function percentrank(source: Source, length: simple_int): series_float {
  * \`\`\`
  */
 export function cci(source: Source, length: simple_int): series_float {
-  const result: series_float = [];
   const smaValues = sma(source, length);
   const devValues = dev(source, length);
-
-  for (let i = 0; i < source.length; i++) {
-    if (isNaN(smaValues[i]!) || isNaN(devValues[i]!)) {
-      result.push(NaN);
-    } else if (eq(devValues[i]!, 0)) {
-      result.push(i > 0 ? result[i - 1]! : NaN);
-    } else {
-      const cci = (source[i]! - smaValues[i]!) / (0.015 * devValues[i]!);
-      result.push(cci);
-    }
-  }
-
-  return result;
+  let last = 0;
+  return smaValues.map((mean, i) => {
+    const d = devValues[i]!;
+    if (Number.isNaN(mean) || Number.isNaN(d)) return NaN;
+    if (!eq(d, 0)) last = (source[i]! - mean) / (0.015 * d);
+    return last;
+  });
 }
 
 /**
@@ -1511,8 +1486,8 @@ export function cci(source: Source, length: simple_int): series_float {
  * - Measures where close is relative to the high-low range
  * - Values above 80 typically indicate overbought
  * - Values below 20 typically indicate oversold
- * - Returns NaN when range is zero (high equals low)
- * - \`na\` values in the source series are ignored
+ * - As PineScript: when the source, \`highest(high, length)\` or \`lowest(low, length)\` is \`na\`, or the range is 0, the
+ *   result is the previous result of the call (\`na\` until a first value)
  *
  * @example
  * \`\`\`typescript
@@ -1526,18 +1501,14 @@ export function stoch(source: Source, high: Source, low: Source, length: simple_
   const lowestValues = lowest(low, length);
   const highestValues = highest(high, length);
 
+  // PineScript: an na input or a zero range keeps the previous result
+  let previous = NaN;
   for (let i = 0; i < source.length; i++) {
-    if (isNaN(lowestValues[i]!) || isNaN(highestValues[i]!)) {
-      result.push(NaN);
-    } else {
-      const range = highestValues[i]! - lowestValues[i]!;
-      if (range === 0) {
-        result.push(NaN);
-      } else {
-        const stochValue = 100 * (source[i]! - lowestValues[i]!) / range;
-        result.push(stochValue);
-      }
-    }
+    const value = source[i]!;
+    const lo = lowestValues[i]!;
+    const range = highestValues[i]! - lo;
+    if (!Number.isNaN(value) && !Number.isNaN(range) && range !== 0) previous = (100 * (value - lo)) / range;
+    result.push(previous);
   }
 
   return result;
@@ -1559,7 +1530,13 @@ export function stoch(source: Source, high: Source, low: Source, length: simple_
  * - Formula: 100 - (100 / (1 + Positive Money Flow / Negative Money Flow))
  * - Values above 80 indicate overbought
  * - Values below 20 indicate oversold
- * - `na` values in the source series are ignored
+ *
+ * PineScript rules (bit for bit):
+ * - the two flows are `math.sum` running sums; a sum within 1e-10 of 0 counts as 0 (the residue a running sum
+ *   keeps over a window of zeros)
+ * - 100 when the negative flow is 0; `na` when `1 + positive / negative` is 0 (division by zero)
+ * - a bar with an `na` source adds nothing to the sums and gives the previous result; the bar after it (an `na`
+ *   change) adds its money flow to both sums
  *
  * @example
  * ```typescript
@@ -1596,11 +1573,16 @@ export function mfi(source: Source, length: simple_int, volume?: Source): series
   const upper = runningSum(upperFlow, length);
   const lower = runningSum(lowerFlow, length);
 
-  return upper.map((u, i) => {
-    const l = lower[i]!;
+  // A sum within 1e-10 of 0 (the residue of a running sum over a window of zeros) is 0
+  const zero = (x: number) => (Math.abs(x) <= 1e-10 ? 0 : x);
+  return upper.map((sumUp, i) => {
+    const u = zero(sumUp);
+    const l = zero(lower[i]!);
     if (Number.isNaN(u) || Number.isNaN(l)) return NaN;
     if (l === 0) return 100;
-    return 100 - 100 / (1 + u / l);
+    const ratio = 1 + u / l;
+    // x / 0 is na in PineScript
+    return ratio === 0 ? NaN : 100 - 100 / ratio;
   });
 }
 
@@ -2012,10 +1994,12 @@ export function dmi(
  * @param source - Series of values to process
  * @param shortLength - Short smoothing length
  * @param longLength - Long smoothing length
- * @returns TSI series
+ * @returns TSI series, a value in [-1, 1]
  *
  * @remarks
- * - TSI oscillates between +100 and -100
+ * - As PineScript: `ta.ema(ta.ema(m, longLength), shortLength) / ta.ema(ta.ema(math.abs(m), longLength), shortLength)`
+ *   with `m = source - source[1]` (not scaled by 100)
+ * - na when the denominator is 0 (a constant source), as a PineScript division by zero
  * - Positive values indicate bullish momentum
  * - Negative values indicate bearish momentum
  * - Crossovers of zero line can signal trend changes
@@ -2047,17 +2031,11 @@ export function tsi(source: Source, shortLength: simple_int, longLength: simple_
   const absMomentum = momentum.map(Math.abs);
   const smoothedAbsMomentum = ema(ema(absMomentum, longLength), shortLength);
 
-  // Calculate TSI
-  const result: series_float = [];
-  for (let i = 0; i < source.length; i++) {
-    if (smoothedAbsMomentum[i]! === 0) {
-      result.push(0);
-    } else {
-      result.push((smoothedMomentum[i]! / smoothedAbsMomentum[i]!) * 100);
-    }
-  }
-
-  return result;
+  // PineScript: a value in [-1, 1]; a division by zero is na
+  return smoothedMomentum.map((m, i) => {
+    const d = smoothedAbsMomentum[i]!;
+    return d === 0 ? NaN : m / d;
+  });
 }
 
 /**
@@ -2223,6 +2201,10 @@ export function bbw(source: Source, length: simple_int, mult: simple_float): ser
  * @param length - Lookback period (default: 14)
  * @returns Williams %R series
  *
+ * @remarks
+ * PineScript rule (bit for bit): `100 * (close - max) / (max - min)` with `max = ta.highest(high, length)` and
+ * `min = ta.lowest(low, length)` (their `na` rules); `na` when the range is 0.
+ *
  * @example
  * ```typescript
  * const wpr = ta.wpr(high, low, close, 14);
@@ -2231,34 +2213,14 @@ export function bbw(source: Source, length: simple_int, mult: simple_float): ser
  * ```
  */
 export function wpr(high: Source, low: Source, close: Source, length: simple_int = 14): series_float {
-  const result: series_float = [];
-
-  for (let i = 0; i < close.length; i++) {
-    if (i < length - 1) {
-      result.push(NaN);
-      continue;
-    }
-
-    // Find highest high and lowest low in the period
-    let highestHigh = high[i - length + 1]!;
-    let lowestLow = low[i - length + 1]!;
-
-    for (let j = i - length + 2; j <= i; j++) {
-      if (high[j]! > highestHigh) highestHigh = high[j]!;
-      if (low[j]! < lowestLow) lowestLow = low[j]!;
-    }
-
-    const range = highestHigh - lowestLow;
-    if (range === 0) {
-      result.push(NaN);
-    } else {
-      // Formula: (Highest High - Close) / (Highest High - Lowest Low) * -100
-      const wprValue = ((highestHigh! - close[i]!) / range) * -100;
-      result.push(wprValue);
-    }
-  }
-
-  return result;
+  const highs = highest(high, length);
+  const lows = lowest(low, length);
+  return Array.from({ length: close.length }, (_, i) => {
+    const hmax = highs[i]!;
+    const range = hmax - lows[i]!;
+    // PineScript, in this order (bit for bit): 100 * (close - max) / (max - min); x / 0 is na
+    return range === 0 ? NaN : (100 * (close[i]! - hmax)) / range;
+  });
 }
 
 /**
@@ -2274,6 +2236,9 @@ export function wpr(high: Source, low: Source, close: Source, length: simple_int
  * @remarks
  * As in PineScript: the sums restart on anchor bars; the standard deviation is
  * `sqrt(Σ(volume × source²) / Σvolume − vwap²)`.
+ * - With an anchor series: `na` before the first anchor bar
+ * - A bar with an `na` source (or volume) makes the sums `na` until the next anchor bar (`na` values are not
+ *   skipped)
  */
 export function vwap(source: Source, volume: Source, anchor?: ArrayLike<boolean | number>): series_float;
 export function vwap(
@@ -2294,18 +2259,19 @@ export function vwap(
   const mid: series_float = [];
   const upper: series_float = [];
   const lower: series_float = [];
-  let sumPV = 0;
-  let sumV = 0;
-  let sumPPV = 0;
+  // na until the first anchor (without an anchor series, bar 0 starts the sums)
+  let sumPV = NaN;
+  let sumV = NaN;
+  let sumPPV = NaN;
   for (let i = 0; i < source.length; i++) {
-    if (anchor && anchor[i]) {
-      sumPV = 0;
-      sumV = 0;
-      sumPPV = 0;
-    }
     const s = source[i]!;
     const v = volume[i]!;
-    if (!Number.isNaN(s) && !Number.isNaN(v)) {
+    if (anchor ? anchor[i] : i === 0) {
+      sumPV = s * v;
+      sumV = v;
+      sumPPV = s * s * v;
+    } else {
+      // An na source or volume makes the sums na until the next anchor
       sumPV += s * v;
       sumV += v;
       sumPPV += s * s * v;
@@ -2387,7 +2353,8 @@ export function alma(
 /**
  * Keltner Channels Width (KCW)
  *
- * Measures the width of Keltner Channels as a percentage of the middle line.
+ * Measures the width of Keltner Channels relative to the middle line: `(upper - lower) / middle`, a ratio as in
+ * PineScript (0.05 is a width of 5% of the middle line; not multiplied by 100).
  * Similar to BBW but uses ATR instead of standard deviation.
  *
  * Low KCW suggests consolidation/low volatility.
@@ -2425,8 +2392,8 @@ export function kcw(
     if (isNaN(basis[i]!) || basis[i]! === 0) {
       result.push(NaN);
     } else {
-      const width = ((upper[i]! - lower[i]!) / basis[i]!) * 100;
-      result.push(width);
+      // PineScript: (upper - lower) / basis, a ratio (not a percentage)
+      result.push((upper[i]! - lower[i]!) / basis[i]!);
     }
   }
 
@@ -2508,50 +2475,30 @@ export function min(source: Source): series_float {
  * The Center of Gravity indicator is an oscillator developed by John Ehlers.
  * It identifies turning points with minimal lag and provides clear signals.
  *
- * The COG calculates a weighted average where more recent prices have higher weights,
- * similar to a moving average but with a focus on momentum shifts.
- *
  * @param source - Source series (typically close)
  * @param length - Lookback period (default: 10)
  * @returns COG series
  *
+ * @remarks
+ * PineScript rule (bit for bit): `-num / math.sum(source, length)`, with `num` the sum of `source[i] * (i + 1)`
+ * for `i = 0 .. length - 1`, added newest first.
+ * - The denominator is the compensated running sum of `math.sum` (the last `length` non-`na` values)
+ * - The numerator reads the last `length` bars, so an `na` among them gives `na`
+ * - A zero denominator gives `na` (PineScript division by zero)
+ *
  * @example
  * ```typescript
  * const cogValue = ta.cog(close, 10);
- * // Use COG crossovers as signals:
- * // - COG crossing above 0: potential buy signal
- * // - COG crossing below 0: potential sell signal
  * ```
  */
 export function cog(source: Source, length: simple_int = 10): series_float {
-  const result: series_float = [];
-
-  for (let i = 0; i < source.length; i++) {
-    if (i < length - 1) {
-      result.push(NaN);
-      continue;
-    }
-
-    let numerator = 0;
-    let denominator = 0;
-
-    for (let j = 0; j < length; j++) {
-      const weight = j + 1;
-      const price = source[i - length + 1 + j]!;
-      numerator += weight * price;
-      denominator += price;
-    }
-
-    if (denominator === 0) {
-      result.push(NaN);
-    } else {
-      // COG formula: -1 * (sum of (weight * price) / sum of prices) + (length + 1) / 2
-      const cog = -1 * (numerator / denominator) + (length + 1) / 2;
-      result.push(cog);
-    }
-  }
-
-  return result;
+  const len = Math.floor(length);
+  return runningSum(source, len).map((sum, i) => {
+    if (i < len - 1 || Number.isNaN(sum) || sum === 0) return NaN;
+    let num = 0;
+    for (let k = 0; k < len; k++) num += source[i - k]! * (k + 1);
+    return -num / sum;
+  });
 }
 
 /**
@@ -2571,32 +2518,25 @@ export function cog(source: Source, length: simple_int = 10): series_float {
  * ```
  *
  * @remarks
- * - `na` values in the source series are ignored
+ * PineScript rules:
+ * - the window is the last `length` non-`na` values (an `na` bar does not enter it, and gets the mode of the
+ *   window it keeps)
+ * - NaN until `length` non-`na` values exist
  * - If no mode exists, returns the smallest value
- * - Returns NaN for the first (length - 1) values where there's insufficient data
  */
 export function mode(source: Source, length: simple_int): series_float {
   const result: series_float = [];
+  const len = Math.floor(length);
+  const seen: number[] = []; // non-na values so far
 
   for (let i = 0; i < source.length; i++) {
-    if (i < length - 1) {
-      result.push(NaN);
-      continue;
-    }
-
-    // Collect non-NaN values in the window
-    const values: number[] = [];
-    for (let j = 0; j < length; j++) {
-      const value = source[i - j]!;
-      if (!isNaN(value)) {
-        values.push(value);
-      }
-    }
-
-    if (values.length === 0) {
+    const v = source[i]!;
+    if (!Number.isNaN(v)) seen.push(v);
+    if (seen.length < len) {
       result.push(NaN);
       continue;
     }
+    const values = seen.slice(seen.length - len);
 
     // Count frequency of each value
     const frequencyMap = new Map<number, number>();
@@ -2759,95 +2699,73 @@ export function percentile_nearest_rank(
  * - +100 indicates source consistently increased over the period
  * - -100 indicates source consistently decreased over the period
  * - 0 indicates no directional consistency
- * - Returns NaN for the first (length - 1) values where there's insufficient data
+ * - As PineScript (bit for bit): the first value is on bar `length`; values less than 1e-10 above the smallest value
+ *   of a group (ascending sweep) are ties with their average rank; a window where all values are ties gives `na`;
+ *   moment-form variances of the bar positions and the ranks, `(100 * cov) / (sd_x * sd_y)`
+ * - A bar with an `na` source keeps the previous result; the values are kept in a ring of `length + 1` slots by bar
+ *   index (0 at the start, not written on `na` bars), so a later window sees the value of `length + 1` bars earlier
+ *   where the `na` was
  */
 export function rci(source: Source, length: simple_int): series_float {
+  const len = Math.floor(length);
   const result: series_float = [];
-
+  // PineScript keeps the values in a ring of `length + 1` slots indexed by the bar index, filled with 0 at the start
+  // and written only on bars with a value: a bar with an na source keeps the previous result, and later windows see
+  // the value of `length + 1` bars earlier in that slot
+  const ring = new Array<number>(len + 1).fill(0);
   for (let i = 0; i < source.length; i++) {
-    if (i < length - 1) {
-      result.push(NaN);
+    const v = source[i]!;
+    if (Number.isNaN(v)) {
+      result.push(i > 0 ? result[i - 1]! : NaN);
       continue;
     }
-
-    // Collect values in the window
-    const values: number[] = [];
-    for (let j = 0; j < length; j++) {
-      values.push(source[i - length + 1 + j]!);
-    }
-
-    // Check for NaN values
-    if (values.some(v => isNaN(v))) {
+    ring[i % (len + 1)] = v;
+    // the first value is on bar `length` (one bar after the window is full)
+    if (i < len) {
       result.push(NaN);
       continue;
     }
-
-    // Create array of indices with their values for ranking
-    const indexed = values.map((value, index) => ({ value, index }));
-
-    // Sort by value to get ranks
-    const sorted = [...indexed].sort((a, b) => a.value - b.value);
-
-    // Assign ranks (handling ties by averaging ranks)
-    const ranks = new Array(length).fill(0);
-    let currentRank = 1;
-    for (let j = 0; j < sorted.length; j++) {
-      // Count ties
-      let tieCount = 1;
-      while (j + tieCount < sorted.length && sorted[j]!.value === sorted[j + tieCount]!.value) {
-        tieCount++;
-      }
-
-      // Average rank for ties
-      const avgRank = (currentRank + (currentRank + tieCount - 1)) / 2;
-
-      // Assign average rank to all tied values
-      for (let k = 0; k < tieCount; k++) {
-        ranks[sorted[j + k]!.index] = avgRank;
-      }
-
-      j += tieCount - 1;
-      currentRank += tieCount;
-    }
-
-    // Calculate D² = sum of (price_rank - time_rank)²
-    let sumSquaredDiff = 0;
-    for (let j = 0; j < length; j++) {
-      const timeRank = j + 1;
-      const diff = ranks[j] - timeRank;
-      sumSquaredDiff += diff * diff;
-    }
-
-    const n = length;
-    const base = (n * n * n - n) / 12;
-
-    // Compute tie correction for price ranks
-    // Count tied groups from the sorted array
-    let tieCorrection = 0;
-    for (let j = 0; j < sorted.length; ) {
-      let tieCount = 1;
-      while (j + tieCount < sorted.length && sorted[j]!.value === sorted[j + tieCount]!.value) {
-        tieCount++;
-      }
-      if (tieCount > 1) {
-        tieCorrection += (tieCount * tieCount * tieCount - tieCount) / 12;
-      }
-      j += tieCount;
-    }
-
-    const A = base - tieCorrection; // Corrected for tied price ranks
-    const B = base;                 // Time ranks have no ties
-
-    let rho: number;
-    if (A === 0 || B === 0) {
-      rho = 0;
-    } else {
-      rho = (A + B - sumSquaredDiff) / (2 * Math.sqrt(A * B));
+    // window newest first (position 0 = this bar)
+    const values = Array.from({ length: len }, (_, j) => ring[(i - j) % (len + 1)]!);
+    // Ranks: ascending sweep; a group collects the values less than 1e-10 above its smallest value; each group gets
+    // its average 0-based rank counted from the largest value
+    const order = values.map((_, j) => j).sort((a, b) => values[a]! - values[b]!);
+    const ranks = new Array<number>(len);
+    for (let g = 0; g < len; ) {
+      const anchor = values[order[g]!]!;
+      let end = g + 1;
+      while (end < len && values[order[end]!]! - anchor < 1e-10) end++;
+      const avgRank = len - 1 - (g + g + (end - g) - 1) / 2;
+      for (let k = g; k < end; k++) ranks[order[k]!] = avgRank;
+      g = end;
+    }
+    // moment-form variances, covariance from deviation products, (100 * cov) / (sd_x * sd_y): this operation order
+    // gives PineScript's values bit for bit
+    let sumX = 0;
+    let sumY = 0;
+    let sumX2 = 0;
+    let sumY2 = 0;
+    for (let k = 0; k < len; k++) {
+      const y = ranks[k]!;
+      sumX += k;
+      sumY += y;
+      sumX2 += k * k;
+      sumY2 += y * y;
+    }
+    const meanX = sumX / len;
+    const meanY = sumY / len;
+    const varX = sumX2 / len - meanX * meanX;
+    const varY = sumY2 / len - meanY * meanY;
+    // a window where all values are ties has no correlation
+    if (!(varX > 0) || !(varY > 0)) {
+      result.push(NaN);
+      continue;
     }
-
-    result.push(rho * 100);
+    let cov = 0;
+    for (let k = 0; k < len; k++) cov += (k - meanX) * (ranks[k]! - meanY);
+    cov /= len;
+    result.push((100 * cov) / (Math.sqrt(varX) * Math.sqrt(varY)));
   }
-
   return result;
 }
 
@@ -3468,16 +3386,18 @@ export function pvt(close: Source, volume: Source): series_float {
 
 /**
  * Accumulation/Distribution index: the running sum of
- * `(2 * close - low - high) / (high - low) * volume`, with 0 on bars where `high == low`.
+ * `((close - low) - (high - close)) / (high - low) * volume`, in this order as in PineScript (bit for bit).
+ * A bar where this is `na` (`high == low`, an `na` volume) adds nothing and keeps the previous value.
  */
 export function accdist(high: Source, low: Source, close: Source, volume: Source): series_float {
-  return cum(
-    close.map((c, i) => {
-      const h = high[i]!;
-      const l = low[i]!;
-      return h === l ? 0 : ((2 * c - l - h) / (h - l)) * volume[i]!;
-    })
-  );
+  let ad = 0;
+  return close.map((c, i) => {
+    const h = high[i]!;
+    const l = low[i]!;
+    const mfv = (((c - l) - (h - c)) / (h - l)) * volume[i]!;
+    if (Number.isFinite(mfv)) ad += mfv;
+    return ad;
+  });
 }
 
 /**