{ "category": "Statistical functions", "display_name": "FORECAST.LINEAR", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.FORECAST.LINEAR", "implementation_state": { "answer_bank": null, "detail": "Recorded: 7 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 7 recorded answers", "workbook_corpus": { "cells": 7, "matched": 7 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/statistics.rs#L384-L387" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/statistics::forecast" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/statistics.rs#L384-L387", "state": "matches", "suite": null, "summary": "Matches all 7 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.FORECAST.LINEAR.json", "name": "FORECAST.LINEAR", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **[FORECAST](FUNC.FORECAST.md)** — the legacy spelling, documented as deprecated. The precise\n statement of what is and is not known about the pair is in the section above.\n- **`FORECAST.ETS`, `FORECAST.ETS.CONFINT`, `FORECAST.ETS.SEASONALITY`, `FORECAST.ETS.STAT`** —\n the exponential-smoothing time-series family that shares the `FORECAST.` prefix and shares\n nothing else. The `.LINEAR` suffix exists to keep these apart. A reader who wants seasonality\n handling wants the ETS members; a reader who wants a straight line wants this one.\n- **`TREND`** — the array-valued generalisation to several predictors and several evaluation\n points.\n- **`SLOPE` and `INTERCEPT`** — the same fit exposed as its two coefficients.\n- **`LINEST`** — the full regression report.\n- **`GROWTH`** — the exponential analogue, fitted in log-space.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nThe numerical content of this function is the numerical content of the least-squares slope, and\nit is set out on the [FORECAST page](FUNC.FORECAST.md#numerical-notes): centered accumulation\nversus the raw-sums form, the catastrophic cancellation that the raw form suffers when the xᵢ\nshare a large offset, the conditioning argument from Björck, and the fact that publishing as\na + b·x rather than ȳ + b·(x − x̄) changes the last bits without changing the mathematics.\n\n", "quirks": "\n### The relationship to FORECAST, stated precisely\n\n\nThis is a dotted-name/legacy-name pair, and the Handbook's rule for such pairs applies in full:\n**a shared documentation page and matching wording are not evidence of a shared computation.**\n\nWhat can be said, with its warrant attached:\n\n1. **The documentation describes the same computation.** Both VBA reference pages give the\n equation as a + bx with the same definitions of a and b, and list the same three error\n conditions. That is a documented statement about intent.\n2. **Microsoft marks the legacy method deprecated.** The `Forecast` page carries \"This member\n is deprecated in Office 2016 and later versions\"; the `Forecast_Linear` page carries no such\n note. That is a supersession statement.\n5. **Nothing establishes that Excel does.** No Handbook measurement compares Excel's two\n surfaces against each other. The evidence record attached to this page says explicitly that\n its rows are `FORECAST`'s, that there is no `FORECAST.LINEAR` probe anywhere in the corpus,\n and that inheriting the figure to this surface would be a shared-kernel *inference* rather\n than a measurement.\n\nPoint 5 is the load-bearing one. Anyone migrating formulas from `FORECAST` to\n`FORECAST.LINEAR` on the assumption that results are unchanged in the last bit is making an\nassumption this Handbook cannot support.\n\n\n\n### Result and edge cases\n\n\nReturns `Number` — a scalar, never an array.\n\nThe edge-case inventory is identical in shape to `FORECAST`'s: two points fit exactly; all-x\nidentical is a zero denominator; constant y is a well-posed fit with zero slope; length\nmismatch and empty input are documented as `#N/A`; large common offsets in x are the accuracy\nhazard. See [FORECAST](FUNC.FORECAST.md#result-and-edge-cases). Whether the two surfaces\nactually agree on any of these in Excel is unmeasured, which is precisely why the inventory is\nworth probing on both surfaces rather than on one.\n\n\n\n### Errors\n\n\nAs documented by Microsoft on the VBA reference page for this method:\n\n| Error | Condition |\n|---|---|\n| `#VALUE!` | `x` is nonnumeric |\n| `#N/A` | the `known_y` and `known_x` parameters are empty, or contain a different number of data points |\n| `#DIV/0!` | the variance of the `known_x` parameters equals zero |\n\n", "sources": "- Microsoft Learn, \"WorksheetFunction.Forecast_Linear method (Excel)\" —\n \n (the a + bx equation with the sample means named, and the three documented error conditions).\n- Handbook evidence record `EV-MISC-0007` — including its explicit statement that no\n `FORECAST.LINEAR` probe exists in the corpus. The record's figures render mechanically beside\n this page; the prose deliberately does not restate them.\n- Å. Björck, *Numerical Methods for Least Squares Problems* — the conditioning argument.\n- Handbook, [FORECAST](FUNC.FORECAST.md) — the shared mathematics and numerical treatment.\n- Handbook projections `data/functions/FUNC.FORECAST.LINEAR.json` (arity, category) and\n `data/presence/FUNC.FORECAST.LINEAR.json` (the shared `regression_forecast_family` module).\n\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`FORECAST.LINEAR(x, known_ys, known_xs)` fits a straight line to the paired data by ordinary\nleast squares and evaluates it at `x`. Microsoft's documented equation is **a + bx**, with the\nsample means named as `AVERAGE(all known_x)` and `AVERAGE(all known_y)`.\n\nWith n paired observations (xᵢ, yᵢ) and means x̄, ȳ:\n\n b = Σ (xᵢ − x̄)(yᵢ − ȳ) / Σ (xᵢ − x̄)²\n a = ȳ − b·x̄\n FORECAST.LINEAR(x, …) = a + b·x\n\nThe full mathematical treatment — that this is a fit and not an interpolation, that no\nextrapolation guard exists, that the denominator vanishes exactly when the xᵢ are all equal\nand *not* when the yᵢ are — is set out on the [FORECAST](FUNC.FORECAST.md) page and is not\nrepeated here. The name is the modern one: `LINEAR` distinguishes this member from the\n`FORECAST.ETS` exponential-smoothing family introduced at the same time, which is why the\nrename happened at all.\n\n\n\n### Arguments\n\n| Argument | Meaning |\n|---|---|\n| `x` | The abscissa at which to evaluate the fitted line. |\n| `known_y's` | The dependent array or range. |\n| `known_x's` | The independent array or range. |\n\n`x` is a scalar numeric slot; the two data arguments are consumed by scanning, not by\nelementwise lifting. See [Coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n" }, "signature": { "display": "FORECAST.LINEAR(x, known_ys, known_xs)", "parameters": [ { "description": null, "name": "x", "optional": false, "repeats": false }, { "description": null, "name": "known_ys", "optional": false, "repeats": false }, { "description": null, "name": "known_xs", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 3 }, "category": "Statistical functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "RefOnly", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Value predicted for x on the least-squares line through the known points", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns a value along a linear trend", "microsoft_url": "https://support.microsoft.com/en-us/office/forecast-and-forecast-linear-functions-50ca49c9-7b40-4892-94e4-7ad38bbeda99" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [], "signature": { "display": "FORECAST.LINEAR(x, known_ys, known_xs)", "parameters": [ { "description": null, "name": "x", "optional": false, "repeats": false }, { "description": null, "name": "known_ys", "optional": false, "repeats": false }, { "description": null, "name": "known_xs", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "FORECAST.LINEAR", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/forecast-and-forecast-linear-functions-50ca49c9-7b40-4892-94e4-7ad38bbeda99" }, "try_it": { "formula": "=FORECAST.LINEAR(4,{2;4;6},{1;2;3})" }, "url": "https://handbook.dnacalc.com/functions/FORECAST.LINEAR.html", "variants": [], "versions": [] }