{ "category": "Statistical functions", "display_name": "QUARTILE.INC", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.QUARTILE.INC", "implementation_state": { "answer_bank": null, "detail": "Recorded: 5 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 5 recorded answers", "workbook_corpus": { "cells": 5, "matched": 5 } }, "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#L306-L306" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/statistics::list", "catalogue/statistics::quartile", "ported/percentile_common::percentile_inc_kernel", "ported/percentile_common::percentile_exc_kernel", "ported/percentile_common::interpolate_sorted" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/statistics.rs#L306-L306", "state": "matches", "suite": null, "summary": "Matches all 5 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.QUARTILE.INC.json", "name": "QUARTILE.INC", "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- **[QUARTILE.EXC](FUNC.QUARTILE.EXC.md)** is the exclusive sibling, Hyndman–Fan type 6. It uses\n the rank `k*(n+1)` instead of `1 + k*(n-1)`, admits only `quart` in `{1, 2, 3}`, and is\n undefined on small samples. The two agree at `quart = 2` and disagree at `quart = 1` and `3`\n for essentially every data set. Neither supersedes the other; Excel publishes both because the\n statistical community uses both.\n- **`QUARTILE`** is the legacy name, retained in the Compatibility category.\n Microsoft's replacement guidance points `QUARTILE` at `QUARTILE.INC`, and the two are\n documented as computing the same quantity. **The Handbook does not treat that as an identity.**\n A legacy alias and its modern name are two entry points that Excel is free to route to two\n different code paths; the observed agreement of a dotted name and its predecessor is a claim\n requiring evidence, not a definition. No such evidence is in the Handbook's record.\n- **[MEDIAN](FUNC.MEDIAN.md)** is the `quart = 2` case.\n- **[SMALL](FUNC.SMALL.md) and [LARGE](FUNC.LARGE.md)** return order statistics without\n interpolation. When you want an actual data value rather than a quantile, they are the correct\n functions — `QUARTILE.INC` will happily return a number that is in no cell.\n- Readers confuse `QUARTILE.INC` with `PERCENTRANK.INC`, which runs the map the other way: data\n value in, probability out.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nThe mathematics is exact selection plus one linear interpolation, so the error budget is small\nand entirely locatable.\n\n**The rank computation.** `h = 1 + k*(n-1)` with `k = quart/4` is computed in binary64. For\n`quart` in `{0, 2, 4}` the value of `k` is exactly representable (`0`, `0.5`, `1`) and `h` is\nexact whenever `n-1` is. For `quart` in `{1, 3}`, `k` is `0.25` or `0.75` — also exactly\nrepresentable, both being dyadic rationals. This is a small piece of luck specific to quartiles:\nthe four-way split lands on binary fractions, so the rank arithmetic for `QUARTILE.INC` is exact\nfor every `n` up to the point where `n-1` exceeds `2^53`. The general\n[PERCENTILE.INC](FUNC.PERCENTILE.INC.md) has no such luck, because `k = 0.1` is not dyadic, and\nits `floor(h)` can therefore land on the wrong side of an integer boundary. `QUARTILE.INC` does\nnot inherit that hazard.\n\n lower + g * (upper - lower)\n\n**The sort.** Values are sorted with a total-order comparison that falls back to \"equal\" for\nincomparable pairs. Excel's value universe has no NaN, so this is unreachable from a worksheet;\nit becomes reachable if a NaN arrives from an add-in boundary, and the result is then an\nunspecified ordering rather than a diagnosed error. Signed zeros compare equal, so `-0.0` and\n`0.0` may appear in either order; the returned value is `0` either way, but its sign bit is not\ndetermined by the data.\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`.\n\n- **`quart = 0` and `quart = 4`** return the minimum and maximum, so `QUARTILE.INC(A, 0)` is\n `MIN(A)` and `QUARTILE.INC(A, 4)` is `MAX(A)` over the numeric cells — a fact worth knowing\n mostly because it means those two quarts can never fail for a non-empty array.\n- **Repeated values** are ordinary: the sort is not distinct-value, and a data set that is\n entirely one value returns that value at every `quart`.\n- **Non-numeric cells in `array`** are skipped, so `n` is the count of numeric cells, not the\n size of the range. A range of text returns `#NUM!`, because `n = 0`.\n- **Errors in `array`** propagate as themselves.\n- **`array` given as a rectangular grid** is flattened; the quartile is over all its numeric\n cells regardless of shape.\n\n\n\n### Errors\n\n\n| Error | Condition | Source |\n|---|---|---|\n| `#NUM!` | `array` is empty (no numeric values) | documented |\n| `#NUM!` | `quart < 0` or `quart > 4` after truncation | documented |\n| `#VALUE!` | `quart` is non-numeric text | shared coercion rule |\n| propagated | An error value in `array` or in `quart` surfaces as that error | shared coercion rule |\n\n", "sources": "- Microsoft, *QUARTILE.INC function* —\n \n (signature, the five admissible `quart` values, truncation of a non-integer `quart`, and the\n `#NUM!` conditions for an empty array and an out-of-range `quart`). Retrieval was blocked by\n the upstream host for this page; the documented behaviour above is stated as documented\n behaviour and should be re-checked against the page.\n- R. J. Hyndman and Y. Fan, \"Sample Quantiles in Statistical Packages\", *The American\n Statistician* 50(4), 1996, pp. 361–365 — the nine-type taxonomy, and the source of the claim\n that `QUARTILE.INC` is type 7 and `QUARTILE.EXC` is type 6.\n- Handbook [coercion and lifting](../model/02-coercion-and-lifting.md) — the range-scan policy\n that decides what counts toward `n`.\n- Handbook `data/functions/FUNC.QUARTILE.INC.json`, `data/presence/FUNC.QUARTILE.INC.json`.\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`QUARTILE.INC(array, quart)` returns a **sample quantile** of the data in `array`, at one of\nfive fixed probabilities selected by `quart`.\n\nSort the numeric values of `array` ascending and call them `x_(1) <= x_(2) <= … <= x_(n)`. Let\n`k = quart / 4`, so `quart` in `{0, 1, 2, 3, 4}` selects `k` in `{0, 1/4, 1/2, 3/4, 1}`. Define\nthe **rank**\n\n h = 1 + k * (n - 1)\n\nand let `j = floor(h)`, `g = h - j`. Then\n\n QUARTILE.INC = x_(j) + g * ( x_(j+1) - x_(j) )\n\nwhich is the value at position `h` in the sorted data, obtained by linear interpolation between\nthe two adjacent order statistics when `h` is not an integer.\n\nThis is exactly **type 7** in the Hyndman–Fan taxonomy of sample quantile definitions — the same\ndefinition that is R's default `quantile()` and NumPy's default `percentile()`. Two properties\nidentify it:\n\n1. **The rank runs from `1` to `n`.** At `k = 0` the rank is `1` and at `k = 1` it is `n`, so\n `QUARTILE.INC(A, 0)` is the minimum and `QUARTILE.INC(A, 4)` is the maximum, exactly. The\n whole probability interval `[0, 1]` maps onto the data, which is what the *inclusive* in the\n name means and what distinguishes it from [QUARTILE.EXC](FUNC.QUARTILE.EXC.md).\n2. **It is a continuous, piecewise-linear, non-decreasing function of `k`** on `[0, 1]`, and a\n non-decreasing function of every data value. It is the linear interpolation of the inverse\n empirical distribution function evaluated at the plotting positions `(i-1)/(n-1)`.\n\nBecause it interpolates, the result need not be one of the data values. `QUARTILE.INC` of an\ninteger data set is routinely a fraction.\n\nAt `quart = 2` the rank is `1 + (n-1)/2 = (n+1)/2`, which is the median rank, so\n\n QUARTILE.INC(A, 2) = MEDIAN(A)\n\nidentically, for every `n`. This is one of the two quartile identities that both the inclusive\nand exclusive definitions share; see [QUARTILE.EXC](FUNC.QUARTILE.EXC.md).\n\n**There is no single correct definition of a sample quartile.** Hyndman and Fan catalogue nine\nin use across statistical packages, differing in the plotting positions they assign to the order\nstatistics and therefore in the rank formula. The type-7 answer that `QUARTILE.INC` returns is a\ndefensible convention, not a theorem, and a reader comparing Excel against another package should\nexpect a different number rather than a bug.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Admissible |\n|---|---|---|\n| `array` | The data set. Required. | Any range or array; numeric cells are used |\n| `quart` | Which quartile. Required. | `0, 1, 2, 3, 4` |\n\n`array` is consumed by scanning. Text, logical values and blank cells in a scanned range are\nskipped rather than converted — they do not become zeros and they do not enlarge `n`. This is the\nordinary aggregate scan policy described in\n[coercion and lifting](../model/02-coercion-and-lifting.md), and it is the policy the reference\nengine's percentile collector implements.\n\n\n" }, "signature": { "display": "QUARTILE.INC(array, quart)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "quart", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "min": 2 }, "category": "Statistical functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "None", "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": "A quartile of a data set, from percentiles with 0 and 1 included", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the quartile of a data set", "microsoft_url": "https://support.microsoft.com/en-us/office/quartile-inc-function-1bbacc80-5075-42f1-aed6-47d735c4819d" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "QUARTILE.INC" }, { "locale": "bg-BG", "name": "QUARTILE.INC" }, { "locale": "cs-CZ", "name": "QUARTIL.INC" }, { "locale": "da-DK", "name": "KVARTIL.MEDTAG" }, { "locale": "de-DE", "name": "QUARTILE.INC" }, { "locale": "el-GR", "name": "QUARTILE.INC" }, { "locale": "en-AU", "name": "QUARTILE.INC" }, { "locale": "en-GB", "name": "QUARTILE.INC" }, { "locale": "en-US", "name": "QUARTILE.INC" }, { "locale": "es-ES", "name": "CUARTIL.INC" }, { "locale": "et-EE", "name": "QUARTILE.INC" }, { "locale": "fi-FI", "name": "NELJÄNNES.SIS" }, { "locale": "fr-FR", "name": "QUARTILE.INCLURE*" }, { "locale": "he-IL", "name": "QUARTILE.INC" }, { "locale": "hr-HR", "name": "QUARTILE.INC" }, { "locale": "hu-HU", "name": "KVARTILIS.TARTALMAZ" }, { "locale": "id-ID", "name": "QUARTILE.INC" }, { "locale": "it-IT", "name": "QUARTILE.INC" }, { "locale": "ja-JP", "name": "QUARTILE.INC" }, { "locale": "ko-KR", "name": "QUARTILE.INC" }, { "locale": "lt-LT", "name": "QUARTILE.INC" }, { "locale": "lv-LV", "name": "QUARTILE.INC" }, { "locale": "nb-NO", "name": "QUARTILE.INC" }, { "locale": "nl-NL", "name": "KWARTIEL.INC" }, { "locale": "pl-PL", "name": "KWARTYL.PRZEDZ.ZAMK" }, { "locale": "pt-BR", "name": "QUARTILE.INC" }, { "locale": "pt-PT", "name": "QUARTIL.INC" }, { "locale": "ro-RO", "name": "QUARTILE.INC" }, { "locale": "ru-RU", "name": "КВАРТИЛЬ.ВКЛ" }, { "locale": "sk-SK", "name": "QUARTILE.INC" }, { "locale": "sl-SI", "name": "QUARTILE.INC" }, { "locale": "sr-Latn-RS", "name": "QUARTILE.INC" }, { "locale": "sv-SE", "name": "KVARTIL.INK" }, { "locale": "th-TH", "name": "QUARTILE.INC" }, { "locale": "tr-TR", "name": "DÖRTTEBİRLİK.DHL" }, { "locale": "uk-UA", "name": "QUARTILE.INC" }, { "locale": "vi-VN", "name": "QUARTILE.INC" }, { "locale": "zh-CN", "name": "QUARTILE.INC" }, { "locale": "zh-HK", "name": "QUARTILE.INC" }, { "locale": "zh-TW", "name": "QUARTILE.INC" } ], "signature": { "display": "QUARTILE.INC(array, quart)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "quart", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "QUARTILE.INC", "version_marker": null, "xlcall": { "code": "507", "symbol": "xlfQuartile_inc" } }, "microsoft": "https://support.microsoft.com/en-us/office/quartile-inc-function-1bbacc80-5075-42f1-aed6-47d735c4819d" }, "try_it": { "formula": "=QUARTILE.INC({1,2,3,4}, 1)" }, "url": "https://handbook.dnacalc.com/functions/QUARTILE.INC.html", "variants": [], "versions": [] }