{ "category": "Statistical functions", "display_name": "AVERAGE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.AVERAGE", "implementation_state": { "answer_bank": { "excel_builds": [ "20430", "20527" ], "larger_numeric": 0, "last_bit": 0, "matched": 1222, "other_mismatch": 0, "refused": 0, "rows": 1222, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 1,222 in the answer bank and 66 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 1,288 recorded answers", "workbook_corpus": { "cells": 67, "matched": 66, "pending": 1 } }, "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/aggregate.rs#L111-L111", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/aggregate.rs#L207-L214" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/aggregate::aggregate", "catalogue/aggregate::mean", "catalogue/aggregate::holds_held_arrays", "catalogue/aggregate::read_held_references", "catalogue/aggregate::number_of", "catalogue/aggregate::each_number", "catalogue/aggregate::read_values", "catalogue/aggregate::reader", "catalogue/aggregate::read_reference" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/aggregate.rs#L111-L111", "state": "matches", "suite": null, "summary": "Matches all 1,288 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.AVERAGE.json", "name": "AVERAGE", "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- **`MEDIAN`, `MODE.SNGL`, `TRIMMEAN`, `GEOMEAN`, `HARMEAN`** — the other centres. `TRIMMEAN`\n is the one to reach for when the objection to `AVERAGE` is outliers.\n- **`SUBTOTAL(1, …)` and `AGGREGATE(1, …)`** — `AVERAGE` with hidden-row and error-skipping\n options, and the usual right answer when a filtered table is involved.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nAveraging is the canonical worked example in floating-point error analysis, and it deserves the\ntreatment even though the formula fits on one line.\n\n**Summation error.** For a plain left-to-right accumulation of \\(n\\) doubles, the standard\nbound (Higham, *Accuracy and Stability of Numerical Algorithms*, chapter 4) is\n\n |ŝ − s| ≤ γ_{n−1} · Σ|x_i|, γ_k = k·u / (1 − k·u)\n\nwith \\(u = 2^{-53}\\). The bound is proportional to \\(\\sum |x_i|\\), not to \\(|s|\\), so the\n*relative* error is governed by the condition number \\(\\sum|x_i| / |\\sum x_i|\\). Data of mixed\nsign that nearly cancels — returns around zero, residuals, differences — can lose every\nsignificant digit while the same data with a constant added stays accurate. This is the\nmechanism behind essentially every reported spreadsheet averaging surprise.\n\n**What better implementations do.** Pairwise (cascade) summation replaces \\(n\\) in the bound by\n\\(\\log_2 n\\) at no meaningful cost, which is why it is the default in most numerical libraries.\nCompensated summation — Kahan's algorithm, and Neumaier's variant that also handles the case\nwhere the running sum is smaller than the addend — reduces the bound to roughly \\(2u\\sum|x_i|\\)\nindependent of \\(n\\). Exact-accumulation schemes (Shewchuk's expansions, Ogita–Rump–Oishi\n`Sum2`/`SumK`, or a long accumulator) give a correctly rounded sum. Any of these changes the\nlast bits of the answer, which is precisely why an implementation targeting a *particular*\nengine's output cannot simply adopt the best one.\n\n**The division.** Dividing an accurately summed total by \\(n\\) adds at most one rounding, so\nthe division is never the problem. Running-mean formulations — \\(m_{k} = m_{k-1} + (x_k -\nm_{k-1})/k\\), the Welford update — trade the overflow hazard for \\(n\\) divisions and a\ndifferent error profile; they are the right choice when the sum would overflow, and a different\nanswer when it would not.\n\n**Ordering.** Floating-point addition is commutative but not associative. Sorting by increasing\nmagnitude before summing is a classical heuristic and improves the typical case for\nsame-sign data; it changes the answer. So does any parallel or vectorised reduction, which is\nwhy a reduction that must agree bit-by-bit across machines has to fix its association order —\nthe concern the Handbook's `portable-reproducible` flavour exists to address; see\n[About implementation options](../model/07-implementation-options.md).\n\n", "quirks": "\n### What counts, and what is skipped\n\nMicrosoft's `AVERAGE` page documents the range half plainly: \"If a range or cell reference\nargument contains text, logical values, or empty cells, those values are ignored; however,\ncells with the value zero are included.\" It documents the direct half as an *exclusion*:\n\"Logical values and text representations of numbers that you type directly into the list of\narguments are not counted.\"\n\n| Value | Written directly at the call site | Arriving through a range or array |\n|---|---|---|\n| Number | counted | counted (including zeros) |\n| Numeric-looking text (`\"2\"`) | **converted and counted** — Microsoft's page says not counted | skipped (documented) |\n| Non-numeric text (`\"x\"`) | `#VALUE!` (documented) | skipped (documented) |\n| Logical `TRUE` / `FALSE` | **counted as 1 / 0** — Microsoft's page says not counted | skipped (documented) |\n| Empty cell | — | skipped (documented) |\n| Omitted slot | skipped | — |\n| Error value | propagates (documented) | propagates (documented) |\n\nSkipped means skipped from *both* the numerator and the denominator: it does not enter as a\nzero. That is the difference between `AVERAGE` and [AVERAGEA](FUNC.AVERAGEA.md), and it is why\nthe two can differ by a large factor on the same range.\n\nThe consequence people meet in practice: a column with three numbers and two text cells\naverages over three values under `AVERAGE` and over five under `AVERAGEA`. Neither is wrong;\nthey answer different questions, and the function name is the only place the choice is\nrecorded.\n\nSee [Coercion and lifting](../model/02-coercion-and-lifting.md) for the general coercion\nmachinery, and [Missing versus Empty](../model/01-value-universe.md#missing-versus-empty) for\nwhy an omitted slot and an empty cell are different kinds that happen to behave alike here.\n\n\n\n### Result and edge cases\n\n\nReturns `Number`.\n\n- **One admitted value.** Returns that value. Whether it returns *exactly* that value depends\n on whether \\(x/1\\) is performed at all; division by one is exact in IEEE arithmetic, so it\n does.\n- **Values spanning many magnitudes.** The result is correct to within the accumulated\n summation error, which is not bounded by anything the function documents. See the numerical\n notes.\n- **Arrays.** The surface lifts natively (`lift_broadcast_profile: surface_native`); as a\n reduction it consumes array arguments rather than broadcasting over them.\n\n\n\n### Errors\n\n| Error | Condition |\n|---|---|\n| `#DIV/0!` | No value was admitted |\n| `#VALUE!` | A directly-supplied text argument could not be converted to a number |\n| propagated | An error value among the admitted data becomes the result |\n\n", "sources": "- Microsoft, \"AVERAGE function\" —\n \n (the one-line description; the argument text and 255 limit; the six Remarks sentences quoted\n above, including the directly-typed-values rule, the range-ignores rule with its\n zero-cells-included clause, the error-causing-arguments sentence, and the pointers to\n `AVERAGEA`, `AVERAGEIF` and `AVERAGEIFS`).\n- Microsoft, \"AVEDEV function\" —\n \n (quoted here only for the contradicting direct-argument rule).\n- Handbook, [The value universe](../model/01-value-universe.md),\n [Coercion and lifting](../model/02-coercion-and-lifting.md), and\n [About implementation options](../model/07-implementation-options.md).\n- N. J. Higham, *Accuracy and Stability of Numerical Algorithms*, 2nd ed., chapter 4 —\n summation error bounds, pairwise and compensated schemes.\n- T. Ogita, S. M. Rump and S. Oishi, \"Accurate Sum and Dot Product\", *SIAM J. Sci. Comput.* 26\n (2005) — the `Sum2`/`SumK` family named in the numerical notes.\n- B. P. Welford, \"Note on a method for calculating corrected sums of squares and products\",\n *Technometrics* 4 (1962) — the running-mean update.\n- M. Welinder's work on the Gnumeric statistical functions and the surrounding published\n critiques of spreadsheet statistical accuracy — the standard entry point to this literature.\n- Handbook `CHARTER.md` sections 1, 3 and 7; `content/model/06-claim-language.md`.\n\n", "version-differences": "The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.\n\n| Excel 16.0 build | Platform and CPU | Captured inputs |\n|---|---|---:|\n| 20430 | Windows, 64-bit, CPU not recorded | 1,212 |\n\nThe record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.AVERAGE.json).", "what-it-does": "\n`AVERAGE(number1, [number2], …)` returns the **arithmetic mean** of the admitted values:\n\n AVERAGE = (1/n) · Σ_{i=1..n} x_i\n\nwhere \\(n\\) is the count of admitted values. That formula is the whole of the mathematics, and\nit is also, deceptively, the least interesting part of the function. Two other things carry the\nfunction's real content:\n\n1. **Which values are admitted** — the direct-versus-range dual policy described below, which\n decides \\(n\\) as well as the numerator. Everything readers get wrong about `AVERAGE` lives\n here.\n2. **How the sum is formed** — because a sum of \\(n\\) doubles is not a mathematical object but\n an ordered sequence of roundings, and different orderings give different answers.\n\nThe mean is the minimiser of \\(\\sum_i (x_i - c)^2\\) over \\(c\\) — that is its defining\nvariational property, and it is why the mean, not the median, is the centre that `VAR`, `DEVSQ`\nand `STDEV` deviate from. Range: the mean of finite values lies between the minimum and the\nmaximum, a property that plain floating-point summation does **not** guarantee to preserve\nunder all orderings and roundings.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number1` | The first value, range or array to average. Required. | — |\n| `number2 …` | Further values, ranges or arrays. Optional, repeating. | — |\n\n" }, "signature": { "display": "AVERAGE(number1, [number2], ...)", "parameters": [ { "description": null, "name": "number1", "optional": false, "repeats": false }, { "description": null, "name": "number2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 255, "min": 1 }, "category": "Statistical functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "AggregateDirectAndRangeDualPolicy", "determinism_class": "Deterministic", "error_collapse_profile": "ReductionFold", "fec_dependency_profile": "None", "host_interaction_class": "None", "kernel_signature_class": "NumsToNum", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Arithmetic mean of the numbers given", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the average of its arguments", "microsoft_url": "https://support.microsoft.com/en-us/office/average-function-047bac88-d466-426c-a32b-8f33eb960cf6" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "AVERAGE" }, { "locale": "bg-BG", "name": "AVERAGE" }, { "locale": "cs-CZ", "name": "PRŮMĚR" }, { "locale": "da-DK", "name": "MIDDEL" }, { "locale": "de-DE", "name": "MITTELWERT" }, { "locale": "el-GR", "name": "AVERAGE" }, { "locale": "en-AU", "name": "AVERAGE" }, { "locale": "en-GB", "name": "AVERAGE" }, { "locale": "en-US", "name": "AVERAGE" }, { "locale": "es-ES", "name": "PROMEDIO" }, { "locale": "et-EE", "name": "AVERAGE" }, { "locale": "fi-FI", "name": "KESKIARVO" }, { "locale": "fr-FR", "name": "MOYENNE" }, { "locale": "he-IL", "name": "AVERAGE" }, { "locale": "hr-HR", "name": "AVERAGE" }, { "locale": "hu-HU", "name": "ÁTLAG" }, { "locale": "id-ID", "name": "AVERAGE" }, { "locale": "it-IT", "name": "MEDIA" }, { "locale": "ja-JP", "name": "AVERAGE" }, { "locale": "ko-KR", "name": "AVERAGE" }, { "locale": "lt-LT", "name": "AVERAGE" }, { "locale": "lv-LV", "name": "AVERAGE" }, { "locale": "nb-NO", "name": "GJENNOMSNITT" }, { "locale": "nl-NL", "name": "GEMIDDELDE" }, { "locale": "pl-PL", "name": "ŚREDNIA" }, { "locale": "pt-BR", "name": "MÉDIA" }, { "locale": "pt-PT", "name": "MÉDIA" }, { "locale": "ro-RO", "name": "AVERAGE" }, { "locale": "ru-RU", "name": "СРЗНАЧ" }, { "locale": "sk-SK", "name": "AVERAGE" }, { "locale": "sl-SI", "name": "AVERAGE" }, { "locale": "sr-Latn-RS", "name": "AVERAGE" }, { "locale": "sv-SE", "name": "MEDEL" }, { "locale": "th-TH", "name": "AVERAGE" }, { "locale": "tr-TR", "name": "ORTALAMA" }, { "locale": "uk-UA", "name": "AVERAGE" }, { "locale": "vi-VN", "name": "Hàm AVERAGE" }, { "locale": "zh-CN", "name": "AVERAGE" }, { "locale": "zh-HK", "name": "AVERAGE" }, { "locale": "zh-TW", "name": "AVERAGE" } ], "signature": { "display": "AVERAGE(number1, [number2], ...)", "parameters": [ { "description": null, "name": "number1", "optional": false, "repeats": false }, { "description": null, "name": "number2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "surface_name": "AVERAGE", "version_marker": null, "xlcall": { "code": "5", "symbol": "xlfAverage" } }, "microsoft": "https://support.microsoft.com/en-us/office/average-function-047bac88-d466-426c-a32b-8f33eb960cf6" }, "try_it": { "formula": "=AVERAGE(1,2,6)" }, "url": "https://handbook.dnacalc.com/functions/AVERAGE.html", "variants": [], "versions": [ { "behaviour": "1,212 captured inputs are indexed for this environment. Capture dates: 2026-09-29 to 2026-09-29. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 20430", "platform": "Windows, 64-bit, CPU not recorded", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.AVERAGE.json" ] } ] }