{ "category": "Statistical functions", "display_name": "T.DIST", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.T.DIST", "implementation_state": { "answer_bank": null, "detail": "Everything else matches (5 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 5 recorded answers differ in the last bits, worst 1 ULP", "workbook_corpus": { "cells": 5, "last_bit": 1, "matched": 4, "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#L162-L165", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/chi_f_t_family.rs#L228-L246", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/chi_f_t_family.rs#L257-L267" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/distributions::nums", "ported/chi_f_t_family::truncate_positive_integer", "ported/chi_f_t_family::t_cdf", "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_pow_chain", "ported/excel_numeric::excel_x87_add", "ported/excel_numeric::excel_x87_mul", "ported/excel_numeric::excel_x87_mul_add", "ported/excel_numeric/x87::mul", "ported/excel_numeric/x87::add", "ported/excel_numeric/x87_chains::pow2_positive", "ported/excel_numeric/x87_chains::pow2", "ported/excel_numeric/x87_chains::exp_ext", "ported/excel_numeric/x87_chains::exp_with", "ported/excel_numeric/x87_chains::excel_exp", "ported/excel_numeric/x87_chains::log_with", "ported/excel_numeric/x87_chains::excel_log", "ported/special_math_common::ln_gamma", "ported/special_math_common::gamma", "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" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/distributions.rs#L162-L165", "state": "close", "suite": null, "summary": "Close: 1 of 5 recorded answers differ in the last bits, worst 1 ULP" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.T.DIST.json", "name": "T.DIST", "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.RT](FUNC.T.DIST.RT.md)** is the right-tail complement: `1 − F(x; ν)`, computed\n directly rather than by subtraction, and therefore the accurate surface for small upper-tail\n probabilities.\n- **[T.DIST.2T](FUNC.T.DIST.2T.md)** is the two-tail area `P(|T| > x)`, defined only for\n `x ≥ 0`.\n- **[T.INV](FUNC.T.INV.md)** is this function's inverse in the cumulative sense: `T.INV(p, ν)`\n is the `x` with `T.DIST(x, ν, TRUE) = p`. **[T.INV.2T](FUNC.T.INV.2T.md)** inverts `T.DIST.2T`\n instead.\n- **`TDIST`** is the legacy compatibility spelling, and it is *not* this function.\n `TDIST(x, ν, tails)` takes `x ≥ 0` and returns a tail area — one-tailed for `tails = 1`,\n two-tailed for `tails = 2` — so its modern counterparts are `T.DIST.RT` and `T.DIST.2T`,\n not `T.DIST`. `T.DIST` has no legacy predecessor at all; the left-tail CDF and the density\n were both new surfaces when the dotted names arrived. Anyone mechanically rewriting `TDIST`\n to `T.DIST` is changing the mathematics, not modernizing a name.\n- **`NORM.S.DIST`** is the ν → ∞ limit; **`F.DIST`** is a relative, since `T² ~ F(1, ν)`, which\n gives `F.DIST.RT(x², 1, ν) = T.DIST.2T(x, ν)` as an identity worth probing across the pair.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nThree separate difficulties, and they are not the same difficulty.\n\n**The density.** Evaluating `Γ((ν+1)/2)/Γ(ν/2)` directly overflows for moderate ν even though\nthe ratio is perfectly well scaled — it grows only like `sqrt(ν/2)`. The standard remedy is\n`exp(lgamma((ν+1)/2) − lgamma(ν/2))`, or the reciprocal of the beta function `B(½, ν/2)`; Cody's\nand the fdlibm-lineage `lgamma` are the usual sources for the log-gamma. The second factor wants\n`exp(−((ν+1)/2) · log1p(x²/ν))` rather than a literal `pow(1 + x*x/ν, ...)`: the `log1p` form\nkeeps relative accuracy when `x²/ν` is small, which is exactly the region where the density is\nlargest and where a spreadsheet user is most likely to be looking.\n\n**The CDF.** The workhorse is the regularized incomplete beta function. Numerical Recipes'\n`betai`/`betacf` pair — the Lentz continued fraction for `I_z(a, b)`, with the reflection\n`I_z(a,b) = 1 − I_{1−z}(b,a)` applied when `z > (a+1)/(a+b+2)` so that the fraction is always\nevaluated in its rapidly converging half — is the canonical treatment, and Cephes (`incbet`,\n`stdtr`) and Boost.Math (`ibeta`, `students_t_distribution`) are the two implementations most\nworth reading. For **integer** ν there is an alternative: A&S 26.7.3 and 26.7.4 give finite\nclosed-form expressions in `arctan` and powers of `sin`/`cos`, separately for odd and even ν.\nThese are exact in principle and fast, and they are also a trap — the alternating recursions in\nthem lose digits for large ν, which is why general-purpose libraries use the incomplete beta\ninstead. An implementation that switches on integer ν has to decide where to switch and be able\nto defend the choice.\n\n**Which tail you compute.** `F(x; ν)` for `x > 0` written as `1 − ½ I(...)` is a subtraction from\none, and the upper-tail information dies in it. A careful implementation computes the *small*\nquantity directly — `½ I_{ν/(ν+x²)}(ν/2, ½)` — and only then subtracts, and it exposes the\nsmall quantity as its own surface. That is the design reason `T.DIST.RT` exists next to\n`T.DIST`, and it is why the two are not interchangeable at the last bits even where they agree\nmathematically.\n\nNothing here is a claim about what Excel does internally. The Handbook does not know Excel's\nalgorithm for this surface.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, a probability in `(0, 1)` when `cumulative` is TRUE and a density value in\n`(0, f(0; ν)]` when it is FALSE.\n\n- **Large positive `x`, cumulative.** `F(x; ν)` approaches 1 and, in double precision, becomes\n indistinguishable from 1 long before the true value reaches it. Everything informative about\n the upper tail has been rounded away. `T.DIST.RT` exists precisely to keep it, and is the\n surface to use for right-tail work.\n- **Large negative `x`, cumulative.** The left tail underflows gracefully toward 0 and stays\n informative far longer than the upper tail does, because the value itself is small rather than\n being a small perturbation of 1.\n- **`x = 0`.** `F(0; ν) = ½` exactly, for every ν, by symmetry. The density at zero is\n `Γ((ν+1)/2) / (sqrt(νπ) Γ(ν/2))`, which is `1/π` at ν = 1 and tends to `1/sqrt(2π)` as\n ν → ∞. Both are exact-value probes that cost nothing to run.\n- **Symmetry.** `T.DIST(−x, ν, TRUE) = 1 − T.DIST(x, ν, TRUE)` and\n `T.DIST(−x, ν, FALSE) = T.DIST(x, ν, FALSE)` are exact mathematical identities. Whether\n Excel's published bits satisfy them is an empirical question nobody has answered here.\n- **Very large ν.** The distribution converges to the standard normal, so `T.DIST(x, ν, TRUE)`\n should approach `NORM.S.DIST(x, TRUE)`. How large ν has to be before the two agree to the last\n bit, and whether the approach is monotone in the published bits, is unprobed.\n\n\nEmpty, missing and error arguments follow the shared call model; see\n[The value universe](../model/01-value-universe.md).\n\n\n\n### Errors\n\n\nAs documented on Microsoft's `T.DIST` page:\n\n| Error | Documented condition |\n|---|---|\n| `#VALUE!` | Any argument is nonnumeric. |\n| unnamed error value | `deg_freedom < 1`. The page says only that the function \"returns an error value\" and that `deg_freedom` \"needs to be at least 1\". |\n\nThat second row is a documentation defect, not a summary of one. The sibling pages `T.DIST.2T`\nand `T.DIST.RT` both name `#NUM!` for exactly the same condition; the `T.DIST` page declines to\nname it. The Handbook records the gap rather than filling it in from the siblings — a reader who\nneeds the code should test for it, and a reader writing a compatibility implementation should\ntreat the code as unpinned by documentation.\n\nErrors arriving in any argument propagate under the universal coercion rule. The Handbook has\nnot verified any of this against Excel.\n\n\n", "sources": "- Microsoft, \"T.DIST function\" —\n \n (syntax, the three required arguments, the `cumulative` switch, the `#VALUE!` condition, and\n the unnamed error for `deg_freedom < 1`). Retrieved for this page.\n- Microsoft, \"T.DIST.2T function\" and \"T.DIST.RT function\" — the sibling pages that *do* name\n `#NUM!` for `deg_freedom < 1`, cited here only to establish that the `T.DIST` page's silence\n is a gap rather than a shared convention.\n- M. Abramowitz and I. A. Stegun, *Handbook of Mathematical Functions*, section 26.7 (Student's\n t-distribution: the density, the integral, and the finite closed forms for integer degrees of\n freedom, 26.7.3–26.7.4).\n- W. H. Press et al., *Numerical Recipes*, the incomplete beta function `betai`/`betacf` and its\n application to Student's t.\n- Cephes (`incbet`, `stdtr`) and Boost.Math (`ibeta`, `students_t_distribution`) as the two\n readable production treatments of the same reduction.\n- Handbook [The value universe](../model/01-value-universe.md) and\n [Coercion and lifting](../model/02-coercion-and-lifting.md).\n\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.DIST(x, deg_freedom, cumulative)` evaluates Student's *t*-distribution with ν degrees of\nfreedom — the density when `cumulative` is FALSE, the **left-tail** cumulative distribution\nfunction when it is TRUE.\n\nThe density is\n\n f(x; ν) = Γ((ν+1)/2) / ( sqrt(νπ) · Γ(ν/2) ) · (1 + x²/ν)^(−(ν+1)/2)\n\non the whole real line, for ν > 0. It is symmetric about zero, unimodal, and has tails that\ndecay like `|x|^(−(ν+1))` — polynomially, not exponentially, which is the entire reason the\ndistribution exists as a separate object from the normal.\n\nThe cumulative form has no elementary closed form for general ν, but it has an exact expression\nin the regularized incomplete beta function `I_z(a, b)`:\n\n F(x; ν) = 1 − ½ · I_{ν/(ν+x²)}(ν/2, ½) for x ≥ 0\n F(x; ν) = ½ · I_{ν/(ν+x²)}(ν/2, ½) for x ≤ 0\n\nEquivalently, if `T ~ t_ν` then `T²/(T² + ν) ~ Beta(½, ν/2)`; the beta identity above is that\nstatement rearranged. Abramowitz & Stegun give the distribution and its integrals in section\n26.7.\n\nDomain and range: `x` ranges over all reals and `F` over `(0, 1)`, strictly — the CDF attains\nneither endpoint at any finite `x`. There are no poles and no branch cuts; `f` is real-analytic\nin `x` for every ν > 0.\n\nThe limiting and special cases are worth keeping in view, because they are the cheapest\ncorrectness checks anyone has:\n\n| ν | Distribution | Closed form for `F` |\n|---|---|---|\n| 1 | Standard Cauchy | `½ + arctan(x)/π` |\n| 2 | — | `½ · (1 + x / sqrt(x² + 2))` |\n| ν → ∞ | Standard normal | `Φ(x)` |\n\nMoments exist only up to order ν: the mean is 0 for ν > 1 and undefined for ν = 1, and the\nvariance is `ν/(ν−2)` for ν > 2 and infinite for 1 < ν ≤ 2. A t-distribution with one degree of\nfreedom has no mean at all, which is why the ν = 1 corner is a genuinely different object rather\nthan an extreme setting of the same one.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Required |\n|---|---|---|\n| `x` | The value at which the distribution is evaluated. | Yes |\n| `deg_freedom` | ν, \"an integer indicating the number of degrees of freedom\" (Microsoft). | Yes |\n| `cumulative` | TRUE selects the cumulative distribution function; FALSE selects the density. | Yes |\n\n`x` may be negative. That is the whole point of this surface: the legacy `TDIST` spelling\ndocumented a non-negative `x` and returned a tail area, while `T.DIST` is the ordinary\nleft-tail CDF over the full real line.\n\nMicrosoft describes `deg_freedom` as an integer but the `T.DIST` page — unlike the `T.INV` and\n`T.INV.2T` pages — does **not** say what happens to a non-integer value. See \"What has not been\nchecked\".\n\nThe numeric slots are subject to ordinary to-number coercion; see\n[Coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n" }, "signature": { "display": "T.DIST(x, deg_freedom, cumulative)", "parameters": [ { "description": null, "name": "x", "optional": false, "repeats": false }, { "description": null, "name": "deg_freedom", "optional": false, "repeats": false }, { "description": null, "name": "cumulative", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 3 }, "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": "Student's t distribution: the density or the left-tail probability", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the Percentage Points (probability) for the Student t-distribution", "microsoft_url": "https://support.microsoft.com/en-us/office/t-dist-function-4329459f-ae91-48c2-bba8-1ead1c6c21b2" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "T.DIST" }, { "locale": "bg-BG", "name": "T.DIST" }, { "locale": "cs-CZ", "name": "T.DIST" }, { "locale": "da-DK", "name": "T.FORDELING" }, { "locale": "de-DE", "name": "T.DIST" }, { "locale": "el-GR", "name": "T.DIST" }, { "locale": "en-AU", "name": "T.DIST" }, { "locale": "en-GB", "name": "T.DIST" }, { "locale": "en-US", "name": "T.DIST" }, { "locale": "es-ES", "name": "DISTR.T.N" }, { "locale": "et-EE", "name": "T.DIST" }, { "locale": "fi-FI", "name": "T.JAKAUMA" }, { "locale": "fr-FR", "name": "LOI.STUDENT.N*" }, { "locale": "he-IL", "name": "T.DIST" }, { "locale": "hr-HR", "name": "T.DIST" }, { "locale": "hu-HU", "name": "T.ELOSZL" }, { "locale": "id-ID", "name": "T.DIST" }, { "locale": "it-IT", "name": "T.DIST" }, { "locale": "ja-JP", "name": "T.DIST" }, { "locale": "ko-KR", "name": "T.DIST" }, { "locale": "lt-LT", "name": "T.DIST" }, { "locale": "lv-LV", "name": "T.DIST" }, { "locale": "nb-NO", "name": "T.DIST" }, { "locale": "nl-NL", "name": "T.DIST" }, { "locale": "pl-PL", "name": "ROZKŁ.T" }, { "locale": "pt-BR", "name": "T.DIST" }, { "locale": "pt-PT", "name": "DIST.T" }, { "locale": "ro-RO", "name": "T.DIST" }, { "locale": "ru-RU", "name": "СТЬЮДЕНТ.РАСП" }, { "locale": "sk-SK", "name": "T.DIST" }, { "locale": "sl-SI", "name": "T.DIST" }, { "locale": "sr-Latn-RS", "name": "T.DIST" }, { "locale": "sv-SE", "name": "T.FÖRD" }, { "locale": "th-TH", "name": "T.DIST" }, { "locale": "tr-TR", "name": "T.DAĞ" }, { "locale": "uk-UA", "name": "T.DIST" }, { "locale": "vi-VN", "name": "T.DIST" }, { "locale": "zh-CN", "name": "T.DIST" }, { "locale": "zh-HK", "name": "T.DIST" }, { "locale": "zh-TW", "name": "T.DIST" } ], "signature": { "display": "T.DIST(x, deg_freedom, cumulative)", "parameters": [ { "description": null, "name": "x", "optional": false, "repeats": false }, { "description": null, "name": "deg_freedom", "optional": false, "repeats": false }, { "description": null, "name": "cumulative", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "T.DIST", "version_marker": null, "xlcall": { "code": "512", "symbol": "xlfT_dist" } }, "microsoft": "https://support.microsoft.com/en-us/office/t-dist-function-4329459f-ae91-48c2-bba8-1ead1c6c21b2" }, "try_it": { "formula": "=T.DIST(1,10,TRUE)" }, "url": "https://handbook.dnacalc.com/functions/T.DIST.html", "variants": [], "versions": [] }