Add FORECAST.LINEAR, INTERCEPT, TREND, GROWTH and LOGEST functions

CHANGELOG.md

@@ -9,7 +9,9 @@ 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)
+- Added the regression functions `FORECAST.LINEAR` (also available as `FORECAST`), `INTERCEPT`, `TREND`, `GROWTH`, and `LOGEST`. `LOGEST`, like `LINEST`, requires a constant `stats` argument. [#1802](https://github.com/handsontable/hyperformula/pull/1802)
 
 ### Changed
 

docs/guide/known-limitations.md

@@ -61,6 +61,22 @@ 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.
+
+### TREND, GROWTH and LOGEST functions
+
+* `TREND` and `GROWTH` determine their result size before evaluation: from `new_x`, or from `known_y` when `new_x` is omitted. If an input expression returns a different size at evaluation, they return `#VALUE!`.
+
+* `LOGEST` returns the same layout as `LINEST`, and the `LINEST` limitations above apply to it: `stats` must be a constant, and the result width is determined from the predictor dimensions before evaluation.
+
 ### 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,22 @@ 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.
+
+## TREND, GROWTH and LOGEST
+
+Like `LINEST`, these functions determine their result size before evaluation. `LOGEST` requires a constant `stats` argument, as `LINEST` does: `=LOGEST(A1:A10,B1:B10,TRUE(),D1)` returns `#VALUE!`. The numerical differences described for `LINEST` also apply to the statistics returned by `LOGEST`, which are those of the fit to the natural logarithm of `known_y`.
+
+An array passed as `const` (or as `stats` in `LOGEST`) is not evaluated element by element. Microsoft Excel returns one result for each element, for example for `=TREND(A1:A6,B1:B6,C1:C3,{TRUE(),FALSE()})`; HyperFormula uses the first element as `const`, and returns `#VALUE!` for an array `stats`.
+
+A single cell that holds an error, passed as `known_x` or `new_x`, returns that error before the other arguments are checked. Microsoft Excel returns `#VALUE!`. For example, `=TREND(A1:A6,B1:B6,C1)` where C1 contains `=1/0` returns `#DIV/0!` in HyperFormula. An error inside a range of several cells returns `#VALUE!`, as in Microsoft Excel.
+
 ## General functionalities
 
 | Functionality                                      | Examples                                                                  | HyperFormula                                                                                                                                                                                                                                                                                                                                                 | Google Sheets                                                                                                                  | Microsoft Excel                                                                                                                |

src/error-message.ts

@@ -7,6 +7,10 @@
  * 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 PositiveValues = 'Values need to be positive.'
+  public static ZeroVariance = 'Values cannot all be equal.'
   public static DistinctSigns = 'Distinct signs.'
   public static WrongArgNumber = 'Wrong number of arguments.'
   public static EmptyArg = 'Empty function argument.'
@@ -80,4 +84,6 @@ export class ErrorMessage {
   public static NamedExpressionName = (arg: string) => `Named expression ${arg} not recognized.`
   public static LicenseKey = (arg: string) => `License key is ${arg}.`
   public static LicenseCapability = (functionName: string) => `Function ${functionName} is not included in your license.`
+  public static StaticResultSize = (functionName: string) => `${functionName} requires input dimensions that determine a fixed result size.`
+  public static StaticStats = (functionName: string) => `${functionName} requires a constant stats argument to determine its result size.`
 }

src/i18n/languages/csCZ.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'JE.TEXT',
     LEFT: 'ZLEVA',
     LEN: 'DÉLKA',
+    LINEST: 'LINREGRESE',
+    LOGEST: 'LOGLINREGRESE',
+    TREND: 'LINTREND',
+    GROWTH: 'LOGLINTREND',
     LN: 'LN',
     LOG10: 'LOG',
     LOG: 'LOGZ',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FTEST',
     STEYX: 'STEYX',
     SLOPE: 'SLOPE',
+    INTERCEPT: 'INTERCEPT',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'FORECAST',
     COVAR: 'COVAR',
     'COVARIANCE.P': 'COVARIANCE.P',
     'COVARIANCE.S': 'COVARIANCE.S',

src/i18n/languages/daDK.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ER.TEKST',
     LEFT: 'VENSTRE',
     LEN: 'LÆNGDE',
+    LINEST: 'LINREGR',
+    LOGEST: 'LOGREGR',
+    TREND: 'TENDENS',
+    GROWTH: 'FORØGELSE',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FTEST',
     STEYX: 'STFYX',
     SLOPE: 'STIGNING',
+    INTERCEPT: 'SKÆRING',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'PROGNOSE',
     COVAR: 'KOVARIANS',
     'COVARIANCE.P': 'KOVARIANS.P',
     'COVARIANCE.S': 'KOVARIANS.S',

src/i18n/languages/deDE.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ISTTEXT',
     LEFT: 'LINKS',
     LEN: 'LÄNGE',
+    LINEST: 'RGP',
+    LOGEST: 'RKP',
+    TREND: 'TREND',
+    GROWTH: 'VARIATION',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FTEST',
     STEYX: 'STFEHLERYX',
     SLOPE: 'STEIGUNG',
+    INTERCEPT: 'ACHSENABSCHNITT',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'SCHÄTZER',
     COVAR: 'KOVAR',
     'COVARIANCE.P': 'KOVARIANZ.P',
     'COVARIANCE.S': 'KOVARIANZ.S',

src/i18n/languages/enGB.ts

@@ -144,6 +144,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ISTEXT',
     LEFT: 'LEFT',
     LEN: 'LEN',
+    LINEST: 'LINEST',
+    LOGEST: 'LOGEST',
+    TREND: 'TREND',
+    GROWTH: 'GROWTH',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -413,6 +417,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FTEST',
     STEYX: 'STEYX',
     SLOPE: 'SLOPE',
+    INTERCEPT: 'INTERCEPT',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'FORECAST',
     'CHISQ.TEST': 'CHISQ.TEST',
     CHITEST: 'CHITEST',
     'T.TEST': 'T.TEST',

src/i18n/languages/esES.ts

@@ -143,6 +143,10 @@ export const dictionary: RawTranslationPackage = {
     ISTEXT: 'ESTEXTO',
     LEFT: 'IZQUIERDA',
     LEN: 'LARGO',
+    LINEST: 'ESTIMACION.LINEAL',
+    LOGEST: 'ESTIMACION.LOGARITMICA',
+    TREND: 'TENDENCIA',
+    GROWTH: 'CRECIMIENTO',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ export const dictionary: RawTranslationPackage = {
     FTEST: 'PRUEBA.F',
     STEYX: 'ERROR.TIPICO.XY',
     SLOPE: 'PENDIENTE',
+    INTERCEPT: 'INTERSECCION.EJE',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'PRONOSTICO',
     COVAR: 'COVAR',
     'COVARIANCE.P': 'COVARIANCE.P',
     'COVARIANCE.S': 'COVARIANZA.M',

src/i18n/languages/fiFI.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ONTEKSTI',
     LEFT: 'VASEN',
     LEN: 'PITUUS',
+    LINEST: 'LINREGR',
+    LOGEST: 'LOGREGR',
+    TREND: 'SUUNTAUS',
+    GROWTH: 'KASVU',
     LN: 'LUONNLOG',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FTESTI',
     STEYX: 'KESKIVIRHE',
     SLOPE: 'KULMAKERROIN',
+    INTERCEPT: 'LEIKKAUSPISTE',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'ENNUSTE',
     COVAR: 'KOVARIANSSI',
     'COVARIANCE.P': 'KOVARIANSSI.P',
     'COVARIANCE.S': 'KOVARIANSSI.S',

src/i18n/languages/frFR.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ESTTEXTE',
     LEFT: 'GAUCHE',
     LEN: 'NBCAR',
+    LINEST: 'DROITEREG',
+    LOGEST: 'LOGREG',
+    TREND: 'TENDANCE',
+    GROWTH: 'CROISSANCE',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'TEST.F',
     STEYX: 'ERREUR.TYPE.XY',
     SLOPE: 'PENTE',
+    INTERCEPT: 'ORDONNEE.ORIGINE',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'PREVISION',
     COVAR: 'COVARIANCE',
     'COVARIANCE.P': 'COVARIANCE.PEARSON',
     'COVARIANCE.S': 'COVARIANCE.STANDARD',

src/i18n/languages/huHU.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'SZÖVEG.E',
     LEFT: 'BAL',
     LEN: 'HOSSZ',
+    LINEST: 'LIN.ILL',
+    LOGEST: 'LOG.ILL',
+    TREND: 'TREND',
+    GROWTH: 'NÖV',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'F.PRÓBA',
     STEYX: 'STHIBAYX',
     SLOPE: 'MEREDEKSÉG',
+    INTERCEPT: 'METSZ',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'ELŐREJELZÉS',
     COVAR: 'KOVAR',
     'COVARIANCE.P': 'KOVARIANCIA.S',
     'COVARIANCE.S': 'KOVARIANCIA.M',

src/i18n/languages/idID.ts

@@ -144,6 +144,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ADALAH.TEKS',
     LEFT: 'KIRI',
     LEN: 'PANJANG',
+    LINEST: 'LINEST',
+    LOGEST: 'LOGEST',
+    TREND: 'TREND',
+    GROWTH: 'GROWTH',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -413,6 +417,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FUJI',
     STEYX: 'STEYX',
     SLOPE: 'KEMIRINGAN',
+    INTERCEPT: 'INTERCEPT',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'FORECAST',
     'CHISQ.TEST': 'CHISQ.UJI',
     CHITEST: 'CHIUJI',
     'T.TEST': 'T.UJI',

src/i18n/languages/itIT.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'VAL.TESTO',
     LEFT: 'SINISTRA',
     LEN: 'LUNGHEZZA',
+    LINEST: 'REGR.LIN',
+    LOGEST: 'REGR.LOG',
+    TREND: 'TENDENZA',
+    GROWTH: 'CRESCITA',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'TEST.F',
     STEYX: 'ERR.STD.YX',
     SLOPE: 'PENDENZA',
+    INTERCEPT: 'INTERCETTA',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'PREVISIONE',
     COVAR: 'COVARIANZA',
     'COVARIANCE.P': 'COVARIANZA.P',
     'COVARIANCE.S': 'COVARIANZA.C',

src/i18n/languages/nbNO.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ERTEKST',
     LEFT: 'VENSTRE',
     LEN: 'LENGDE',
+    LINEST: 'RETTLINJE',
+    LOGEST: 'KURVE',
+    TREND: 'TREND',
+    GROWTH: 'VEKST',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'FTEST',
     STEYX: 'STANDARDFEIL',
     SLOPE: 'STIGNINGSTALL',
+    INTERCEPT: 'SKJÆRINGSPUNKT',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'PROGNOSE',
     COVAR: 'KOVARIANS',
     'COVARIANCE.P': 'KOVARIANS.P',
     'COVARIANCE.S': 'KOVARIANS.S',

src/i18n/languages/nlNL.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ISTEKST',
     LEFT: 'LINKS',
     LEN: 'PITUUS',
+    LINEST: 'LIJNSCH',
+    LOGEST: 'LOGSCH',
+    TREND: 'TREND',
+    GROWTH: 'GROEI',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'F.TOETS',
     STEYX: 'STAND.FOUT.YX',
     SLOPE: 'RICHTING',
+    INTERCEPT: 'SNIJPUNT',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'VOORSPELLEN',
     COVAR: 'COVARIANTIE',
     'COVARIANCE.P': 'COVARIANTIE.P',
     'COVARIANCE.S': 'COVARIANTIE.S',

src/i18n/languages/plPL.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'CZY.TEKST',
     LEFT: 'LEWY',
     LEN: 'DŁ',
+    LINEST: 'REGLINP',
+    LOGEST: 'REGEXPP',
+    TREND: 'REGLINW',
+    GROWTH: 'REGEXPW',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'TEST.F',
     STEYX: 'REGBŁSTD',
     SLOPE: 'NACHYLENIE',
+    INTERCEPT: 'ODCIĘTA',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'REGLINX',
     COVAR: 'KOWARIANCJA',
     'COVARIANCE.P': 'KOWARIANCJA.POPUL',
     'COVARIANCE.S': 'KOWARIANCJA.PRÓBKI',

src/i18n/languages/ptPT.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ÉTEXTO',
     LEFT: 'ESQUERDA',
     LEN: 'NÚM.CARACT',
+    LINEST: 'PROJ.LIN',
+    LOGEST: 'PROJ.LOG',
+    TREND: 'TENDÊNCIA',
+    GROWTH: 'CRESCIMENTO',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'TESTEF',
     STEYX: 'EPADYX',
     SLOPE: 'INCLINAÇÃO',
+    INTERCEPT: 'INTERCETAR',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'PREVISÃO',
     COVAR: 'COVAR',
     'COVARIANCE.P': 'COVARIAÇÃO.P',
     'COVARIANCE.S': 'COVARIAÇÃO.S',

src/i18n/languages/ruRU.ts

@@ -143,6 +143,10 @@ const dictionary: RawTranslationPackage = {
     ISTEXT: 'ЕТЕКСТ',
     LEFT: 'ЛЕВСИМВ',
     LEN: 'ДЛСТР',
+    LINEST: 'ЛИНЕЙН',
+    LOGEST: 'ЛГРФПРИБЛ',
+    TREND: 'ТЕНДЕНЦИЯ',
+    GROWTH: 'РОСТ',
     LN: 'LN',
     LOG10: 'LOG10',
     LOG: 'LOG',
@@ -410,6 +414,9 @@ const dictionary: RawTranslationPackage = {
     FTEST: 'ФТЕСТ',
     STEYX: 'СТОШYX',
     SLOPE: 'НАКЛОН',
+    INTERCEPT: 'ОТРЕЗОК',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR',
+    FORECAST: 'ПРЕДСКАЗ',
     COVAR: 'КОВАР',
     'COVARIANCE.P': 'КОВАРИАЦИЯ.Г',
     'COVARIANCE.S': 'КОВАРИАЦИЯ.В',