T.DIST

What it does

T.DIST(x, deg_freedom, cumulative)

T.DIST(x, deg_freedom, cumulative) evaluates Student's t-distribution with ν degrees of freedom — the density when cumulative is FALSE, the left-tail cumulative distribution function when it is TRUE.

The density is

f(x; ν) = Γ((ν+1)/2) / ( sqrt(νπ) · Γ(ν/2) ) · (1 + x²/ν)^(−(ν+1)/2)

on the whole real line, for ν > 0. It is symmetric about zero, unimodal, and has tails that decay like |x|^(−(ν+1)) — polynomially, not exponentially, which is the entire reason the distribution exists as a separate object from the normal.

The cumulative form has no elementary closed form for general ν, but it has an exact expression in the regularized incomplete beta function I_z(a, b):

F(x; ν) = 1 − ½ · I_{ν/(ν+x²)}(ν/2, ½)     for x ≥ 0
F(x; ν) =     ½ · I_{ν/(ν+x²)}(ν/2, ½)     for x ≤ 0

Equivalently, if T ~ t_ν then T²/(T² + ν) ~ Beta(½, ν/2); the beta identity above is that statement rearranged. Abramowitz & Stegun give the distribution and its integrals in section 26.7.

Domain and range: x ranges over all reals and F over (0, 1), strictly — the CDF attains neither endpoint at any finite x. There are no poles and no branch cuts; f is real-analytic in x for every ν > 0.

The limiting and special cases are worth keeping in view, because they are the cheapest correctness checks anyone has:

Moments exist only up to order ν: the mean is 0 for ν > 1 and undefined for ν = 1, and the variance is ν/(ν−2) for ν > 2 and infinite for 1 < ν ≤ 2. A t-distribution with one degree of freedom has no mean at all, which is why the ν = 1 corner is a genuinely different object rather than an extreme setting of the same one.

Arguments

x may be negative. That is the whole point of this surface: the legacy TDIST spelling documented a non-negative x and returned a tail area, while T.DIST is the ordinary left-tail CDF over the full real line.

Microsoft describes deg_freedom as an integer but the T.DIST page — unlike the T.INV and T.INV.2T pages — does not say what happens to a non-integer value. See "What has not been checked".

The numeric slots are subject to ordinary to-number coercion; see Coercion and lifting.

Try it

Quirks

Result and edge cases

Returns Number, a probability in (0, 1) when cumulative is TRUE and a density value in (0, f(0; ν)] when it is FALSE.

• Large positive x, cumulative. F(x; ν) approaches 1 and, in double precision, becomes indistinguishable from 1 long before the true value reaches it. Everything informative about the upper tail has been rounded away. T.DIST.RT exists precisely to keep it, and is the surface to use for right-tail work.
• Large negative x, cumulative. The left tail underflows gracefully toward 0 and stays informative far longer than the upper tail does, because the value itself is small rather than being a small perturbation of 1.
• x = 0. F(0; ν) = ½ exactly, for every ν, by symmetry. The density at zero is Γ((ν+1)/2) / (sqrt(νπ) Γ(ν/2)), which is 1/π at ν = 1 and tends to 1/sqrt(2π) as ν → ∞. Both are exact-value probes that cost nothing to run.
• Symmetry. T.DIST(−x, ν, TRUE) = 1 − T.DIST(x, ν, TRUE) and T.DIST(−x, ν, FALSE) = T.DIST(x, ν, FALSE) are exact mathematical identities. Whether Excel's published bits satisfy them is an empirical question nobody has answered here.
• Very large ν. The distribution converges to the standard normal, so T.DIST(x, ν, TRUE) should approach NORM.S.DIST(x, TRUE). How large ν has to be before the two agree to the last bit, and whether the approach is monotone in the published bits, is unprobed.

Empty, missing and error arguments follow the shared call model; see The value universe.

Errors

As documented on Microsoft's T.DIST page:

That second row is a documentation defect, not a summary of one. The sibling pages T.DIST.2T and T.DIST.RT both name #NUM! for exactly the same condition; the T.DIST page declines to name it. The Handbook records the gap rather than filling it in from the siblings — a reader who needs the code should test for it, and a reader writing a compatibility implementation should treat the code as unpinned by documentation.

Errors arriving in any argument propagate under the universal coercion rule. The Handbook has not verified any of this against Excel.

How to implement

Numerical notes

Three separate difficulties, and they are not the same difficulty.

The density. Evaluating Γ((ν+1)/2)/Γ(ν/2) directly overflows for moderate ν even though the ratio is perfectly well scaled — it grows only like sqrt(ν/2). The standard remedy is exp(lgamma((ν+1)/2) − lgamma(ν/2)), or the reciprocal of the beta function B(½, ν/2); Cody's and the fdlibm-lineage lgamma are the usual sources for the log-gamma. The second factor wants exp(−((ν+1)/2) · log1p(x²/ν)) rather than a literal pow(1 + x*x/ν, ...): the log1p form keeps relative accuracy when x²/ν is small, which is exactly the region where the density is largest and where a spreadsheet user is most likely to be looking.

