{ "category": "Statistical functions", "display_name": "Z.TEST", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.Z.TEST", "implementation_state": { "answer_bank": null, "detail": "Everything else matches (7 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: 3 of 7 recorded answers differ in the last bits, worst 3 ULP", "workbook_corpus": { "cells": 7, "last_bit": 3, "matched": 4, "worst_ulp": 3 } }, "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#L348-L348" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/distributions::sample", "catalogue/distributions::z_test_of", "ported/confidence_test_family::z_test_kernel", "ported/excel_numeric::binary_with", "ported/excel_numeric::excel_x87_add", "ported/excel_numeric::excel_x87_sub", "ported/excel_numeric::excel_x87_mul", "ported/excel_numeric::excel_x87_div", "ported/excel_numeric::excel_sqrt_staged", "ported/excel_numeric/x87::mul", "ported/excel_numeric/x87::add", "ported/excel_numeric/x87::sub", "ported/excel_numeric/x87::div", "ported/normal_dist_common::stored_horner", "ported/normal_dist_common::erf_approx", "ported/normal_dist_common::erfc_upper", "ported/normal_log_family::flush_subnormal", "ported/normal_log_family::identified_std_normal_cdf", "ported/normal_log_family::norm_cdf", "ported/normal_log_family::norm_s_dist_kernel", "ported/phi_fn::phi_kernel", "ported/special_dist_family::erfc_kernel", "ported/special_dist_family::erfc_precise_kernel", "ported/variance_common::variance_from_values", "ported/variance_common::stdev_from_values" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/distributions.rs#L348-L348", "state": "close", "suite": null, "summary": "Close: 3 of 7 recorded answers differ in the last bits, worst 3 ULP" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.Z.TEST.json", "name": "Z.TEST", "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- **`ZTEST`** is the legacy compatibility spelling. Neither spelling appears in the Handbook's\n legacy/modern alias-pairing record, so **nothing in the Handbook's record bears on whether they\n publish the same bits.**\n- **`NORM.S.DIST`** is the function the documented formula calls, and therefore the surface whose\n accuracy `Z.TEST` inherits. This surface's module carries the open defect stream\n `BUG-FUNC-013`, whose title names a normal-distribution exact-value accuracy gap, and\n `BUG-FUNC-021`, whose title names a statistical numeric exactness drift. Both are cited by name\n only.\n- **`ERFC`** is the escape hatch. `1 − Φ(z) = ½·ERFC(z/sqrt 2)` exactly, and `ERFC` is a\n complementary surface computed directly rather than by subtraction — so\n `=0.5*ERFC((AVERAGE(a)-x)/(s/SQRT(n))/SQRT(2))` reproduces `Z.TEST` in the well-conditioned\n region and keeps working where `Z.TEST`'s documented composition has saturated to zero. Whether\n Excel's `ERFC` is itself accurate in the far tail is a separate question, on a separate page.\n- **[T.TEST](FUNC.T.TEST.md)** is the small-sample counterpart — and note the shape mismatch: it\n takes two samples, not a sample and a hypothesized mean, and it is direction-blind. There is no\n one-sample `T.TEST`. A one-sample t-test must be assembled from `AVERAGE`, `STDEV.S`, `COUNT`\n and [T.DIST.RT](FUNC.T.DIST.RT.md).\n- **`STANDARDIZE`** computes the `z` this function's formula forms internally.\n- **Confused with**: the Data Analysis ToolPak's \"z-Test: Two Sample for Means\", which is a\n different (two-sample) test on a different code path.\n\n\n", "how-to-implement": "\n### Numerical notes\n\n\n**The documented formula has a hard accuracy floor, and it is visible on the documentation page\nitself.** `1 − Φ(z)` is a subtraction from one. Once `Φ(z)` rounds to `1.0` in double precision —\nwhich happens beyond roughly eight standard errors — the difference is exactly zero, and every\nsmaller `p`-value collapses to zero with it. A z-test on a well-powered study routinely produces\nstatistics past that point; the whole scientific content of such a result is the *size* of the\ntiny `p`-value, and this composition discards it.\n\nThe fix is standard and old: compute the upper tail directly rather than as a complement. The\nidentity is exact,\n\n 1 − Φ(z) = ½ · erfc( z / sqrt 2 )\n\nand `erfc` exists precisely so that the small quantity is computed as itself. Cody's rational\napproximations for `erf`/`erfc`, the fdlibm implementations, and Boost.Math's `erfc` are the\nstandard sources, and the far-tail asymptotic\n`erfc(t) ~ exp(−t²)/(t·sqrt π) · (1 − 1/(2t²) + …)` is what carries the value once the\napproximation regions run out. A normal-tail routine that switches to the asymptotic keeps\nreturning meaningful values until `exp(−z²/2)` itself underflows, which is dozens of standard\nerrors out rather than eight.\n\nExcel's surface set does not offer a complementary normal CDF, which is why the composition is\nwritten the way it is. `ERFC` is the workaround, and it is the honest recommendation to a reader\nwho needs small `p`-values.\n\n**Secondary hazards**, all real but smaller:\n\n1. **The sample standard deviation.** With `sigma` omitted, the default path computes a variance,\n and the usual accumulation argument applies — never `Σx² − (Σx)²/n`; see\n `VAR.S` and Higham's §1.9. A data set with a large mean relative to its spread\n can lose most of the digits of `s` before the statistic is formed.\n2. **The mean difference.** `x̄ − x` is a subtraction of near-equal quantities exactly when the\n null hypothesis is nearly true, which is the interesting case.\n3. **Composition ordering.** `(x̄ − x)/(σ/sqrt n)` and `(x̄ − x)·sqrt(n)/σ` are the same real\n number and different floating-point numbers; the second avoids one division and one rounding.\n Which one Excel uses is unknown, and the documented formula shows only the first.\n\nThe accuracy of Excel's normal-distribution and hypothesis-test surfaces is a long-standing topic\nin the published literature — Morten Welinder's work on Gnumeric's statistical functions is the\nmost concrete account of the failure modes, and the assessments by Knüsel and by McCullough &\nWilson are the standing evaluations. The Handbook names them as the right reading and does not\nassert from them what any current build does.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, a probability in `(0, 1)`.\n\n- **`x̄ = x`** gives exactly `½`. Free and exact, and the cheapest diagnostic on the surface.\n- **Large positive `z`** is where the documented formula fails, and it fails hard. See Numerical\n notes: `1 − Φ(z)` computed by subtraction saturates at zero once `Φ(z)` rounds to 1, which\n happens beyond roughly eight standard errors. Every `p`-value smaller than that is published as\n zero, whatever the data says. This is a property of the documented composition, not a defect\n discovered by measurement.\n- **Large negative `z`** is the well-conditioned direction: the answer approaches 1 from below and\n `Φ(z)` carries it accurately.\n- **`sigma = 0`** makes the statistic infinite. Undocumented.\n- **Zero-variance `array` with `sigma` omitted** is the same situation with more data.\n- **Text, logicals and empty cells** in `array` follow the family's coercion policy; the engine's\n battery rejects a logical in the `array` position. Undocumented on Microsoft's page, which says\n nothing about the contents of `array` beyond that it must not be empty.\n- **`COUNT` semantics.** The documented `n` is `COUNT(array)`, which counts numbers only. So a\n range mixing numbers and text has an `n` that differs from its cell count, and the documented\n formula's `AVERAGE` and `STDEV` use the same convention. Consistent, but worth stating.\n\n\n\n### Errors\n\n\nAs documented on Microsoft's `Z.TEST` page:\n\n| Error | Documented condition |\n|---|---|\n| `#N/A` | `array` is empty. |\n\nThat is the entire documented error table — one row, for a function with a divisor that can be\nzero, an optional argument that can be negative, and a data argument whose admissible contents\nare never described. Undocumented and therefore open: `sigma ≤ 0`, `n = 1`, zero-variance data\nwith `sigma` omitted, and non-numeric contents of `array`.\n\nErrors in any argument propagate under the universal coercion rule. The Handbook has not verified\nany of this against Excel.\n\n\n", "sources": "- Microsoft, \"Z.TEST function\" —\n \n (syntax; `array`, `x` and the optional `sigma`; `#N/A` when `array` is empty; the two defining\n equations in terms of `NORM.S.DIST`, `AVERAGE`, `STDEV` and `COUNT`; the interpretation remark\n and its statement that a sample mean below `x` gives a result above 0.5; and the two-tailed\n recipe `2*MIN(Z.TEST(...), 1−Z.TEST(...))`). Retrieved for this page.\n- Handbook evidence record `EV-DIST-0012` — the sampled per-surface histogram that holds this\n surface's only per-surface count, with its own warnings about sampling, tiny denominators and\n an internally inconsistent drifts column.\n- Handbook evidence record `EV-DIST-0017` — the standing residual register publishing run totals\n over a fifteen-function family, with its warning that no total may be attributed to one member.\n- W. J. Cody's rational Chebyshev approximations for `erf`/`erfc`; fdlibm and Boost.Math `erfc` —\n the complementary-evaluation route that the documented composition forgoes.\n- M. Abramowitz and I. A. Stegun, *Handbook of Mathematical Functions*, chapter 7 (the error\n function and its asymptotic expansion) and chapter 26 (the normal probability function).\n- N. J. Higham, *Accuracy and Stability of Numerical Algorithms*, §1.9 — the sample-variance\n accumulation argument behind the offset-invariance probe.\n- M. Welinder's documentation of Gnumeric's statistical functions, and the Excel accuracy\n assessments of R. Knüsel and of B. D. McCullough and B. Wilson.\n- Handbook [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`Z.TEST(array, x, [sigma])` returns the **one-tailed probability value of a z-test**: the\nprobability of observing a sample mean at least as large as the one in `array`, if the underlying\npopulation mean were `x`.\n\nMicrosoft gives the definition as an explicit composition of other worksheet functions, which is\nunusual and useful:\n\n Z.TEST(array, x, sigma) = 1 − NORM.S.DIST( (AVERAGE(array) − x) / (sigma/sqrt(n)), TRUE )\n\n Z.TEST(array, x) = 1 − NORM.S.DIST( (AVERAGE(array) − x) / (STDEV(array)/sqrt(n)), TRUE )\n\nwith `n = COUNT(array)`. Writing the standardized statistic as\n\n z = ( x̄ − x ) / ( σ / sqrt(n) )\n\nthe function returns `1 − Φ(z) = P(Z > z)`, the upper tail of the standard normal.\n\nRange: `(0, 1)`, strictly. The value is exactly `½` when `x̄ = x`, decreases toward 0 as the\nsample mean rises above the hypothesized mean, and rises toward 1 as it falls below. Microsoft\nstates the direction explicitly: \"if `AVERAGE(array) < x`, `Z.TEST` will return a value greater\nthan 0.5.\"\n\nTwo structural facts distinguish this from every other test surface in Excel:\n\n1. **It is directional.** Unlike [T.TEST](FUNC.T.TEST.md), which takes the absolute value of its\n statistic and is blind to which mean is larger, `Z.TEST` returns an upper-tail probability that\n depends on the sign. Swapping the roles of the sample and the hypothesized mean changes the\n answer to its complement, not to itself. A two-tailed value therefore has to be built by the\n caller, and Microsoft supplies the recipe:\n `=2 * MIN(Z.TEST(array, x, sigma), 1 − Z.TEST(array, x, sigma))`.\n2. **The default is not the test the name implies.** When `sigma` is omitted, the documented\n formula substitutes the **sample** standard deviation while keeping the **normal** distribution\n for the tail. That combination is not a z-test and not a t-test; it is a z-test using an\n estimated σ, which is only asymptotically correct. For small `n` it understates the tail.\n Microsoft documents the substitution plainly; the statistical consequence is not commented on\n there, and a reader who wants the exact small-sample answer wants a one-sample t-test, which\n Excel does not offer directly.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Required |\n|---|---|---|\n| `array` | \"The array or range of data against which to test `x`.\" | Yes |\n| `x` | \"The value to test\" — the hypothesized population mean. | Yes |\n| `sigma` | \"The population (known) standard deviation.\" | No — defaults to the sample standard deviation |\n\nNote a small documentation staleness: the defining formula names `STDEV`, the legacy spelling,\ninside the page for a modern dotted-name function. `STDEV` and `STDEV.S` are documented\nequivalents, but the modern page's formula reaches for the compatibility name.\n\nNote a larger one: the remark defining what the function represents introduces a symbol `μ0`\n(\"when the underlying population mean is μ0\") that appears nowhere else on the page and is never\ntied to the argument `x`. Read strictly, the sentence defines the function in terms of an\nundefined quantity. The intended reading is obvious and this page states it — `μ0` is `x` — but\nthe Handbook records the defect rather than silently repairing it.\n\n\n" }, "signature": { "display": "Z.TEST(array, x, [sigma])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "x", "optional": false, "repeats": false }, { "description": null, "name": "sigma", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 2 }, "category": "Statistical functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "RefOnly", "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": "One-tailed probability of a z-test for a sample mean", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the one-tailed probability-value of a z-test", "microsoft_url": "https://support.microsoft.com/en-us/office/z-test-function-d633d5a3-2031-4614-a016-92180ad82bee" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "Z.TEST" }, { "locale": "bg-BG", "name": "Z.TEST" }, { "locale": "cs-CZ", "name": "Z.TEST" }, { "locale": "da-DK", "name": "Z.TEST" }, { "locale": "de-DE", "name": "Z.TEST" }, { "locale": "el-GR", "name": "Z.TEST" }, { "locale": "en-AU", "name": "Z.TEST" }, { "locale": "en-GB", "name": "Z.TEST" }, { "locale": "en-US", "name": "Z.TEST" }, { "locale": "es-ES", "name": "PRUEBA.Z.N" }, { "locale": "et-EE", "name": "Z.TEST" }, { "locale": "fi-FI", "name": "Z.TESTI" }, { "locale": "fr-FR", "name": "Z.TEST*" }, { "locale": "he-IL", "name": "Z.TEST" }, { "locale": "hr-HR", "name": "Z.TEST" }, { "locale": "hu-HU", "name": "Z.PRÓB" }, { "locale": "id-ID", "name": "Z.TEST" }, { "locale": "it-IT", "name": "Z.TEST" }, { "locale": "ja-JP", "name": "Z.TEST" }, { "locale": "ko-KR", "name": "Z.TEST" }, { "locale": "lt-LT", "name": "Z.TEST" }, { "locale": "lv-LV", "name": "Z.TEST" }, { "locale": "nb-NO", "name": "Z.TEST" }, { "locale": "nl-NL", "name": "Z.TEST" }, { "locale": "pl-PL", "name": "Z.TEST" }, { "locale": "pt-BR", "name": "Z.TEST" }, { "locale": "pt-PT", "name": "TESTE.Z" }, { "locale": "ro-RO", "name": "Z.TEST" }, { "locale": "ru-RU", "name": "Z.ТЕСТ" }, { "locale": "sk-SK", "name": "Z.TEST" }, { "locale": "sl-SI", "name": "Z.TEST" }, { "locale": "sr-Latn-RS", "name": "Z.TEST" }, { "locale": "sv-SE", "name": "Z.TEST" }, { "locale": "th-TH", "name": "Z.TEST" }, { "locale": "tr-TR", "name": "Z.TEST" }, { "locale": "uk-UA", "name": "Z.TEST" }, { "locale": "vi-VN", "name": "Z.TEST" }, { "locale": "zh-CN", "name": "Z.TEST" }, { "locale": "zh-HK", "name": "Z.TEST" }, { "locale": "zh-TW", "name": "Z.TEST" } ], "signature": { "display": "Z.TEST(array, x, [sigma])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "x", "optional": false, "repeats": false }, { "description": null, "name": "sigma", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "Z.TEST", "version_marker": null, "xlcall": { "code": "542", "symbol": "xlfZ_test" } }, "microsoft": "https://support.microsoft.com/en-us/office/z-test-function-d633d5a3-2031-4614-a016-92180ad82bee" }, "try_it": { "formula": "=Z.TEST({1;2;3},0.5)" }, "url": "https://handbook.dnacalc.com/functions/Z.TEST.html", "variants": [], "versions": [] }