{ "category": "Statistical functions", "display_name": "T.INV", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.T.INV", "implementation_state": { "answer_bank": null, "detail": "Recorded: 4 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 4 recorded answers", "workbook_corpus": { "cells": 4, "matched": 4 } }, "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/distributions.rs#L185-L188", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/chi_f_t_family.rs#L285-L300" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/distributions::nums", "ported/chi_f_t_family::truncate_positive_integer", "ported/chi_f_t_family::validate_probability_open_unit", "ported/chi_f_t_family::search_upper_bound", "ported/chi_f_t_family::t_cdf", "ported/chi_f_t_family::t_inv_2t_kernel", "ported/excel_numeric::binary_with", "ported/excel_numeric::tan_with", "ported/excel_numeric::excel_tan", "ported/excel_numeric::excel_x87_add", "ported/excel_numeric::excel_x87_mul", "ported/excel_numeric::excel_x87_mul_add", "ported/excel_numeric/soft87::pack_raw", "ported/excel_numeric/soft87::zero", "ported/excel_numeric/soft87::inf", "ported/excel_numeric/soft87::pack", "ported/excel_numeric/soft87::ext_pi", "ported/excel_numeric/soft87::ext_one", "ported/excel_numeric/soft87::ext_chs", "ported/excel_numeric/x87::mul", "ported/excel_numeric/x87::add", "ported/special_math_common::bratio_ftoi", "ported/special_math_common::bratio_spmpar1", "ported/special_math_common::bratio_exparg", "ported/special_math_common::bratio_esum", "ported/special_math_common::bratio_esum20", "ported/special_math_common::bratio_alnrel", "ported/special_math_common::bratio_rlog1", "ported/special_math_common::bratio_gam1", "ported/special_math_common::bratio_gamln1", "ported/special_math_common::bratio_gamln", "ported/special_math_common::bratio_algdiv", "ported/special_math_common::bratio_bcorr", "ported/special_math_common::bratio_gsumln", "ported/special_math_common::bratio_betaln", "ported/special_math_common::bratio_betaln_60", "ported/special_math_common::bratio_erf_nswc", "ported/special_math_common::bratio_erfc1", "ported/special_math_common::bratio_rexp", "ported/special_math_common::bratio_psi", "ported/special_math_common::bratio_fpser", "ported/special_math_common::bratio_apser", "ported/special_math_common::bratio_bpser", "ported/special_math_common::bratio_bup", "ported/special_math_common::bratio_brcomp", "ported/special_math_common::bratio_brcmp1", "ported/special_math_common::bratio_bfrac", "ported/special_math_common::bratio_bgrat", "ported/special_math_common::bratio_grat1", "ported/special_math_common::bratio_basym", "ported/special_math_common::bratio", "ported/special_math_common::bisect_inverse", "ported/tan::tan_kernel" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/distributions.rs#L185-L188", "state": "matches", "suite": null, "summary": "Matches all 4 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.T.INV.json", "name": "T.INV", "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- **[T.DIST](FUNC.T.DIST.md)** is the forward function this inverts, in its cumulative form.\n- **[T.INV.2T](FUNC.T.INV.2T.md)** is the *other* inverse, and the distinction is the single\n most consequential fact in this corner of Excel. `T.INV.2T(p, ν)` returns the `t` with\n `P(|T| > t) = p`; `T.INV(p, ν)` returns the `t` with `P(T ≤ t) = p`. They are related by\n\n T.INV.2T(p, ν) = T.INV(1 − p/2, ν) = − T.INV(p/2, ν)\n\n- **`TINV` is the legacy spelling of `T.INV.2T`, not of `T.INV`.** `T.INV` has no legacy\n predecessor: before the dotted names arrived, Excel offered no left-tail t quantile at all.\n A mechanical rewrite of `TINV` to `T.INV` silently changes the answer, and changes its sign\n for `p > ½`. This is the sharpest name-versus-semantics trap in the statistical category.\n- **`NORM.S.INV`** is the ν → ∞ limit and the usual source of an initial guess.\n- Readers confuse `T.INV` with `T.INV.2T`, and both with `T.TEST` (which returns a `p`-value,\n not a critical value).\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nA quantile function is an inverse problem, and there are exactly three ways to attack it: invert\nthe reduction analytically, invert an incomplete-beta inverse, or iterate on the forward\nfunction. Excel's own documentation says, for the two-tail sibling, that it iterates.\n\n**The analytic route.** The t-quantile reduces to the inverse of the regularized incomplete\nbeta: from `T²/(T² + ν) ~ Beta(½, ν/2)`, if `y = I⁻¹_{2p'}(ν/2, ½)` for the appropriate tail\nprobability `p'`, then `t = ±sqrt(ν(1 − y)/y)`. Any library with a good `ibeta_inv` — Boost.Math\nhas one; Cephes' `incbi` is the classical implementation; DCDFLIB and the TOMS algorithms in\nthat lineage are the other standard sources — gets the t-quantile for free and with a stated\nerror bound. This is the route a `natural-best` implementation should take.\n\n**The iterative route.** Newton's method on `F(t) − p = 0` has the derivative available in\nclosed form (it is the density), so each step is cheap, and the function is monotone, so\nbisection is always available as a safeguard. The difficulties are the starting bracket — the\nCornish–Fisher expansion for the t quantile in terms of the normal quantile, given by Hill's\nclassic algorithm and reproduced in A&S 26.7.5, is the standard seed — and the stopping rule.\nIterating to a fixed *absolute* tolerance on `t` is wrong in the tail, where `t` is large;\niterating to a fixed tolerance on `p` is wrong in the centre, where the density is large. A\ntolerance stated in the wrong variable is the most common defect in spreadsheet quantile\nfunctions, and it is precisely what makes a documented statement like \"precision depends on the\nprecision of the forward function\" true rather than merely modest.\n\n**Conditioning.** The derivative of the quantile function is `1/f(t; ν)`, so the condition number\nof the problem blows up wherever the density is small — which is the entire tail. No algorithm\ncan beat this; it is a property of the question. What an implementation *can* do is avoid\nadding error of its own, which means: never form `1 − p` when `p` is near 1 (use a complement\nentry point), never evaluate the forward CDF by subtraction inside the iteration, and use the\nsymmetry `T.INV(p, ν) = −T.INV(1 − p, ν)` to move the work into the half where the argument is\nbetter conditioned.\n\nNone of this is a claim about Excel's internals. Microsoft documents an iterative seek for\n`T.INV.2T`; it does not say what `T.INV` does, and the Handbook does not know.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, a real quantile.\n\n- **`probability = ½`** gives exactly 0 for every ν. Free, exact, and diagnostic.\n- **`probability` near 0 or near 1** is where the quantile is largest in magnitude and where its\n *relative* accuracy is hardest to hold, because the forward CDF is flat there: a change of one\n ulp in `p` moves `t` by an amount inversely proportional to the density, which is tiny in the\n tail. This is the fundamental conditioning statement for any quantile function, and it means\n a t-quantile in the far tail cannot be accurate to the last bit no matter how good the\n algorithm — the information is not in the input.\n- **`probability = 1`** — see Arguments. Documented as admissible, mathematically infinite,\n behaviour unknown.\n- **Small ν** makes the tails heavier and the quantile larger: at ν = 1 the quantile grows like\n `1/p`, so `T.INV(1e-300, 1)` should be an enormous but finite double, and `T.INV(1e-320, 1)`\n should overflow. Where the overflow boundary actually sits, and what Excel returns at it, is\n unprobed.\n- **Round trips.** `T.DIST(T.INV(p, ν), ν, TRUE)` should return `p`, and\n `T.INV(T.DIST(x, ν, TRUE), ν)` should return `x`. Neither round trip can be exact in floating\n point, and the *size* of the discrepancy is a direct measurement of the pair's joint quality.\n No such measurement exists in the Handbook.\n\n\n\n### Errors\n\n\nAs documented on Microsoft's `T.INV` page:\n\n| Error | Documented condition |\n|---|---|\n| `#VALUE!` | Either argument is nonnumeric. |\n| `#NUM!` | `probability ≤ 0` or `probability > 1`. |\n| `#NUM!` | `deg_freedom < 1`. |\n\nErrors in either argument propagate under the universal coercion rule. The Handbook has not\nverified any of this against Excel.\n\n\n", "sources": "\n- Microsoft, \"T.INV function\" —\n \n (syntax; `#VALUE!` for nonnumeric arguments; `#NUM!` for `probability ≤ 0` or\n `probability > 1`; `#NUM!` for `deg_freedom < 1`; and the statement that a non-integer\n `deg_freedom` is truncated). Retrieved for this page. The page states no iteration count,\n tolerance, or accuracy claim.\n- Microsoft, \"T.INV.2T function\" — for the contrast: that page *does* describe an iterative seek\n and does state that precision depends on the forward function.\n- Handbook evidence record `EV-DIST-0011` — cited for its explicit limit that the legacy/modern\n collapse covers forward CDFs only and that no inverse pair has been probed for identity.\n- M. Abramowitz and I. A. Stegun, *Handbook of Mathematical Functions*, section 26.7, including\n 26.7.5 (the Cornish–Fisher-style expansion of the t percentage point in terms of the normal\n deviate).\n- Cephes `incbi` (inverse incomplete beta) and `stdtri`; Boost.Math `ibeta_inv` and\n `students_t_distribution` quantile; DCDFLIB and the TOMS incomplete-beta-inverse lineage — the\n standard analytic routes to a t quantile.\n- Handbook [The value universe](../model/01-value-universe.md) (no infinity kind) and\n [Coercion and lifting](../model/02-coercion-and-lifting.md).\n- Handbook projections `data/functions/FUNC.T.INV.json`, `data/presence/FUNC.T.INV.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`T.INV(probability, deg_freedom)` returns the **left-tail quantile** of Student's\n*t*-distribution with ν degrees of freedom: the value `t` for which\n\n P(T ≤ t) = probability, i.e. t = F⁻¹(p; ν)\n\nwhere `F` is the cumulative distribution function described on\n[T.DIST](FUNC.T.DIST.md#what-it-computes). It is the exact functional inverse of\n`T.DIST(·, ν, TRUE)`.\n\n`F(·; ν)` is continuous and strictly increasing on the whole real line, so the inverse exists,\nis unique, and is single-valued for every `p` in the **open** interval `(0, 1)`. It is not\ndefined at the endpoints: `F⁻¹(p) → −∞` as `p → 0⁺` and `→ +∞` as `p → 1⁻`. Those are genuine\npoles of the quantile function, not removable singularities, and they are where every\nimplementation difficulty lives.\n\nSymmetry gives the identity that halves the work and doubles the accuracy:\n\n T.INV(p, ν) = − T.INV(1 − p, ν)\n\nso `T.INV(½, ν) = 0` exactly for every ν, and the whole function is determined by its values on\n`p ∈ (0, ½]`. There is no closed form for general ν, but there are two:\n\n| ν | `T.INV(p, ν)` |\n|---|---|\n| 1 | `tan(π(p − ½))` |\n| 2 | `(2p − 1) · sqrt( 2 / (4p(1 − p)) )` |\n| ν → ∞ | `NORM.S.INV(p)` |\n\nThe ν = 2 row is exact and elementary — write `u = 2p − 1`; then `t = u·sqrt(2/(1 − u²))`. Along\nwith the ν = 1 tangent form, it gives two full parameter slices where an implementation can be\nchecked against arithmetic rather than against another approximation.\n\nA useful asymptotic for the deep tail: as `p → 0⁺`, `t ~ −(ν/(2p·B(ν/2, ½)·... )` — more\nusefully stated as `t ≈ −ν^{1/2} · (2p·B)^{−1/ν}` with `B = B(ν/2, ½)` the beta function, which\nsays the quantile blows up like a *power* `p^{−1/ν}` rather than like the normal's\n`sqrt(−2 ln p)`. For small ν the growth is violent: at ν = 1 the quantile is proportional to\n`1/p`. That is why t-quantile routines need a starting bracket that is aware of ν and why a\nnormal-based initial guess is a bad one in the tail.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Required |\n|---|---|---|\n| `probability` | \"The probability associated with the Student's t-distribution\" — the left-tail cumulative probability. | Yes |\n| `deg_freedom` | ν, the number of degrees of freedom. Non-integer values are documented as truncated. | Yes |\n\nMicrosoft documents the admissible range as `0 < probability ≤ 1` — `#NUM!` when\n`probability ≤ 0` **or** `probability > 1`. Read literally, `probability = 1` is admitted. The\nmathematics says `F⁻¹(1) = +∞`, which is not a double. **This is a documentation-versus-\nmathematics divergence and the Handbook records it rather than resolving it:** either Excel\nreturns some finite saturation value, or it returns `#NUM!` in a case the documentation admits,\nor it returns an infinity that the value model has no place for\n([The value universe](../model/01-value-universe.md) has no infinity kind). Nobody has checked\nwhich. It is the first probe on the list below.\n\nUnlike the three `T.DIST*` pages, this page **does** document what happens to a non-integer\n`deg_freedom`: \"if `deg_freedom` is not an integer, it is truncated\". That asymmetry in the\ndocumentation — the inverses specify truncation and the forwards say nothing — is itself worth\nrecording.\n\nNumeric slots take ordinary to-number coercion; see\n[Coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n" }, "signature": { "display": "T.INV(probability, deg_freedom)", "parameters": [ { "description": null, "name": "probability", "optional": false, "repeats": false }, { "description": null, "name": "deg_freedom", "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": "The t at which the left-tail probability reaches a given level", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the t-value of the Student's t-distribution as a function of the probability and the degrees of freedom", "microsoft_url": "https://support.microsoft.com/en-us/office/t-inv-function-2908272b-4e61-4942-9df9-a25fec9b0e2e" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "T.INV" }, { "locale": "bg-BG", "name": "T.INV" }, { "locale": "cs-CZ", "name": "T.INV" }, { "locale": "da-DK", "name": "T.INV" }, { "locale": "de-DE", "name": "T.INV" }, { "locale": "el-GR", "name": "T.INV" }, { "locale": "en-AU", "name": "T.INV" }, { "locale": "en-GB", "name": "T.INV" }, { "locale": "en-US", "name": "T.INV" }, { "locale": "es-ES", "name": "INV.T" }, { "locale": "et-EE", "name": "T.INV" }, { "locale": "fi-FI", "name": "T.KÄÄNT" }, { "locale": "fr-FR", "name": "LOI.STUDENT.INVERSE.N*" }, { "locale": "he-IL", "name": "T.INV" }, { "locale": "hr-HR", "name": "T.INV" }, { "locale": "hu-HU", "name": "T.INVERZ" }, { "locale": "id-ID", "name": "T.INV" }, { "locale": "it-IT", "name": "T.INV" }, { "locale": "ja-JP", "name": "T.INV" }, { "locale": "ko-KR", "name": "T.INV" }, { "locale": "lt-LT", "name": "T.INV" }, { "locale": "lv-LV", "name": "T.INV" }, { "locale": "nb-NO", "name": "T.INV" }, { "locale": "nl-NL", "name": "T.INV" }, { "locale": "pl-PL", "name": "ROZKŁ.T.ODWR" }, { "locale": "pt-BR", "name": "T.INV" }, { "locale": "pt-PT", "name": "INV.T" }, { "locale": "ro-RO", "name": "T.INV" }, { "locale": "ru-RU", "name": "СТЬЮДЕНТ.ОБР" }, { "locale": "sk-SK", "name": "T.INV" }, { "locale": "sl-SI", "name": "T.INV" }, { "locale": "sr-Latn-RS", "name": "T.INV" }, { "locale": "sv-SE", "name": "T.INV" }, { "locale": "th-TH", "name": "T.INV" }, { "locale": "tr-TR", "name": "T.TERS" }, { "locale": "uk-UA", "name": "T.INV" }, { "locale": "vi-VN", "name": "T.INV" }, { "locale": "zh-CN", "name": "T.INV" }, { "locale": "zh-HK", "name": "T.INV" }, { "locale": "zh-TW", "name": "T.INV" } ], "signature": { "display": "T.INV(probability, deg_freedom)", "parameters": [ { "description": null, "name": "probability", "optional": false, "repeats": false }, { "description": null, "name": "deg_freedom", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "T.INV", "version_marker": null, "xlcall": { "code": "515", "symbol": "xlfT_inv" } }, "microsoft": "https://support.microsoft.com/en-us/office/t-inv-function-2908272b-4e61-4942-9df9-a25fec9b0e2e" }, "try_it": { "formula": "=T.INV(0.975,10)" }, "url": "https://handbook.dnacalc.com/functions/T.INV.html", "variants": [], "versions": [] }