{ "category": "Statistical functions", "display_name": "T.INV.2T", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.T.INV.2T", "implementation_state": { "answer_bank": null, "detail": "Everything else matches (4 workbook cells). Last-bit means a finite number within 16 ULP of Excel's.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "close", "state_label": "Close: last-bit deviations remain", "summary": "Close: 1 of 4 recorded answers differ in the last bits, worst 1 ULP", "workbook_corpus": { "cells": 4, "last_bit": 1, "matched": 3, "worst_ulp": 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/distributions.rs#L189-L192" ], "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_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#L189-L192", "state": "close", "suite": null, "summary": "Close: 1 of 4 recorded answers differ in the last bits, worst 1 ULP" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.T.INV.2T.json", "name": "T.INV.2T", "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- **[T.DIST.2T](FUNC.T.DIST.2T.md)** is the forward function this inverts, and Microsoft's page\n names it as such.\n- **[T.INV](FUNC.T.INV.md)** is the *left-tail* quantile, a different function. The conversion is\n `T.INV.2T(p, ν) = T.INV(1 − p/2, ν)`. Using `T.INV(p, ν)` where `T.INV.2T(p, ν)` was meant\n gives a number of the wrong sign and the wrong magnitude, and it will not look obviously wrong\n in a spreadsheet.\n- **`TINV` is this surface's legacy spelling** — not `T.INV`'s. `TINV(p, ν)` and\n `T.INV.2T(p, ν)` are documented to compute the same quantity. **Whether they compute it the\n same way, and publish the same bits, is not established.** The Handbook's alias-pairing record\n for the legacy/modern collapse covers five *forward* CDF pairs and states in terms that no\n inverse pair — `GAMMAINV`/`GAMMA.INV`, `CHIINV`/`CHISQ.INV.RT`, `BETAINV`/`BETA.INV`,\n `FINV`/`F.INV.RT`, and `TINV`/`T.INV.2T` — has ever been probed for identity. Treating the\n legacy and modern inverse spellings as interchangeable is an assumption, and this Handbook\n names it as one.\n- **[T.DIST.RT](FUNC.T.DIST.RT.md)**: there is no `T.INV.RT`. The right-tail critical value is\n spelled `T.INV(1 − p, ν)` or `T.INV.2T(2p, ν)`; the second form is preferable, because it does\n not form `1 − p`.\n- **`CONFIDENCE.T`** is the packaged consumer: a t-based confidence half-width is\n `T.INV.2T(alpha, n−1) · s / sqrt(n)`.\n- **`T.TEST`** goes the other way — it returns a `p`-value, not a critical value.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nMicrosoft is unusually forthcoming here, and what it says shapes the whole section: the page\nstates that `T.INV.2T` uses an iterative seek for the `x` at which the forward two-tail function\nequals `probability`, and that **the precision of `T.INV.2T` depends on the precision of\n`T.DIST.2T`**. That is a documented statement about an algorithm, and it is rare enough in\nExcel's documentation to be worth taking seriously: it says the inverse is not independently\naccurate, and that any error in the forward surface is inherited.\n\nThree consequences follow.\n\n**Error inheritance is not neutral — it is amplified by the conditioning.** If the forward\nsurface has relative error ε at `t`, the induced error in the recovered `t` is roughly\n`ε · p / f(t; ν)`. In the tail, where `f` is tiny, that factor is large. An inverse built by\niterating on a forward function that is good to a few ulp can still be poor in absolute terms far\nout, and no amount of iteration fixes it.\n\n**The stopping rule has to be stated in the right variable.** Iterating to a fixed tolerance on\n`t` over-solves in the centre and under-solves in the tail; iterating to a fixed tolerance on `p`\ndoes the reverse. A defensible implementation iterates on `p` with a *relative* tolerance and\npolishes with one Newton step whose derivative is the density — which is available in closed\nform from `T.DIST(·, ν, FALSE)`.\n\n**There is a better route than iteration.** The two-tail critical value follows analytically from\nthe inverse regularized incomplete beta: with `y = I⁻¹_p(ν/2, ½)`, `t = sqrt(ν(1 − y)/y)`. Cephes'\n`incbi`, Boost.Math's `ibeta_inv`, and the DCDFLIB/TOMS lineage all provide the inverse beta with\nstated error bounds, so a `natural-best` implementation should take this route and reserve\niteration for the polish step. Hill's classic t-quantile algorithm and the expansion in A&S\n26.7.5 give the starting approximation when iteration is used; both are stated in terms of the\nnormal deviate and both need a tail correction for small ν, for exactly the power-law reason\ngiven above.\n\nNothing here is a claim about what Excel actually does beyond what its own page says.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, a non-negative critical value.\n\n- **`probability = 1`** is exactly 0. Free and exact.\n- **`probability` near 0** is where the critical value is large and where the problem is badly\n conditioned: `dt/dp = −1/(2 f(t; ν))`, and the density in the tail is tiny, so a one-ulp change\n in `p` moves `t` a long way. No algorithm can recover accuracy the input does not contain.\n This is why a tail critical value is a fundamentally harder request than a central one.\n- **`probability` near 1** is the opposite corner: `t` is near 0 and the answer has plenty of\n absolute room, but computing it from `T.INV(1 − p/2, ν)` would form `1 − p/2` for `p` near 1\n and lose relative precision in the small quantity. A direct two-tail search does not have that\n problem, which is an argument for this surface existing rather than being a wrapper.\n- **Round trip.** `T.DIST.2T(T.INV.2T(p, ν), ν)` should return `p`. Microsoft's own remark makes\n this the defining relationship rather than a nice property: the value is *found* by seeking it.\n\n\n\n### Errors\n\n\nAs documented on Microsoft's `T.INV.2T` 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.2T function\" —\n \n (syntax; the definition `P(|X| > t) = probability`; `#VALUE!` for nonnumeric arguments; `#NUM!`\n for `probability ≤ 0` or `> 1`; `#NUM!` for `deg_freedom < 1`; truncation of a non-integer\n `deg_freedom`; the one-tailed conversion by doubling the probability; and the statement that\n the precision of `T.INV.2T` depends on the precision of `T.DIST.2T`, found by an iterative\n seek). Retrieved for this page; see the arity discrepancy noted above.\n- Handbook evidence record `EV-DIST-0011` — cited for its explicit statement that no legacy/\n modern *inverse* pair, `TINV`/`T.INV.2T` included, has ever been probed for identity, and that\n no inverse figure may be inherited across such a pair.\n- M. Abramowitz and I. A. Stegun, *Handbook of Mathematical Functions*, section 26.7, including\n 26.7.5 (t percentage points in terms of the normal deviate) and the percentage-point tables\n this surface replaces.\n- Cephes `incbi` / `stdtri`; Boost.Math `ibeta_inv` and the `students_t_distribution` quantile;\n DCDFLIB and the TOMS incomplete-beta-inverse lineage — the analytic route to a t critical\n value.\n- Handbook [Coercion and lifting](../model/02-coercion-and-lifting.md).\n- Handbook projections `data/functions/FUNC.T.INV.2T.json`, `data/presence/FUNC.T.INV.2T.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.2T(probability, deg_freedom)` returns the **two-tailed critical value** of Student's\n*t*-distribution with ν degrees of freedom. Microsoft states the definition directly: it returns\n\"that value `t`, such that `P(|X| > t) = probability` where `X` is a random variable that\nfollows the t-distribution\".\n\nSo it is the exact inverse of [T.DIST.2T](FUNC.T.DIST.2T.md), and it is related to the left-tail\nquantile of [T.INV](FUNC.T.INV.md) by\n\n T.INV.2T(p, ν) = T.INV(1 − p/2, ν) = − T.INV(p/2, ν)\n\nThis is the number printed in every statistics textbook's t table. Asking for the 5% two-sided\ncritical value at 10 degrees of freedom is `T.INV.2T(0.05, 10)`.\n\nBecause `P(|T| > t)` is continuous and strictly decreasing from 1 at `t = 0` to 0 as `t → ∞`,\nthe inverse exists and is unique on `p ∈ (0, 1]`, with\n\n T.INV.2T(1, ν) = 0 exactly, for every ν\n T.INV.2T(p, ν) → +∞ as p → 0⁺\n\nThe range is `[0, ∞)`: this surface never returns a negative number. That is worth stating\nplainly, because it is the fastest way to tell it apart from `T.INV`, which returns negative\nvalues for `p < ½`.\n\nClosed forms at the two small integer degrees of freedom, obtained by inverting the elementary\ntwo-tail formulas:\n\n| ν | `T.INV.2T(p, ν)` |\n|---|---|\n| 1 | `cot(πp/2)` = `tan(π(1 − p)/2)` |\n| 2 | `sqrt( 2(1 − p²) / p² )` = `sqrt(2)·sqrt(1 − p²)/p` |\n| ν → ∞ | `NORM.S.INV(1 − p/2)` |\n\nBoth are exact and elementary — a full parameter slice each on which any implementation can be\nchecked against arithmetic instead of against another approximation.\n\nDeep-tail growth: as `p → 0⁺` the critical value grows like `p^{−1/ν}`, so it explodes as a power\nlaw, violently for small ν (`ν = 1` gives growth proportional to `1/p`) and gently for large ν.\nAn implementation whose starting bracket is derived from the normal quantile — which grows only\nlike `sqrt(−2 ln p)` — will start catastrophically low in the small-ν tail.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Required |\n|---|---|---|\n| `probability` | The two-tail probability `P(\\|T\\| > t)`. | Yes |\n| `deg_freedom` | ν, the number of degrees of freedom. Non-integer values are documented as truncated. | Yes |\n\nDocumented admissible range: `#NUM!` when `probability ≤ 0` or `probability > 1`, so\n`probability = 1` is admitted — and here, unlike on `T.INV`, that is mathematically fine: the\nanswer is exactly 0. The two inverse surfaces have opposite behaviour at their shared documented\nboundary, which is a small but real reason to keep them straight.\n\nMicrosoft documents that a non-integer `deg_freedom` is truncated, and that one-tailed values can\nbe recovered by passing `2 * probability`.\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.2T(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 two-tailed probability falls to a given level", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the inverse of the Student's t-distribution", "microsoft_url": "https://support.microsoft.com/en-us/office/t-inv-2t-function-ce72ea19-ec6c-4be7-bed2-b9baf2264f17" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "T.INV.2T" }, { "locale": "bg-BG", "name": "T.INV.2T" }, { "locale": "cs-CZ", "name": "T.INV.2T" }, { "locale": "da-DK", "name": "T.INV.2T" }, { "locale": "de-DE", "name": "T.INV.2T" }, { "locale": "el-GR", "name": "T.INV.2T" }, { "locale": "en-AU", "name": "T.INV.2T" }, { "locale": "en-GB", "name": "T.INV.2T" }, { "locale": "en-US", "name": "T.INV.2T" }, { "locale": "es-ES", "name": "INV.T.2C" }, { "locale": "et-EE", "name": "T.INV.2T" }, { "locale": "fi-FI", "name": "T.KÄÄNT.2S" }, { "locale": "fr-FR", "name": "LOI.STUDENT.INVERSE.BILATERALE*" }, { "locale": "he-IL", "name": "T.INV.2T" }, { "locale": "hr-HR", "name": "T.INV.2T" }, { "locale": "hu-HU", "name": "T.INVERZ.2SZ" }, { "locale": "id-ID", "name": "T.INV.2T" }, { "locale": "it-IT", "name": "T.INV.2T" }, { "locale": "ja-JP", "name": "T.INV.2T" }, { "locale": "ko-KR", "name": "T.INV.2T" }, { "locale": "lt-LT", "name": "T.INV.2T" }, { "locale": "lv-LV", "name": "T.INV.2T" }, { "locale": "nb-NO", "name": "T.INV.2T" }, { "locale": "nl-NL", "name": "T.INV.2T" }, { "locale": "pl-PL", "name": "ROZKŁ.T.ODWR.DS" }, { "locale": "pt-BR", "name": "T.INV.2T" }, { "locale": "pt-PT", "name": "INV.T.2C" }, { "locale": "ro-RO", "name": "T.INV.2T" }, { "locale": "ru-RU", "name": "СТЬЮДЕНТ.ОБР.2Х" }, { "locale": "sk-SK", "name": "T.INV.2T" }, { "locale": "sl-SI", "name": "T.INV.2T" }, { "locale": "sr-Latn-RS", "name": "T.INV.2T" }, { "locale": "sv-SE", "name": "T.INV.2T" }, { "locale": "th-TH", "name": "T.INV.2T" }, { "locale": "tr-TR", "name": "T.TERS.2K" }, { "locale": "uk-UA", "name": "T.INV.2T" }, { "locale": "vi-VN", "name": "T.INV.2T" }, { "locale": "zh-CN", "name": "T.INV.2T" }, { "locale": "zh-HK", "name": "T.INV.2T" }, { "locale": "zh-TW", "name": "T.INV.2T" } ], "signature": { "display": "T.INV.2T(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.2T", "version_marker": null, "xlcall": { "code": "516", "symbol": "xlfT_inv_2t" } }, "microsoft": "https://support.microsoft.com/en-us/office/t-inv-2t-function-ce72ea19-ec6c-4be7-bed2-b9baf2264f17" }, "try_it": { "formula": "=T.INV.2T(0.05, 10)" }, "url": "https://handbook.dnacalc.com/functions/T.INV.2T.html", "variants": [], "versions": [] }