{ "category": "Statistical functions", "display_name": "RANK.AVG", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.RANK.AVG", "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#L301-L301" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/statistics::list", "catalogue/statistics::rank_number", "catalogue/statistics::rank", "ported/rank_common::rank_eq", "ported/rank_common::rank_avg" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/statistics.rs#L301-L301", "state": "matches", "suite": null, "summary": "Matches all 5 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.RANK.AVG.json", "name": "RANK.AVG", "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- **`RANK`**, the legacy Compatibility-category name, corresponds to\n [RANK.EQ](FUNC.RANK.EQ.md), **not** to this function. `RANK.AVG` has no legacy predecessor: it\n arrived with the dotted names because averaged ranking was not previously available in Excel at\n all. That asymmetry matters when reading migration guidance — the `.EQ`/`.AVG` pair is one old\n function plus one genuinely new one, not a split of one old function into two.\n- **[CORREL](FUNC.CORREL.md)** over two `RANK.AVG` columns is Spearman's rank correlation\n coefficient, and is the reason `RANK.AVG` exists in a spreadsheet. Excel publishes no\n `SPEARMAN`; this composition is the standard route, and it is only correct with averaged ranks.\n- **`COUNTIF`** reproduces the definition:\n `COUNTIF(ref,\">\"&number) + (COUNTIF(ref,\"=\"&number)+1)/2` is the descending midrank, without\n the presence check.\n- **`PERCENTRANK.INC`** answers the same question on a `[0, 1]` scale and\n does interpolate for absent values.\n- **[SMALL](FUNC.SMALL.md) and [LARGE](FUNC.LARGE.md)**: the inverse identity that holds for\n `RANK.EQ` fails here, because a midrank on tied data is not a valid order-statistic index.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n`RANK.AVG` does one division, by two, and nothing else. That makes it about as numerically clean\nas a worksheet function can be, and it is worth saying why precisely.\n\n**The correction term is exact.** `(m - 1) / 2` with `m` a small integer is a division by a power\nof two, which is exact in binary64 for every `m` up to `2^53`. Adding it to the integer-valued\ncompetition rank is also exact, because `r + (m-1)/2` needs at most one bit below the binary\npoint and `r` is far from the top of the significand. So `RANK.AVG` returns the mathematically\nexact midrank, with no rounding, for any list Excel can hold. There is no accuracy question here\nat all — which is unusual enough in the statistical category to be worth recording.\n\n**The conservation identity is a usable self-check.** Because the midranks of a complete list sum\nto `n(n+1)/2` exactly, and because that sum is computed in exact arithmetic as argued above, a\ncolumn of `RANK.AVG` over its own `ref` must sum to exactly `n(n+1)/2` with no tolerance. If it\ndoes not, the tie detection disagreed with itself somewhere. This is a cheap and strong invariant,\nand it is the one a vector suite for this function should assert first.\n\n**Cost.** Two passes over `ref` per call — one for the strict count, one for the multiplicity —\nso a column of `RANK.AVG` formulas over a shared `ref` is `O(n^2)`.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number` — an exact integer or exact half-integer.\n\n- **`ref` empty of numbers.** `#N/A`.\n- **A block spanning the whole list.** If every value in `ref` equals `number`, then `r = 1` and\n `m = n`, so the answer is `(n+1)/2` — the midpoint. Every element is equally ranked, which is\n the correct statement about a constant sample.\n- **Errors in `ref`** propagate as themselves.\n- **`ref` given as a rectangular grid** is flattened.\n\n\n", "sources": "- Microsoft, *RANK.AVG function* —\n \n (signature, the descending default and the zero/nonzero `order` convention, the averaged-rank\n tie behaviour, and the `#N/A` condition when `number` is absent). Retrieval was blocked by the\n upstream host for this page; the documented behaviour above is stated as documented behaviour\n and should be re-checked against the page.\n- Handbook [coercion and lifting](../model/02-coercion-and-lifting.md) — the range-scan policy\n governing what `ref` contributes.\n- Handbook `data/functions/FUNC.RANK.AVG.json`, `data/presence/FUNC.RANK.AVG.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`RANK.AVG(number, ref, [order])` returns the **midrank** of `number` within `ref`: the average of\nthe positions the tied block containing `number` occupies in the sorted order.\n\nLet `S` be the multiset of numeric values in `ref`, let `r` be the competition rank\n\n order = 0 or omitted (descending): r = #{ i : v_i > number } + 1\n order nonzero (ascending): r = #{ i : v_i < number } + 1\n\nand let `m = #{ i : v_i == number }` be the multiplicity of `number`. The tied block occupies\npositions `r, r+1, …, r+m-1`, whose mean is\n\n RANK.AVG = r + (m - 1) / 2\n\nThis is **fractional ranking**, the `1, 2.5, 2.5, 4` convention. When `m = 1` the correction term\nvanishes and `RANK.AVG` agrees exactly with [RANK.EQ](FUNC.RANK.EQ.md); the two functions differ\nonly on values that repeat.\n\nThe reason midranks exist is a conservation property that competition ranks lack. Summing the\nmidrank over every element of `ref` gives\n\n sum of midranks = 1 + 2 + … + n = n(n+1)/2\n\nfor **every** data set, tied or not, because averaging within a block redistributes the block's\npositions without changing their total. Competition ranking skips positions and does not conserve\nthe sum. That conservation is exactly what the rank-based statistics need: Spearman's rank\ncorrelation, the Wilcoxon rank-sum and signed-rank tests, the Mann–Whitney U statistic and the\nKruskal–Wallis test are all defined on midranks, and all of them lose their null distributions if\nfed competition ranks on tied data. **If the ranks are going into further arithmetic, `RANK.AVG`\nis the correct function and `RANK.EQ` is not.**\n\nTwo consequences of the formula:\n\n1. **The result need not be an integer.** A block of even size lands on a half-integer; a block\n of size `m` shifts the rank by `(m-1)/2`, which is a multiple of `1/2` and nothing finer.\n `RANK.AVG` returns exactly `r` or exactly `r + k/2`, never anything more exotic.\n2. **The result is unchanged by which member of the block you ask about.** Every element of the\n tied block gets the same midrank, because `r` and `m` depend on the *value*, not on its\n position in `ref`.\n\nLike [RANK.EQ](FUNC.RANK.EQ.md), `RANK.AVG` requires `number` to **occur** in `ref`. It reports\nwhere a present value sits; it does not interpolate a position for an absent one. An absent\n`number` yields `#N/A`.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `number` | The value whose rank is wanted. Required. | — |\n| `ref` | The list of numbers to rank within. Required. | — |\n| `order` | `0` or omitted for descending; any nonzero value for ascending. Optional. | `0` (descending) |\n\nThe default is descending: `1` is the largest value.\n\n`ref` is consumed by scanning; text, logical values and blank cells in a scanned range are\nskipped rather than converted, so `n` counts numeric cells only. See\n[coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n" }, "signature": { "display": "RANK.AVG(number, ref, [order])", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false }, { "description": null, "name": "ref", "optional": false, "repeats": false }, { "description": null, "name": "order", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "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": "Rank of a number in a list, with tied values sharing their average rank", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the rank of a number in a list of numbers", "microsoft_url": "https://support.microsoft.com/en-us/office/rank-avg-function-bd406a6f-eb38-4d73-aa8e-6d1c3c72e83a" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "RANK.AVG" }, { "locale": "bg-BG", "name": "RANK.AVG" }, { "locale": "cs-CZ", "name": "RANK.AVG" }, { "locale": "da-DK", "name": "PLADS.GNSN" }, { "locale": "de-DE", "name": "RANK.AVG" }, { "locale": "el-GR", "name": "RANK.AVG" }, { "locale": "en-AU", "name": "RANK.AVG" }, { "locale": "en-GB", "name": "RANK.AVG" }, { "locale": "en-US", "name": "RANK.AVG" }, { "locale": "es-ES", "name": "JERARQUIA.MEDIA" }, { "locale": "et-EE", "name": "RANK.AVG" }, { "locale": "fi-FI", "name": "ARVON.MUKAAN.KESKIARVO" }, { "locale": "fr-FR", "name": "MOYENNE.RANG*" }, { "locale": "he-IL", "name": "RANK.AVG" }, { "locale": "hr-HR", "name": "RANK.AVG" }, { "locale": "hu-HU", "name": "RANG.ÁTL" }, { "locale": "id-ID", "name": "RANK.AVG" }, { "locale": "it-IT", "name": "RANK.AVG" }, { "locale": "ja-JP", "name": "RANK.AVG" }, { "locale": "ko-KR", "name": "RANK.AVG" }, { "locale": "lt-LT", "name": "RANK.AVG" }, { "locale": "lv-LV", "name": "RANK.AVG" }, { "locale": "nb-NO", "name": "RANK.AVG" }, { "locale": "nl-NL", "name": "RANG.GEMIDDELDE" }, { "locale": "pl-PL", "name": "POZYCJA.ŚR" }, { "locale": "pt-BR", "name": "RANK.AVG" }, { "locale": "pt-PT", "name": "ORDEM.MÉD" }, { "locale": "ro-RO", "name": "RANK.AVG" }, { "locale": "ru-RU", "name": "РАНГ.СР" }, { "locale": "sk-SK", "name": "RANK.AVG" }, { "locale": "sl-SI", "name": "RANK.AVG" }, { "locale": "sr-Latn-RS", "name": "RANK.AVG" }, { "locale": "sv-SE", "name": "RANG.MED" }, { "locale": "th-TH", "name": "RANK.AVG" }, { "locale": "tr-TR", "name": "RANK.ORT" }, { "locale": "uk-UA", "name": "RANK.AVG" }, { "locale": "vi-VN", "name": "RANK.AVG" }, { "locale": "zh-CN", "name": "RANK.AVG" }, { "locale": "zh-HK", "name": "RANK.AVG" }, { "locale": "zh-TW", "name": "RANK.AVG" } ], "signature": { "display": "RANK.AVG(number, ref, [order])", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false }, { "description": null, "name": "ref", "optional": false, "repeats": false }, { "description": null, "name": "order", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "RANK.AVG", "version_marker": null, "xlcall": { "code": "508", "symbol": "xlfRank_avg" } }, "microsoft": "https://support.microsoft.com/en-us/office/rank-avg-function-bd406a6f-eb38-4d73-aa8e-6d1c3c72e83a" }, "try_it": { "formula": "=RANK.AVG(2,B2:B5)", "inputs": { "B2": 1, "B3": 2, "B4": 3, "B5": 4 } }, "url": "https://handbook.dnacalc.com/functions/RANK.AVG.html", "variants": [], "versions": [] }