@trebco/treb 32.8.1 → 32.9.3

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v32.8. Copyright 2018-2025 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v32.9. Copyright 2018-2025 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 /*
  * This file is part of TREB.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trebco/treb",
-  "version": "32.8.1",
+  "version": "32.9.3",
   "license": "LGPL-3.0-or-later",
   "homepage": "https://treb.app",
   "repository": {

package/treb-calculator/src/calculator.ts

@@ -1014,65 +1014,141 @@ export class Calculator extends Graph {
 
       /**
        * FIXME: there are cases we are not handling
+       * 
+       * update to return a reference so you can use it as part of a 
+       * range. we're not handling literal arrays atm.
        */
       Index: {
+        return_type: 'reference',
         arguments: [
-          { name: 'range', boxed: true }, 
+          { name: 'range', metadata: true, }, 
           { name: 'row', }, 
           { name: 'column', }
         ],
+
+        // volatile: true, // not sure this is necessary bc input is the range
         volatile: false,
 
         // FIXME: handle full row, full column calls
-        fn: (data: UnionValue, row?: number, column?: number) => {
+        fn: (range: UnionValue, row: number|undefined, column: number|undefined) => {
 
-          // ensure array
-          if (data && data.type !== ValueType.array) {
-            data = {
-              type: ValueType.array,
-              value: [[data]],
-            };
+          if (!range) {
+            return ArgumentError();
+          }
+
+          // this is illegal, although we could just default to zeros
+
+          if (row === undefined && column === undefined) {
+            return ArgumentError();
           }
 
-          if (row && column) {
+          row = row || 0;
+          column = column || 0;
 
-            // simple case: 2 indexes
+          let arr: { value: {address: UnitAddress }}[][] = [];
+
+          // NOTE: could be a single cell. in that case it won't be passed
+          // as an array so we'll need a second branch (or convert it)
+
+          if (range.type === ValueType.array) {
+
+            // FIXME: validate these are addresses (shouldn't be necessary
+            // if we're marking the argument as metadata? what about literals?)
+
+            // check rows and columns. we might need to return an array.
+
+            arr = range.value as unknown as { value: {address: UnitAddress }}[][];
 
-            const c = data.value[column - 1];
-            if (c) {
-              const cell = c[row - 1];
-              if (cell) {
-                return cell;
-              }
-            }
           }
-          else if (row) {
+          else if (range.type === ValueType.object) {
 
-            // return an array
+            const metadata = range.value as { type: string, address?: UnitAddress };
 
-            const value: UnionValue[][] = [];
-            for (const c of data.value) {
-              if (!c[row - 1]) {
-                return ArgumentError();
-              }
-              value.push([c[row-1]]);
+            if (metadata.type === 'metadata' && metadata.address) {
+              arr.push([range as { value: { address: UnitAddress }}]);
             }
+
+          }
+
+          const columns = arr.length;
+          const rows = arr[0]?.length || 0;
+
+          if (rows <= 0 || columns <= 0 || row > rows || column > columns || row < 0 || column < 0) {
+            return ArgumentError();
+          }
+
+
+          // return everything if arguments are (0, 0)
+
+          if (column === 0 && row === 0) {
+
+            // because of the way we're structured this we might be 
+            // returning a range of length 1; in that case we want 
+            // to return it as an address
+
+            const expression: ExpressionUnit = (columns === 1 && rows === 1) ? {
+              ...arr[0][0].value.address,
+            } : {
+              type: 'range', 
+              start: arr[0][0].value.address, 
+              end: arr[columns-1][rows-1].value.address,
+              label: '', position: 0,
+              id: 0,
+            };
+
             return {
-              type: ValueType.array,
-              value,
+              type: ValueType.object,
+              value: expression,  
+            };
+
+          }
+
+          // single cell
+
+          if ((row || rows === 1) && (column || columns === 1)) {
+            return {
+              type: ValueType.object,
+              value: arr[column ? column - 1 : 0][row ? row - 1 : 0].value.address,  
             };
           }
+
+          // sub array
+
+          if (row) {
+
+            // return column
+
+            const expression: ExpressionUnit = {
+              type: 'range', 
+              start: arr[0][row - 1].value.address, 
+              end: arr[columns-1][row-1].value.address,
+              label: '', position: 0,
+              id: 0,
+            };
+
+            return {
+              type: ValueType.object,
+              value: expression,  
+            };
+
+          }
           else if (column) {
 
-            // return an array
+            // return row
+            
+            const expression: ExpressionUnit = {
+              type: 'range', 
+              start: arr[column - 1][0].value.address, 
+              end: arr[column-1][rows-1].value.address,
+              label: '', position: 0,
+              id: 0,
+            };
+
+            return {
+              type: ValueType.object,
+              value: expression,  
+            };
 
-            const c = data.value[column - 1];
-            if (c) {
-              return {
-                type: ValueType.array,
-                value: [c],
-              };
-            }
           }
 
           return ArgumentError();

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

@@ -32,7 +32,7 @@ const Log1p = (x: number) => {
 /** 
  * continued fraction expansion 
  */
-const BetaContFrac = (a: number, b: number, x: number, epsabs: number) => {
+export const BetaContFrac = (a: number, b: number, x: number, epsabs: number) => {
 
   const cutoff = 2.0 * Number.MIN_VALUE;
 
@@ -242,3 +242,17 @@ export const BetaCDF = (x: number, a: number, b: number) => {
 
 };
 
+export const BetaInc = (x: number, a: number, b: number): number => {
+  if (x < 0 || x > 1) return 0; // throw new Error("Invalid x in betainc");
+  const bt =
+    x === 0 || x === 1
+      ? 0
+      : Math.exp(LnGamma(a + b) - LnGamma(a) - LnGamma(b) + a * Math.log(x) + b * Math.log(1 - x));
+  if (x < (a + 1) / (a + b + 2)) {
+    return bt * BetaContFrac(a, b, x, 0) / a;
+  } else {
+    return 1 - bt * BetaContFrac(b, a, 1 - x, 0) / b;
+  }
+};
+
+

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

@@ -0,0 +1,37 @@
+
+/*
+ * 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-2025 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+/** imprecise but reasonably fast normsinv function */
+export const InverseNormal = (q: number): number => {
+
+  if (q === 0.50) {
+    return 0;
+  }
+  
+  const p = (q < 1.0 && q > 0.5) ? (1 - q) : q;
+  const t = Math.sqrt(Math.log(1.0 / Math.pow(p, 2.0)));
+  const x = t - (2.515517 + 0.802853 * t + 0.010328 * Math.pow(t, 2.0)) /
+    (1.0 + 1.432788 * t + 0.189269 * Math.pow(t, 2.0) + 0.001308 * Math.pow(t, 3.0));
+
+  return (q > 0.5 ? x : -x);
+
+};

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

@@ -27,6 +27,8 @@ import * as ComplexMath from '../complex-math';
 
 import { BetaCDF, BetaPDF, InverseBeta, LnGamma } from './beta';
 import { gamma_p } from './gamma';
+import { InverseNormal } from './normal';
+import { tCDF, tInverse, tPDF } from './students-t';
 
 /** error function (for gaussian distribution) */
 const erf = (x: number): number => {
@@ -62,21 +64,7 @@ const norm_dist = (x: number, mean: number, stdev: number, cumulative: boolean)
 
 }
 
-/** imprecise but reasonably fast normsinv function */
-const inverse_normal = (q: number): number => {
 
-  if (q === 0.50) {
-    return 0;
-  }
-  
-  const p = (q < 1.0 && q > 0.5) ? (1 - q) : q;
-  const t = Math.sqrt(Math.log(1.0 / Math.pow(p, 2.0)));
-  const x = t - (2.515517 + 0.802853 * t + 0.010328 * Math.pow(t, 2.0)) /
-    (1.0 + 1.432788 * t + 0.189269 * Math.pow(t, 2.0) + 0.001308 * Math.pow(t, 3.0));
-
-  return (q > 0.5 ? x : -x);
-
-};
 
 const Median = (data: number[]) => {
   const n = data.length;
@@ -478,7 +466,7 @@ export const StatisticsFunctionLibrary: FunctionMap = {
     fn: (q: number, mean = 0, stdev = 1): UnionValue => {
       return {
         type: ValueType.number,
-        value: inverse_normal(q) * stdev + mean,
+        value: InverseNormal(q) * stdev + mean,
       }
     }
   },
@@ -492,7 +480,7 @@ export const StatisticsFunctionLibrary: FunctionMap = {
     fn: (q: number): UnionValue => {
       return {
         type: ValueType.number,
-        value: inverse_normal(q),
+        value: InverseNormal(q),
       }
     }
   }, 
@@ -831,6 +819,71 @@ export const StatisticsFunctionLibrary: FunctionMap = {
     }    
   },
 
+  'T.DIST': {  
+    description: `Returns the left-tailed Student's t-distribution`,
+    arguments: [
+      { name: 'X', unroll: true, boxed: true, },
+      { name: 'degrees of freedom', unroll: true, boxed: true, },
+      { name: 'cumulative', unroll: true, boxed: true, },
+    ],
+    fn: (x: UnionValue, df: UnionValue, cumulative?: UnionValue) => {
+
+      const cum = cumulative ? !!cumulative.value : false;
+
+      if (df.type !== ValueType.number || x.type !== ValueType.number || df.value < 1) {
+        return ArgumentError();
+      }
+      
+      return {
+        type: ValueType.number,
+        value: cum ? tCDF(x.value, df.value) : tPDF(x.value, df.value),
+      }
+
+    },
+  },
+
+  'T.Inv': {
+    description: `Returns the left-tailed inverse of the Student's t-distribution`,
+    arguments: [
+      { 
+        name: 'Probability', boxed: true, unroll: true,
+      }, 
+      {
+        name: 'Degrees of freedom', boxed: true, unroll: true,
+      },
+    ],
+    fn: (p: UnionValue, df: UnionValue) => {
+      if (df.type !== ValueType.number || df.value < 1 || p.type !== ValueType.number || p.value <= 0 || p.value >= 1) {
+        return ArgumentError();
+      }
+      return {
+        type: ValueType.number,
+        value: tInverse(p.value, df.value),
+      };
+    },
+  },
+
+  'T.Inv.2T': {
+    description: `Returns the two-tailed inverse of the Student's t-distribution`,
+    arguments: [
+      { 
+        name: 'Probability', boxed: true, unroll: true,
+      }, 
+      {
+        name: 'Degrees of freedom', boxed: true, unroll: true,
+      },
+    ],
+    fn: (p: UnionValue, df: UnionValue) => {
+      if (df.type !== ValueType.number || df.value < 1 ||p.type !== ValueType.number || p.value <= 0 || p.value >= 1) {
+        return ArgumentError();
+      }
+      return {
+        type: ValueType.number,
+        value: Math.abs(tInverse(1 - p.value/2, df.value)),
+      };
+    },
+  },
+
   GammaLn: {
     description: 'Returns the natural log of the gamma function',
     arguments: [{ name: 'value', boxed: true, unroll: true }],

package/treb-calculator/src/functions/students-t.ts

@@ -0,0 +1,85 @@
+/*
+ * 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-2025 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import { BetaInc, LnGamma } from './beta';
+import { InverseNormal } from './normal';
+
+export const tCDF = (t: number, df: number) => {
+  const x = df / (df + t * t);
+  const a = df / 2;
+  const b = 0.5;
+  const ib = BetaInc(x, a, b);
+  return t >= 0 ? 1 - 0.5 * ib : 0.5 * ib;
+};
+
+export const tPDF = (t: number, nu: number): number => {
+
+  const logNumerator = LnGamma((nu + 1) / 2);
+  const logDenominator = LnGamma(nu / 2) + 0.5 * Math.log(nu * Math.PI);
+  const logFactor = -((nu + 1) / 2) * Math.log(1 + (t * t) / nu);
+
+  const logPDF = logNumerator - logDenominator + logFactor;
+
+  return Math.exp(logPDF);
+
+}
+
+export const tInverse = (p: number, df: number) => {
+
+  const EPS = 1e-12;
+
+  let x = 1;
+
+  // Hill's approximation for initial guess
+
+  {
+    const t = InverseNormal(p);
+    const g1 = (Math.pow(t, 3) + t) / 4;
+    const g2 = ((5 * Math.pow(t, 5)) + (16 * Math.pow(t, 3)) + (3 * t)) / 96;
+    const g3 = ((3 * Math.pow(t, 7)) + (19 * Math.pow(t, 5)) + (17 * Math.pow(t, 3)) - 15 * t) / 384;
+    const g4 = ((79 * Math.pow(t, 9)) + (776 * Math.pow(t, 7)) + (1482 * Math.pow(t, 5)) - (1920 * Math.pow(t, 3)) - (945 * t)) / 92160;
+
+    x = t + g1 / df + g2 / Math.pow(df, 2) + g3 / Math.pow(df, 3) + g4 / Math.pow(df, 4);
+  }
+
+  for (let i = 0; i < 16; i++) {
+
+    const error = tCDF(x, df) - p;
+    if (Math.abs(error) < EPS) {
+      break;
+    }
+
+    const derivative = tPDF(x, df);
+    if (derivative === 0) {
+      break;
+    }
+
+    const delta = error / derivative;
+    const step = Math.max(-1, Math.min(1, delta));
+
+    x -= step;
+
+  }
+
+  return x;
+
+};
+

package/treb-parser/src/parser.ts

@@ -630,13 +630,23 @@ export class Parser {
           }).join(', ')).join('; ') + '}';
 
       case 'binary':
-        return (
-          this.Render(unit.left, options) +
-          ' ' +
-          unit.operator +
-          ' ' +
-          this.Render(unit.right, options)
-        );
+
+        // in some cases we might see range constructs as binary units
+        // because one side (or maybe both sides) of the range is a 
+        // function. in that case we don't want a space in front of the 
+        // operator.
+
+        {
+          const separator = (unit.operator === ':' ? '': ' ');
+
+          return (
+            this.Render(unit.left, options) +
+            separator +
+            unit.operator +
+            separator +
+            this.Render(unit.right, options)
+          );
+        }
 
       case 'unary':
         return (