@trebco/treb 23.6.2 → 25.0.0-rc1

package/treb-calculator/src/functions/sparkline.ts

@@ -0,0 +1,335 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the 
+ * terms of the GNU General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your option) any 
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY 
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along 
+ * with TREB. If not, see <https://www.gnu.org/licenses/>. 
+ *
+ * Copyright 2022-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+/**
+ * moved from sparkline module -- not sure why this needed a separate
+ * module. although on reflection it might be better placed in the charts
+ * module? (...) 
+ * 
+ * perhaps not because we use that module elsewhere and this one is only
+ * ever used in spreadsheets.
+ * 
+ */
+
+
+import type { Cell, Style } from 'treb-base-types';
+
+export interface SparklineRenderOptions {
+  context: CanvasRenderingContext2D;
+  width: number;
+  height: number;
+  cell: Cell;
+}
+
+enum LineOperation {
+  move,
+  line,
+}
+
+export class Sparkline {
+
+  // public static SingleColor = ['#333'];
+  // public static TwoColors = ['green', 'red'];
+
+  public static readonly default_color = '#888'; // should never be used, but jic
+
+  /**
+   * three possible cases: 
+   * 
+   * (1) array of numbers, possibly including missing values
+   * (2) typed array
+   * (3) nested array, so we need to recurse and concatenate 
+   *
+   * there's actually one more case, where data comes in from serialized
+   * representation (loading file); in that case it's an object with numeric
+   * indexes (sadly)
+   */
+  protected static UnpackValues(underlying: any): number[] {
+
+    if (Array.isArray(underlying)) {
+      const test = underlying[0];
+      if (Array.isArray(test) || test instanceof Float64Array || test instanceof Float32Array) {
+        return underlying.reduce((a, subset) => a.concat(this.UnpackValues(subset)), []);
+      }
+      else {
+        return underlying.map(test => isNaN(test) ? undefined : test);
+      }
+    }
+    else if (underlying instanceof Float32Array || underlying instanceof Float64Array) {
+      return Array.prototype.slice.call(underlying);
+    }
+    else if (underlying && typeof underlying === 'object') {
+
+      const keys = Object.keys(underlying);
+      const len = keys.length;
+      
+      // this is maybe overdoing it? (...) there's probably a smarter test
+      // if (keys.every(key => !isNaN(Number(key)))) {
+
+      // check first, last
+      if (typeof underlying['0'] !== 'undefined' && typeof underlying[(len - 1).toString()] !== 'undefined') {
+        const data: number[] = [];
+
+        // we probably don't have to explicitly use strings -- although it's not
+        // clear that it would be any faster because someone still has to do the
+        // conversion
+
+        for (let i = 0; i < len; i++) {
+          data[i] = underlying[i.toString()];
+        }
+        return data;
+      }
+
+    }
+
+    return [];
+
+  }
+
+  protected static SparklineCommon(cell: Cell, style: Style.Properties): {
+      values: Array<number|undefined>,
+      colors: string[],
+    } {
+
+    // the cell function echoes back arguments. the first argument
+    // should be an array, but it will be 2D...
+
+    let values: Array<number|undefined> = [];
+
+    // use text color, or default. because this is called from renderer,
+    // theme default _should_ always be passed in, so we should (theoretically)
+    // never need our default.
+   
+    const text_color = style.text?.text || this.default_color;
+    const colors: string[] = [ text_color, text_color ];
+
+    if (Array.isArray(cell.calculated)) {
+      values = this.UnpackValues(cell.calculated[0]);
+      if (typeof cell.calculated[1] === 'string') {
+        colors[0] = cell.calculated[1];
+      }
+      if (typeof cell.calculated[2] === 'string') {
+        colors[1] = cell.calculated[2];
+      }
+    }
+
+    return { values, colors };
+
+  }
+
+  public static RenderLine(
+      width: number,
+      height: number,
+      context: CanvasRenderingContext2D,
+      cell: Cell,
+      style: Style.Properties,
+    ): void {
+
+    const {values, colors} = this.SparklineCommon(cell, style);
+
+    const x_margin = 0.05; // FIXME: parameterize? (...)
+    const y_margin = 0.10;
+
+    let line_width = 1;
+    if (Array.isArray(cell.calculated) && typeof cell.calculated[2] === 'number') {
+      line_width = cell.calculated[2];
+    }
+
+    let min = 0;
+    let max = 0;
+    let first_index = -1;
+
+    for (let i = 0; i < values.length; i++) {
+      const value = values[i];
+      if (typeof value === 'number') {
+        if (first_index >= 0) {
+          min = Math.min(min, value);
+          max = Math.max(max, value);
+        }
+        else {
+          first_index = i;
+          min = max = value;
+        }
+      }
+    }
+
+    if (min !== max) {
+
+      const step = (width * (1 - 2 * x_margin)) / (values.length - 1);
+      const range = max - min;
+      const pixel_range = height * (1 - 2 * y_margin); // ?
+      const base = height * y_margin;
+
+      context.strokeStyle = colors[0];
+      context.lineWidth = line_width;
+      context.lineCap = 'round';
+      context.lineJoin = 'round';
+
+      // let x = width * x_margin + step * first_index;
+      // let y = height - ((values[first_index] as number) - min) * pixel_range / range - base;
+
+      context.beginPath();
+
+      let op = LineOperation.move;
+
+      for (let i = first_index; i < values.length; i++) {
+        const value = values[i];
+        if (typeof value === 'number') {
+          const x = width * x_margin + step * i;
+          const y = height - (value - min) * pixel_range / range - base;
+          if (op === LineOperation.move) {
+            context.moveTo(x, y);
+            op = LineOperation.line;
+          }
+          else {
+            context.lineTo(x, y);
+          }
+        }
+        else {
+          op = LineOperation.move;
+        }
+      }
+
+      context.stroke();
+    
+    }
+
+  }
+
+
+  public static RenderColumn(
+      width: number,
+      height: number,
+      context: CanvasRenderingContext2D,
+      cell: Cell,
+      style: Style.Properties,
+    ): void {
+
+    const {values, colors} = this.SparklineCommon(cell, style);
+
+    // const x_margin = 0.05; // FIXME: parameterize? (...)
+    // const y_margin = 0.10;
+    // const y_margin = Math.max(1, Math.min(0.10 * height, 2));
+
+    const x_margin = 3;
+    const y_margin = 2.5;
+
+    let min = 0;
+    let max = 0;
+    let first_value = false;
+
+    for (const value of values) {
+      if (typeof value === 'number') {
+        if (first_value) {
+          min = Math.min(min, value);
+          max = Math.max(max, value);
+        }
+        else {
+          first_value = true;
+          min = max = value;
+        }
+      }
+    }
+
+    if (values.length) {
+
+      // const step = (width - 2 * x_margin - 2) / (values.length-1);
+      const step = (width - 2 * x_margin - 2) / (values.length-0);
+      const pixel_range = (height - 2 * y_margin); // ?
+      const base = y_margin;
+
+      // let x = Math.round(width * x_margin);
+
+      if (min !== max) { 
+
+        if (min < 0 && max > 0) {
+
+          const range = max - min;
+          const zero = base + max / range * pixel_range;
+
+          // use an indexed loop so we can multiply to get x instead of adding
+          for (let i = 0; i < values.length; i++) {
+            const value = values[i];
+            if (typeof value === 'number') {
+              const x = (x_margin + i * step);
+              const bar_height = (Math.abs(value) / range) * pixel_range;
+
+              if (value >= 0) { 
+                context.fillStyle = colors[0];
+                const top = zero - bar_height;
+                context.fillRect(x + 2, top, step - 2, bar_height);
+                }
+              else { 
+                context.fillStyle = colors[1];
+                const top = zero;
+                context.fillRect(x + 2, top, step - 2, bar_height);
+                }
+
+            }
+          }  
+
+        }
+        else if (max > 0) {
+
+          // all positive
+
+          context.fillStyle = colors[0];
+          const range = max - min;
+
+          // use an indexed loop so we can multiply to get x instead of adding
+          for (let i = 0; i < values.length; i++) {
+            const value = values[i];
+            if (typeof value === 'number') {
+              const x = (x_margin + i * step);
+              const bar_height = Math.max(1, ((value - min) / range) * pixel_range);
+              const top = height - base - bar_height;
+              context.fillRect(x + 2, top, step - 2, bar_height);
+            }
+          }  
+
+        }
+        else {
+
+          // all negative
+
+          context.fillStyle = colors[1];
+          const range = max - min;
+
+          // use an indexed loop so we can multiply to get x instead of adding
+          for (let i = 0; i < values.length; i++) {
+            const value = values[i];
+            if (typeof value === 'number') {
+              const x = (x_margin + i * step);
+              const bar_height = Math.max( 1, (Math.abs(max - value) / range) * pixel_range);
+              const top = base;
+              context.fillRect(x + 2, top, step - 2, bar_height);
+            }
+          }  
+
+        }
+
+      }
+
+    }
+
+  }
+
+}

