{ "category": "Statistical functions", "display_name": "CONFIDENCE.T", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CONFIDENCE.T", "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 2 ULP", "workbook_corpus": { "cells": 5, "last_bit": 1, "matched": 4, "worst_ulp": 2 } }, "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#L105-L108", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/confidence_test_family.rs#L5-L18" ], "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#L105-L108", "state": "close", "suite": null, "summary": "Close: 1 of 5 recorded answers differ in the last bits, worst 2 ULP" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CONFIDENCE.T.json", "name": "CONFIDENCE.T", "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- **[CONFIDENCE.NORM](FUNC.CONFIDENCE.NORM.md)** — the known-`σ` sibling. Same shape, `z_{1−α/2}`\n in place of `t_{1−α/2,n−1}`. Not a legacy/modern pair: both are current, and both were introduced\n in Excel 2010 alongside the legacy `CONFIDENCE`.\n- **`CONFIDENCE`** — the pre-2010 spelling, which corresponds to the *normal*\n function. There is no legacy spelling of `CONFIDENCE.T`; it is new function surface, not a\n rename. This matters when reading migration tables that treat every dotted name as a rename.\n- **[STDEV.S](FUNC.STDEV.S.md)** — the usual supplier of `standard_dev`. Feeding `STDEV.P` here\n instead is a common and silent error: it estimates with the wrong divisor and then pairs it with\n a t quantile that assumes the other one.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\nThree sources of error stack in this function, and only the first is specific to it.\n\n3. **The composition.** `t · s / √n` — one multiplication, one square root, one division, and a\n choice of association that changes the last bit.\n\nStandard references for the routines involved: Abramowitz & Stegun chapter 26.7 (Student's t, its\nincomplete-beta form, and the percentage-point expansions); Didonato & Morris, ACM TOMS 708\n(`BRATIO`); Cephes `incbet`/`incbi`; Boost's `students_t` quantile; Numerical Recipes' `betai` and\n`betacf` (readable, and explicitly less accurate than the TOMS routine).\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number` — a positive half-width.\n\nDocumented boundary behaviour, from Microsoft's page:\n\n- Any nonnumeric argument → `#VALUE!`.\n- `alpha ≤ 0` or `alpha ≥ 1` → `#NUM!`.\n- `standard_dev ≤ 0` → `#NUM!`.\n- `size` non-integer → truncated.\n- **`size = 1` → `#DIV/0!`.** This is the one documented error condition with no counterpart on\n `CONFIDENCE.NORM`, and it is mathematically the right shape: at `n = 1` there are zero degrees of\n freedom and the t quantile does not exist.\n\nWhat the documentation does **not** say: what `size < 1` does. The normal sibling documents\n`size < 1 → #NUM!`; this page documents only the `size = 1` case. So `CONFIDENCE.T(0.05, 1, 0)` is\nundocumented behaviour.\n\n\n### Errors\n\n\nAs documented on Microsoft's `CONFIDENCE.T` page:\n\n| Error | Condition |\n|---|---|\n| `#VALUE!` | Any argument is nonnumeric |\n| `#NUM!` | `alpha ≤ 0` or `alpha ≥ 1` |\n| `#NUM!` | `standard_dev ≤ 0` |\n| `#DIV/0!` | `size` equals 1 |\n\n\n### A documentation defect on the Microsoft page\n\n\nMicrosoft's `CONFIDENCE.T` page describes `standard_dev` as \"The population standard deviation for\nthe data range and is assumed to be known\" — word for word the sentence on the `CONFIDENCE.NORM`\npage.\n\nFor `CONFIDENCE.T` that sentence is self-contradicting. If the population standard deviation were\nknown, the correct interval would use the normal quantile and there would be no reason for this\nfunction to exist; the t-distribution enters *precisely because* `s` is a sample estimate with its\nown sampling variability. The wording appears to have been copied from the normal page when the\n2010 dotted pair was created.\n\nThe Handbook records this as a documentation defect, not as a behaviour claim: nothing about what\nthe function *computes* is in doubt, only what the page says the argument is. Readers deciding\nbetween the two functions should use the operative rule — known `σ` takes `CONFIDENCE.NORM`,\nsample `s` takes `CONFIDENCE.T` — and not the argument prose.\n\n\n", "sources": "- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 26.7 — Student's\n t-distribution, its incomplete-beta representation, and percentage points.\n- Didonato & Morris, \"Algorithm 708: Significant Digit Computation of the Incomplete Beta Function\n Ratio\", ACM TOMS 18 (1992) — the `BRATIO` routine underlying t and F evaluation.\n- Handbook evidence records `EV-DIST-0012` and `EV-DIST-0017` (`content/evidence/records/`); read\n their reader warnings, which bound what may be attributed to this surface.\n- Handbook call-model chapter [02 Coercion and lifting](../model/02-coercion-and-lifting.md).\n- Handbook projections `data/functions/FUNC.CONFIDENCE.T.json` and\n `data/presence/FUNC.CONFIDENCE.T.json`.\n\n\n", "version-differences": "The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.\n\n| Excel 16.0 build | Platform and CPU | Captured inputs |\n|---|---|---:|\n| 19929 | Windows, bitness not recorded, CPU not recorded | 87 |\n\nThe record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.CONFIDENCE.T.json).", "what-it-does": "\n`CONFIDENCE.T(alpha, standard_dev, size)` returns the **half-width** of a two-sided confidence\ninterval for a population mean when the standard deviation was *estimated from the sample* rather\nthan known in advance.\n\nWriting `t_{q,ν}` for the `q`-quantile of Student's t-distribution with `ν` degrees of freedom,\n\n CONFIDENCE.T(α, s, n) = t_{1 − α/2, n − 1} · s / √n\n\nand the interval is `x̄ ± CONFIDENCE.T(α, s, n)`.\n\nThe degrees-of-freedom count is `n − 1`, not `n`: one degree of freedom was spent estimating the\nmean before the spread was measured. That single subtraction is the whole difference between this\nfunction and [CONFIDENCE.NORM](FUNC.CONFIDENCE.NORM.md) in structure, and it is the reason the\nsmallest usable sample here is `n = 2` rather than `n = 1`.\n\nThe t-distribution itself. Its density on `ν > 0` degrees of freedom is\n\n f(t; ν) = Γ((ν+1)/2) / ( √(νπ) · Γ(ν/2) ) · (1 + t²/ν)^(−(ν+1)/2)\n\nsymmetric about zero, with tails heavier than the normal's — `f(t; ν) ~ C·|t|^(−(ν+1))`, so only\nmoments below order `ν` exist, and the variance `ν/(ν−2)` exists only for `ν > 2`. As `ν → ∞` the\ndensity converges to the standard normal's, and correspondingly `t_{q,ν} → z_q` from above. Because\n`t_{q,ν} > z_q` for every finite `ν` and every `q > 1/2`, **`CONFIDENCE.T` is always at least as\nwide as `CONFIDENCE.NORM` on the same three arguments**, dramatically so for small `n`.\n\nThe CDF is an incomplete beta function. With `I_x(a,b)` the regularized incomplete beta,\n\n P(T ≤ t; ν) = 1 − ½ · I_{ν/(ν+t²)}(ν/2, ½) for t ≥ 0\n\nDomain and range: `α ∈ (0,1)`, `s > 0`, `n ≥ 2`, and the value is positive throughout. It diverges\nas `α → 0⁺`, tends to `0` as `α → 1⁻`, is linear in `s`, and falls roughly like `n^(−1/2)` with a\nsecond, faster contribution from the shrinking t quantile as the degrees of freedom grow.\n\n\n\n### Arguments\n\n| Argument | Meaning | Admissible values |\n|---|---|---|\n| `alpha` | The significance level; the confidence level is `100·(1 − alpha)%` | `0 < alpha < 1` |\n| `standard_dev` | The standard deviation of the data (see the defect note below) | `> 0` |\n| `size` | The sample size; truncated if not an integer | `≥ 2` in practice — see the error discussion |\n\nThe misunderstood positions are the same two as on the normal sibling, plus one specific to this\nfunction:\n\n- `alpha` is the significance level, not the confidence level. `0.05` means 95%.\n- `size` is documented as truncated when non-integer.\n- The **degrees of freedom are derived, not supplied**. A reader who has already computed\n `n − 1` elsewhere and passes it here gets an interval one degree of freedom too wide.\n\nAll three are numeric slots under ordinary to-number coercion\n([chapter 02](../model/02-coercion-and-lifting.md)).\n\n\n" }, "signature": { "display": "CONFIDENCE.T(alpha, standard_dev, size)", "parameters": [ { "description": null, "name": "alpha", "optional": false, "repeats": false }, { "description": null, "name": "standard_dev", "optional": false, "repeats": false }, { "description": null, "name": "size", "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": "None", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Half-width of a confidence interval for a mean, from Student's t distribution", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the confidence interval for a population mean, using a Student's t distribution", "microsoft_url": "https://support.microsoft.com/en-us/office/confidence-t-function-e8eca395-6c3a-4ba9-9003-79ccc61d3c53" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CONFIDENCE.T" }, { "locale": "bg-BG", "name": "CONFIDENCE.T" }, { "locale": "cs-CZ", "name": "CONFIDENCE.T" }, { "locale": "da-DK", "name": "KONFIDENST" }, { "locale": "de-DE", "name": "CONFIDENCE.T" }, { "locale": "el-GR", "name": "CONFIDENCE.T" }, { "locale": "en-AU", "name": "CONFIDENCE.T" }, { "locale": "en-GB", "name": "CONFIDENCE.T" }, { "locale": "en-US", "name": "CONFIDENCE.T" }, { "locale": "es-ES", "name": "INTERVALO.CONFIANZA.T" }, { "locale": "et-EE", "name": "CONFIDENCE.T" }, { "locale": "fi-FI", "name": "LUOTTAMUSVÄLI.T" }, { "locale": "fr-FR", "name": "INTERVALLE.CONFIANCE.STUDENT*" }, { "locale": "he-IL", "name": "CONFIDENCE.T" }, { "locale": "hr-HR", "name": "CONFIDENCE.T" }, { "locale": "hu-HU", "name": "MEGBÍZHATÓSÁG.T" }, { "locale": "id-ID", "name": "CONFIDENCE.T" }, { "locale": "it-IT", "name": "CONFIDENCE.T" }, { "locale": "ja-JP", "name": "CONFIDENCE.T" }, { "locale": "ko-KR", "name": "CONFIDENCE.T" }, { "locale": "lt-LT", "name": "CONFIDENCE.T" }, { "locale": "lv-LV", "name": "CONFIDENCE.T" }, { "locale": "nb-NO", "name": "KONFIDENS.T" }, { "locale": "nl-NL", "name": "VERTROUWELIJKHEID.T" }, { "locale": "pl-PL", "name": "UFNOŚĆ.T" }, { "locale": "pt-BR", "name": "CONFIANÇA.T" }, { "locale": "pt-PT", "name": "INT.CONFIANÇA.T" }, { "locale": "ro-RO", "name": "CONFIDENCE.T" }, { "locale": "ru-RU", "name": "ДОВЕРИТ.СТЬЮДЕНТ" }, { "locale": "sk-SK", "name": "CONFIDENCE.T" }, { "locale": "sl-SI", "name": "CONFIDENCE.T" }, { "locale": "sr-Latn-RS", "name": "CONFIDENCE.T" }, { "locale": "sv-SE", "name": "KONFIDENCE.T" }, { "locale": "th-TH", "name": "CONFIDENCE.T" }, { "locale": "tr-TR", "name": "GÜVENİLİRLİK.T" }, { "locale": "uk-UA", "name": "CONFIDENCE.T" }, { "locale": "vi-VN", "name": "CONFIDENCE.T" }, { "locale": "zh-CN", "name": "CONFIDENCE.T" }, { "locale": "zh-HK", "name": "CONFIDENCE.T" }, { "locale": "zh-TW", "name": "CONFIDENCE.T" } ], "signature": { "display": "CONFIDENCE.T(alpha, standard_dev, size)", "parameters": [ { "description": null, "name": "alpha", "optional": false, "repeats": false }, { "description": null, "name": "standard_dev", "optional": false, "repeats": false }, { "description": null, "name": "size", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "CONFIDENCE.T", "version_marker": null, "xlcall": { "code": "489", "symbol": "xlfConfidence_t" } }, "microsoft": "https://support.microsoft.com/en-us/office/confidence-t-function-e8eca395-6c3a-4ba9-9003-79ccc61d3c53" }, "try_it": { "formula": "=CONFIDENCE.T(0.05,2,20)" }, "url": "https://handbook.dnacalc.com/functions/CONFIDENCE.T.html", "variants": [], "versions": [ { "behaviour": "87 captured inputs are indexed for this environment. Capture dates are not recorded. This is a reading count, not a comparison with another build.", "excel_build": "16.0 build 19929", "platform": "Windows, bitness not recorded, CPU not recorded", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.CONFIDENCE.T.json" ] } ] }