The CDF. The workhorse is the regularized incomplete beta function. Numerical Recipes' betai/betacf pair — the Lentz continued fraction for I_z(a, b), with the reflection I_z(a,b) = 1 − I_{1−z}(b,a) applied when z > (a+1)/(a+b+2) so that the fraction is always evaluated in its rapidly converging half — is the canonical treatment, and Cephes (incbet, stdtr) and Boost.Math (ibeta, students_t_distribution) are the two implementations most worth reading. For integer ν there is an alternative: A&S 26.7.3 and 26.7.4 give finite closed-form expressions in arctan and powers of sin/cos, separately for odd and even ν. These are exact in principle and fast, and they are also a trap — the alternating recursions in them lose digits for large ν, which is why general-purpose libraries use the incomplete beta instead. An implementation that switches on integer ν has to decide where to switch and be able to defend the choice.

Which tail you compute. F(x; ν) for x > 0 written as 1 − ½ I(...) is a subtraction from one, and the upper-tail information dies in it. A careful implementation computes the small quantity directly — ½ I_{ν/(ν+x²)}(ν/2, ½) — and only then subtracts, and it exposes the small quantity as its own surface. That is the design reason T.DIST.RT exists next to T.DIST, and it is why the two are not interchangeable at the last bits even where they agree mathematically.

Nothing here is a claim about what Excel does internally. The Handbook does not know Excel's algorithm for this surface.

Rust code

40 t_dist "T.DIST" (3, 3) [V "x", V "deg_freedom", V "cumulative"] |s, a, sv| {
    let [x, df] = nums::<2>(s, a)?;
    out(s, cft::t_dist_kernel(x, df, flag(s, a, 2)?))
}

fn t_pdf(x: f64, deg_freedom: f64) -> Result<f64, WorksheetErrorCode> {
    let v = truncate_positive_integer(deg_freedom)?;
    if v == 1.0 {
        // Live Excel 16.0 b20326: T.DIST(x,1,FALSE)=1/(PI()*(1+x*x)) 20/20.
        // 1/PI()/(1+x*x) is 12/20; 1/(PI()+PI()*x*x) is 18/20.
        return Ok(1.0 / (std::f64::consts::PI * (1.0 + x * x)));
    }
    if v == 2.0 {
        // Live Excel 16.0 b20326: T.DIST(x,2,FALSE)=POWER(2+x*x,-1.5) 15/15.
        // 1/EXP(1.5*LN) is 15/15 in Excel but only 10/15 via spilled excel_exp/log.
        // excel_pow_chain is 15/15 including |x|=4,8.
        return Ok(crate::ported::excel_numeric::excel_pow_chain(2.0 + x * x, -1.5));
    }
    let numerator = gamma((v + 1.0) / 2.0);
    let denominator = (v * std::f64::consts::PI).sqrt()
        * gamma(v / 2.0)
        * crt_pow(1.0 + x * x / v, (v + 1.0) / 2.0);
    Ok(numerator / denominator)
}

pub fn t_dist_kernel(
    x: f64,
    deg_freedom: f64,
    cumulative: bool,
) -> Result<f64, WorksheetErrorCode> {
    if cumulative {
        t_cdf(x, deg_freedom)
    } else {
        t_pdf(x, deg_freedom)
    }
}

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• T.DIST.RT is the right-tail complement: 1 − F(x; ν), computed directly rather than by subtraction, and therefore the accurate surface for small upper-tail probabilities.
• T.DIST.2T is the two-tail area P(|T| > x), defined only for x ≥ 0.
• T.INV is this function's inverse in the cumulative sense: T.INV(p, ν) is the x with T.DIST(x, ν, TRUE) = p. T.INV.2T inverts T.DIST.2T instead.
• TDIST is the legacy compatibility spelling, and it is not this function. TDIST(x, ν, tails) takes x ≥ 0 and returns a tail area — one-tailed for tails = 1, two-tailed for tails = 2 — so its modern counterparts are T.DIST.RT and T.DIST.2T, not T.DIST. T.DIST has no legacy predecessor at all; the left-tail CDF and the density were both new surfaces when the dotted names arrived. Anyone mechanically rewriting TDIST to T.DIST is changing the mathematics, not modernizing a name.
• NORM.S.DIST is the ν → ∞ limit; F.DIST is a relative, since T² ~ F(1, ν), which gives F.DIST.RT(x², 1, ν) = T.DIST.2T(x, ν) as an identity worth probing across the pair.

Named variants

No named variants are recorded yet.