feat(HF-221): add LINEST regression function

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 
+- Added `LINEST` for simple and multiple linear regression, with optional intercept and regression statistics. The `stats` argument must be constant because result dimensions are determined before evaluation. [#1769](https://github.com/handsontable/hyperformula/pull/1769)
 - Added support for the new license key format. A proprietary key can now grant a subset of the library: a function your key does not include evaluates to a `#LIC!` error, and the matching parts of the API throw a `LicenseCapabilityMissingError`. `getAvailableFunctions()` and `getFunctionDetails()` describe only the functions your key includes. [#1728](https://github.com/handsontable/hyperformula/pull/1728)
 
 ### Changed

docs/guide/known-limitations.md

@@ -61,6 +61,16 @@ a circular reference.
 
 * Ordering (including mixed types, empty cells, and text collation) follows HyperFormula's own comparison rules, which honor the `caseSensitive` and `accentSensitive` configuration options. Numbers sort before text, and text before logical values.
 
+### LINEST function
+
+* The `stats` argument controls whether the result has one or five rows. It must be omitted or supplied as a constant: `TRUE()`, `FALSE()`, a number, or the text `"TRUE"` or `"FALSE"`. Parentheses and numeric unary signs are supported. Cell references, named expressions, and calculated expressions such as `1=1` return `#VALUE!`, including when `LINEST` is nested inside another function.
+
+* Result width is determined from the predictor dimensions before evaluation. Changes to values within fixed input ranges and to a referenced `const` argument recalculate normally. Changes to dependency values do not resize the result automatically; this is the existing array-sizing limitation.
+
+* If an input expression returns a different predictor count than predicted, `LINEST` returns `#VALUE!`. For example, filtering predictor columns can change the required result width.
+
+* Very large or very small input magnitudes can reduce numerical accuracy. Intermediate calculations, such as residual sums of squares, can still overflow or underflow, producing `#NUM!` or inaccurate statistics. Rescale inputs to more moderate units where possible. See [LINEST numerical differences](list-of-differences.md#linest) for compatibility considerations.
+
 ### OFFSET function
 
 HyperFormula resolves the OFFSET function at parse time rather than during evaluation. The parser inspects the arguments and rewrites the expression into a plain cell reference or range. This keeps the dependency graph accurate but imposes several restrictions.

docs/guide/list-of-differences.md

@@ -34,6 +34,14 @@ See a full list of differences between HyperFormula, Microsoft Excel, and Google
 **Contents:**
 [[toc]]
 
+## LINEST
+
+Unlike Excel, HyperFormula requires a constant `stats` argument because the output dimensions are determined before evaluation. For example, `=LINEST(A1:A10,B1:B10,TRUE(),D1)` returns `#VALUE!`; use `TRUE()` or `FALSE()` directly for `stats`. See [LINEST limitations](known-limitations.md#linest-function) for supported constants and input-sizing requirements.
+
+Numerical results can differ for nearly dependent predictors and nearly perfect fits. Coefficient standard errors are sensitive to conditioning, and the F statistic is sensitive to residuals close to machine precision. For an effectively perfect multiple regression, Excel and HyperFormula can return different large finite F values even when the coefficients agree.
+
+Very large or very small input scales can also cause substantial differences in coefficients and statistics, including for a single predictor with a non-perfect fit. HyperFormula does not reproduce Excel's loss of predictors or zero standard errors observed at extreme scales. Rescaling inputs to more moderate units can reduce numerical errors in both engines.
+
 ## General functionalities
 
 | Functionality                                      | Examples                                                                  | HyperFormula                                                                                                                                                                                                                                                                                                                                                 | Google Sheets                                                                                                                  | Microsoft Excel                                                                                                                |

src/error-message.ts

@@ -7,6 +7,8 @@
  * This is a class for detailed error messages across HyperFormula.
  */
 export class ErrorMessage {
+  public static LinestStaticSize = 'LINEST requires input dimensions that determine a fixed result size.'
+  public static LinestStaticStats = 'LINEST requires a constant stats argument to determine its result size.'
   public static DistinctSigns = 'Distinct signs.'
   public static WrongArgNumber = 'Wrong number of arguments.'
   public static EmptyArg = 'Empty function argument.'

src/i18n/languages/csCZ.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'JE.TEXT',
     LEFT: 'ZLEVA',
     LEN: 'DÉLKA',
+    LINEST: 'LINREGRESE',
     LN: 'LN',
     LOG10: 'LOG',
     LOG: 'LOGZ',

src/i18n/languages/daDK.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ER.TEKST',
     LEFT: 'VENSTRE',
     LEN: 'LÆNGDE',
+    LINEST: 'LINREGR',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/deDE.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ISTTEXT',
     LEFT: 'LINKS',
     LEN: 'LÄNGE',
+    LINEST: 'RGP',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/enGB.ts

@@ -144,6 +144,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ISTEXT',
     LEFT: 'LEFT',
     LEN: 'LEN',
+    LINEST: 'LINEST',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/esES.ts

@@ -143,6 +143,7 @@ export const dictionary: RawTranslationPackage = {
     ISTEXT: 'ESTEXTO',
     LEFT: 'IZQUIERDA',
     LEN: 'LARGO',
+    LINEST: 'ESTIMACION.LINEAL',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/fiFI.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ONTEKSTI',
     LEFT: 'VASEN',
     LEN: 'PITUUS',
+    LINEST: 'LINREGR',
     LN: 'LUONNLOG',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/frFR.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ESTTEXTE',
     LEFT: 'GAUCHE',
     LEN: 'NBCAR',
+    LINEST: 'DROITEREG',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/huHU.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'SZÖVEG.E',
     LEFT: 'BAL',
     LEN: 'HOSSZ',
+    LINEST: 'LIN.ILL',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/idID.ts

@@ -144,6 +144,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ADALAH.TEKS',
     LEFT: 'KIRI',
     LEN: 'PANJANG',
+    LINEST: 'LINEST',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/itIT.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'VAL.TESTO',
     LEFT: 'SINISTRA',
     LEN: 'LUNGHEZZA',
+    LINEST: 'REGR.LIN',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/nbNO.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ERTEKST',
     LEFT: 'VENSTRE',
     LEN: 'LENGDE',
+    LINEST: 'RETTLINJE',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/nlNL.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ISTEKST',
     LEFT: 'LINKS',
     LEN: 'PITUUS',
+    LINEST: 'LIJNSCH',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/plPL.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'CZY.TEKST',
     LEFT: 'LEWY',
     LEN: 'DŁ',
+    LINEST: 'REGLINP',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/ptPT.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ÉTEXTO',
     LEFT: 'ESQUERDA',
     LEN: 'NÚM.CARACT',
+    LINEST: 'PROJ.LIN',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/ruRU.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ЕТЕКСТ',
     LEFT: 'ЛЕВСИМВ',
     LEN: 'ДЛСТР',
+    LINEST: 'ЛИНЕЙН',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/svSE.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ÄRTEXT',
     LEFT: 'VÄNSTER',
     LEN: 'LÄNGD',
+    LINEST: 'REGR',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/i18n/languages/trTR.ts

@@ -143,6 +143,7 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'EMETİNSE',
     LEFT: 'SOL',
     LEN: 'UZUNLUK',
+    LINEST: 'DOT',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',

src/interpreter/functionMetadata/categories/statistical.ts

@@ -304,6 +304,18 @@ export const STATISTICAL_DOCS: Record<string, FunctionDoc> = {
     documentationUrl: 'https://hyperformula.handsontable.com/docs/guide/built-in-functions.html',
     examples: ['=LARGE(A1:A10, 1)', '=LARGE(A1:A10, 3)'],
   },
+  LINEST: {
+    category: 'Statistical',
+    shortDescription: 'Returns linear regression coefficients and optional statistics.',
+    parameters: [
+      {name: 'known_y', description: 'A numeric range of observed dependent values.'},
+      {name: 'known_x', description: 'Optional numeric predictors. If omitted, uses sequential values starting at 1 with the shape of known_y.'},
+      {name: 'const', description: 'Whether to fit an intercept. Defaults to TRUE; FALSE fits through zero.'},
+      {name: 'stats', description: 'Whether to return five rows including regression statistics. Defaults to FALSE. Must be a constant; cell references and computed expressions are unsupported.'},
+    ],
+    documentationUrl: 'https://hyperformula.handsontable.com/docs/guide/built-in-functions.html',
+    examples: ['=LINEST(A1:A10, B1:C10)', '=LINEST(A1:A10, B1:C10, TRUE(), TRUE())'],
+  },
   'LOGNORM.DIST': {
     category: 'Statistical',
     shortDescription: 'Returns density of lognormal distribution.',