package/treb-calculator/src/functions/statistics-functions.ts

@@ -0,0 +1,350 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the 
+ * terms of the GNU General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your option) any 
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY 
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along 
+ * with TREB. If not, see <https://www.gnu.org/licenses/>. 
+ *
+ * Copyright 2022-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { FunctionMap } from '../descriptors';
+import * as Utils from '../utilities';
+import { ValueError, ArgumentError, NAError } from '../function-error';
+import { Complex, UnionValue, ValueType } from 'treb-base-types';
+import * as ComplexMath from '../complex-math';
+
+export const Variance = (data: number[], sample = false) => {
+
+  const len = data.length;
+  
+  let m = 0;
+  let v = 0;
+  // let k = 0;
+  // let s = 0;
+
+  for (let i = 0; i < len; i++) m += data[i];
+
+  m /= len;
+  // const mean = m;
+
+  for (let i = 0; i < len; i++) {
+    const d = data[i] - m;
+    v += (d * d);
+    // s += (d * d * d);
+    // k += (d * d * d * d);
+  }
+
+  // const N = len;
+  // const variance = v / len;
+  // const stdev = Math.sqrt(v / len);
+  return sample ? (v / (len-1)) : (v/len);
+
+};
+
+export const StatisticsFunctionLibrary: FunctionMap = {
+
+  'StDev.P': {
+    description: 'Returns the standard deviation of a set of values, corresponding to a population',
+    arguments: [{ name: 'data', }],
+    fn: (...args: any[]): UnionValue => {
+      return { type: ValueType.number, value: Math.sqrt(Variance(Utils.FlattenUnboxed(args), false)) };
+    },
+  },
+
+  'StDev.S': {
+    description: 'Returns the standard deviation of a set of values, corresponding to a sample of a population',
+    arguments: [{ name: 'data', }],
+    fn: (...args: any[]): UnionValue => {
+      return { type: ValueType.number, value: Math.sqrt(Variance(Utils.FlattenUnboxed(args), true)) };
+    },
+  },
+
+  'Var.P': {
+    description: 'Returns the variance of a set of values, corresponding to a population',
+    arguments: [{ name: 'data', }],
+    fn: (...args: any[]): UnionValue => {
+      return { type: ValueType.number, value: Variance(Utils.FlattenUnboxed(args), false) };
+    },
+  },
+
+  'Var.S': {
+    description: 'Returns the variance of a set of values, corresponding to a sample of a population',
+    arguments: [{ name: 'data', }],
+    fn: (...args: any[]): UnionValue => {
+      return { type: ValueType.number, value: Variance(Utils.FlattenUnboxed(args), true) };
+    },
+  },
+
+  Covar: {
+    description: 'Returns the covariance between two ranges of values',
+    arguments: [{
+      name: 'A',
+    }, {
+      name: 'B',
+    }],
+    fn: (x: any[], y: any[]): UnionValue => {
+
+      // both must be 2d arrays, we're assuming the same or mostly similar shape
+      if (!Array.isArray(x) || !Array.isArray(y)) { return ValueError(); }
+      if (!Array.isArray(x[0]) || !Array.isArray(y[0])) { return ValueError(); }
+
+      if (x.length !== y.length) {
+        return ArgumentError();
+      }
+
+      let sum = 0;
+      let length = 0;
+
+      const mean = { x: 0, y: 0 };
+      const data: { x: number[], y: number[] } = { x: [], y: [] };
+
+      for (let j = 0; j < x.length; j++) {
+
+        if (!x[j] || !y[j]) { continue; }
+        if (x[j].length !== y[j].length) {
+          return ArgumentError();
+        }
+        
+        const len = x[j].length;
+        length += len;
+
+        for (let i = 0; i < len; i++) {
+          mean.x += (x[j][i] || 0);
+          mean.y += (y[j][i] || 0);
+
+          data.x.push(x[j][i] || 0);
+          data.y.push(y[j][i] || 0);
+        }
+
+      }
+
+      if (length === 0) {
+        return NAError();
+      }
+
+      mean.x /= length;
+      mean.y /= length;
+
+      for (let i = 0; i < length; i++) {
+        sum += (data.x[i] - mean.x) * (data.y[i] - mean.y);
+      }
+
+      return { type: ValueType.number, value: sum / length, };
+
+    },
+  },
+
+  Correl: {
+    description: 'Returns the correlation between two ranges of values',
+    arguments: [{
+      name: 'A',
+    }, {
+      name: 'B',
+    }],
+    fn: (x: any[], y: any[]): UnionValue => {
+
+      // both must be 2d arrays, we're assuming the same or mostly similar shape
+      if (!Array.isArray(x) || !Array.isArray(y)) { return ValueError(); }
+      if (!Array.isArray(x[0]) || !Array.isArray(y[0])) { return ValueError(); }
+      
+      let rslt = 0;
+      let sumProduct = 0;
+      let sumX = 0;
+      let sumY = 0;
+      let sumSquaredX = 0;
+      let sumSquaredY = 0;
+      let count = 0;
+
+      for (let j = 0; j < x.length; j++) {
+        if (!x[j] || !y[j]) { continue; }
+
+        const len = x[j].length;
+        for (let i = 0; i < len; i++) {
+          const a = Number(x[j][i]);
+          const b = Number(y[j][i]);
+
+          if (isNaN(a) || isNaN(b)) { continue; }
+
+          sumProduct += (a * b);
+          sumX += a;
+          sumY += b;
+          sumSquaredX += (a * a);
+          sumSquaredY += (b * b);
+          count++;
+        }
+      }
+  
+      rslt = ((count * sumProduct) - (sumX * sumY));
+      if (rslt) {
+        rslt /= Math.sqrt(((count * sumSquaredX) - (sumX * sumX)) * ((count * sumSquaredY) - (sumY * sumY)));
+      }
+  
+      return { type: ValueType.number, value: rslt };
+
+    },
+  },
+
+  GeoMean: {
+
+    description: 'Returns the geometric mean of all numeric arguments',
+    arguments: [{ boxed: true }],
+
+    fn: (...args: any[]): UnionValue => {
+
+      args = Utils.FlattenBoxed(args); 
+
+      let count = 0;
+      let product: Complex = {real: 1, imaginary: 0};
+      let complex = false;
+      let negative = false;
+
+      for (const arg of args as UnionValue[]) {
+        
+        if (arg.type === ValueType.complex) {
+          complex = true;
+          product = ComplexMath.Multiply(product, arg.value);
+          count++;
+        }
+        else if (arg.type === ValueType.number) {
+          if (arg.value < 0) {
+            negative = true;
+          }
+          count++;
+          // product = ComplexMath.Multiply(product, {real: arg.value, imaginary: 0});
+          product.real *= arg.value;
+          product.imaginary *= arg.value;
+
+        }
+
+      }
+
+      if (complex) {
+        const value = ComplexMath.Power(product, {real: 1/count, imaginary: 0});
+        if (value.imaginary) {
+          return { type: ValueType.complex, value };
+        }
+        return { type: ValueType.number, value: value.real };
+      }
+      else {
+        if (negative) {
+          return ValueError();
+        }
+        return { type: ValueType.number, value: Math.pow(product.real, 1 / count) };
+      }
+
+      /*
+      for (const arg of args) {
+        if (typeof arg === 'undefined') { continue; }
+        const value = Number(arg);
+        if (value < 0) { return ValueError(); }
+        count++;
+        product *= value;
+      }
+      return { type: ValueType.number, value: Math.pow(product, 1 / count) };
+      */
+
+
+
+    },
+  },
+
+  Average: {
+
+    description: 'Returns the arithmetic mean of all numeric arguments',
+    arguments: [{ boxed: true }],
+
+    fn: (...args: any[]): UnionValue => {
+      args = Utils.FlattenBoxed(args);
+
+      const result = { real: 0, imaginary: 0 };
+      let count = 0;
+
+      for (const ref of args as UnionValue[]) {
+        if (ref.type === ValueType.error) {
+          return ref;
+        }
+        if (ref.type === ValueType.number) {
+          result.real += ref.value;
+          count++;
+        }
+        if (ref.type === ValueType.complex) {
+          result.real += ref.value.real;
+          result.imaginary += ref.value.imaginary;
+          count++;
+        }
+      }
+
+      result.real /= count;
+      result.imaginary /= count;
+      
+      if (result.imaginary) {
+        return { type: ValueType.complex, value: result, };
+      }
+      return { type: ValueType.number, value: result.real };
+
+    },
+  },
+
+  Percentile: {
+    description: 'Returns the kth percentile value from the range of data',
+    arguments: [
+      { name: 'range' },
+      { name: 'percentile' },
+    ],
+    fn: (range: number[][], percentile: number): UnionValue => {
+
+      const flat = Utils.FlattenUnboxed(range).filter((test) => typeof test === 'number');
+      flat.sort((a, b) => a - b);
+      const n = flat.length;
+
+      // try to stabilize this number
+      const factor = Math.pow(10,8);
+      const x = Math.round((1 + (n-1) * percentile) * factor)/factor;
+
+      const lo = Math.floor(x);
+      const hi = Math.ceil(x);
+
+      return { type: ValueType.number, value: (flat[lo-1] + flat[hi-1]) / 2 };
+
+    },
+  },
+
+  Median: {
+    description: 'Returns the median value of the range of data',
+    arguments: [
+      { name: 'range' },
+    ],
+    fn: (...args: any[]): UnionValue => {
+
+      const flat = Utils.FlattenUnboxed(args).filter((test) => typeof test === 'number');
+      flat.sort((a, b) => a - b);
+      const n = flat.length;
+
+      const x = 1 + (n-1) * .5;
+      const lo = Math.floor(x);
+      const hi = Math.ceil(x);
+
+      return { type: ValueType.number, value: (flat[lo-1] + flat[hi-1]) / 2 };
+
+    },
+  }
+
+};
+
+export const StatisticsFunctionAliases: {[index: string]: string} = {
+  Mean: 'Average',
+  'StDev': 'StDev.S',
+  'Var': 'Var.S',
+};