{
  "category": "Statistical functions",
  "display_name": "FISHERINV",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.FISHERINV",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 3 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 3 recorded answers",
    "workbook_corpus": {
      "cells": 3,
      "matched": 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/statistics.rs#L409-L411",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/fisherinv_fn.rs#L3-L15"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/statistics.rs#L409-L411",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 3 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.FISHERINV.json",
  "name": "FISHERINV",
  "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\n- **[FISHER](FUNC.FISHER.md)** — the forward transform, artanh. Microsoft documents the round\n  trip. Note the asymmetry: `FISHER` guards its domain with `#NUM!`; `FISHERINV` has no domain\n  to guard and documents no `#NUM!` at all.\n- **`TANH`** — the Math-category spelling of the same mathematical function. Excel ships both.\n  They are documented to compute the same thing; whether they are the same computation, and\n  therefore agree in the last bit, is unestablished and would need evidence. Do not assume it.\n- **`CORREL` / `PEARSON`** — the correlation estimators whose transformed confidence bounds\n  are mapped back through this function.\n- **`NORM.S.INV`** — the quantile that sets those bounds on the transformed scale.\n- **`EXP`, `LN`** — the substrate. Any statement about `FISHERINV`'s last bits is ultimately a\n  statement about the exponential the platform provides.\n\n\n",
    "how-to-implement": "\n### Numerical notes\n\n    tanh(y) = expm1(2y) / (expm1(2y) + 2)\n\nremoves that cancellation entirely, which is why fdlibm's `tanh` is written that way. The\nsymmetric form (e^y − e^{−y})/(e^y + e^{−y}) costs two exponentials and still overflows.\n\n**The standard treatment** — fdlibm, Cephes, Boost — is a three-region split: return y (or the\nfirst series term) below a small threshold; use the `expm1` form in the middle; and return\n±1 with a token dependence on y beyond the saturation threshold, so the sign and the\nrounding mode behave. Argument reduction is not needed; tanh is its own reduction.\n\n**The round trip is a good test and a bad guarantee.** `FISHERINV(FISHER(x))` recovers x\nexactly only when the two roundings happen to cancel. Near x = 0 both functions are\napproximately the identity and the round trip is faithful; near |x| = 1 the forward map\nexpands and the backward map contracts, so the round trip is catastrophically unstable there —\na change of one ulp in the transformed value moves the recovered correlation by far more than\none ulp. That instability is a property of the mathematics, not a defect, and it is precisely\nwhy the transformation is useful: it spreads out the region where correlations are hard to\ndistinguish.\n\n**What a careful implementation does.** Use `expm1`; special-case the origin so the signed zero\nsurvives; pick the saturation threshold from the actual double spacing rather than a\nhard-coded constant; and never let an intermediate infinity reach a quotient.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns `Number`, always in [−1, 1] once floating point is accounted for.\n\n- **At the origin**, tanh(0) = 0 exactly.\n- **Small `y`**, including subnormals, returns `y` to within a rounding, because\n  tanh(y) = y + O(y³).\n- **Large positive `y`** saturates at exactly 1, and large negative `y` at exactly −1. This is\n  a floating-point fact, not a mathematical one: the true value never reaches the endpoint,\n  but the nearest double to it is the endpoint once |y| is beyond roughly 19.\n- **The negative side needs no guard**: e^{2y} underflows to 0 and the direct quotient gives\n  −1 without special handling. The asymmetry in the guard is a consequence of the asymmetry of\n  the formula, not a modelling choice.\n- **Array arguments** lift elementwise; the surface is classified as a unary numeric\n  scalar-or-array kernel.\n\n\n\n### Errors\n\n\nAs documented by Microsoft:\n\n| Error | Condition |\n|---|---|\n| `#VALUE!` | `y` is nonnumeric |\n\nThat is the entire documented error surface — one row. There is **no documented `#NUM!`\ncondition**, which is unusual for a Statistical-category function and is the clearest\nstructural contrast with `FISHER`. Error values arriving in the argument propagate under the\nshared coercion discipline.\n\nWhat the documentation does not say, and this page will not invent: what happens for an\nargument so large that the intermediate exponential overflows. The documented error table has\nno row for it, the mathematical answer is a value inside the range, and the observed answer in\nthe upstream record is saturation — but \"documented\" and \"observed once, upstream\" are\ndifferent warrants and the Handbook keeps them apart.\n\n\n",
    "sources": "- Abramowitz & Stegun, *Handbook of Mathematical Functions*, chapter 4 — the hyperbolic\n  tangent, its series and asymptotics.\n- fdlibm `s_tanh.c`; Cephes; Boost.Math — the `expm1` rearrangement and the three-region split.\n- Handbook, [The value universe](../model/01-value-universe.md) and\n  [Coercion and lifting](../model/02-coercion-and-lifting.md).\n- Handbook projections `data/functions/FUNC.FISHERINV.json` and\n  `data/presence/FUNC.FISHERINV.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 | 41 |\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.FISHERINV.json).",
    "what-it-does": "\n`FISHERINV(y)` is the hyperbolic tangent:\n\n    FISHERINV(y)  =  tanh(y)  =  (e^{2y} − 1) / (e^{2y} + 1)\n                              =  (e^{y} − e^{−y}) / (e^{y} + e^{−y})\n\n- **Domain:** the whole real line. This function has no interior domain restriction, which is\n  the structural difference between it and its partner.\n- **Range:** the open interval (−1, 1). The endpoints are approached but never attained\n  mathematically.\n- **Symmetry:** odd. tanh(−y) = −tanh(y), tanh(0) = 0 exactly.\n- **Derivative:** 1 − tanh²(y) = sech²(y); it is 1 at the origin and decays like 4e^{−2|y|}.\n- **Asymptotics:** tanh(y) → ±1 exponentially fast. By |y| ≈ 19 the difference from 1 is below\n  the double-precision spacing at 1, so every implementation saturates well before the argument\n  gets large.\n- **Series at the origin:** tanh(y) = y − y³/3 + 2y⁵/15 − … , so for small y the function is y\n  to first order.\n\nMicrosoft states the relationship rather than the formula: \"If y = FISHER(x), then\nFISHERINV(y) = x.\" That is the defining property, and it is exact as mathematics — tanh and\nartanh are genuine mutual inverses on (−1, 1) ↔ ℝ. It is *not* exact as floating point, and\nthe round trip is one of the more useful probes this pair offers; see **Numerical notes**.\n\nThe statistical use is the return leg of the Fisher z-transformation: build a confidence\ninterval on the transformed scale, where the sampling distribution is approximately normal,\nthen map the interval endpoints back to correlations with `FISHERINV`. Because tanh is\nmonotone, the mapped interval is still an interval, and because it is nonlinear, the mapped\ninterval is asymmetric about the point estimate — which is the whole point.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Default |\n|---|---|---|\n| `y` | The value to transform back. Required. | — |\n\n"
  },
  "signature": {
    "display": "FISHERINV(y)",
    "parameters": [
      {
        "description": null,
        "name": "y",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 1,
        "min": 1
      },
      "category": "Statistical functions",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "coercion_lift_profile": "UnaryNumericScalarOrArrayElementwise",
        "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": "Inverse Fisher transformation, tanh(y)",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the inverse of the Fisher transformation",
        "microsoft_url": "https://support.microsoft.com/en-us/office/fisherinv-function-62504b39-415a-4284-a285-19c8e82f86bb"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "FISHERINV"
        },
        {
          "locale": "bg-BG",
          "name": "FISHERINV"
        },
        {
          "locale": "cs-CZ",
          "name": "FISHERINV"
        },
        {
          "locale": "da-DK",
          "name": "FISHERINV"
        },
        {
          "locale": "de-DE",
          "name": "FISHERINV"
        },
        {
          "locale": "el-GR",
          "name": "FISHERINV"
        },
        {
          "locale": "en-AU",
          "name": "FISHERINV"
        },
        {
          "locale": "en-GB",
          "name": "FISHERINV"
        },
        {
          "locale": "en-US",
          "name": "FISHERINV"
        },
        {
          "locale": "es-ES",
          "name": "PRUEBA.FISHER.INV"
        },
        {
          "locale": "et-EE",
          "name": "FISHERINV"
        },
        {
          "locale": "fi-FI",
          "name": "FISHER.KÄÄNT"
        },
        {
          "locale": "fr-FR",
          "name": "FISHER.INVERSE*"
        },
        {
          "locale": "he-IL",
          "name": "FISHERINV"
        },
        {
          "locale": "hr-HR",
          "name": "FISHERINV"
        },
        {
          "locale": "hu-HU",
          "name": "INVERZ.FISHER"
        },
        {
          "locale": "id-ID",
          "name": "FISHERINV"
        },
        {
          "locale": "it-IT",
          "name": "FISHERINV"
        },
        {
          "locale": "ja-JP",
          "name": "FISHERINV"
        },
        {
          "locale": "ko-KR",
          "name": "FISHERINV"
        },
        {
          "locale": "lt-LT",
          "name": "FISHERINV"
        },
        {
          "locale": "lv-LV",
          "name": "FISHERINV"
        },
        {
          "locale": "nb-NO",
          "name": "FISHERINV"
        },
        {
          "locale": "nl-NL",
          "name": "FISHER.INV"
        },
        {
          "locale": "pl-PL",
          "name": "ROZKŁAD.FISHER.ODW"
        },
        {
          "locale": "pt-BR",
          "name": "FISHERINV"
        },
        {
          "locale": "pt-PT",
          "name": "FISHERINV"
        },
        {
          "locale": "ro-RO",
          "name": "FISHERINV"
        },
        {
          "locale": "ru-RU",
          "name": "ФИШЕРОБР"
        },
        {
          "locale": "sk-SK",
          "name": "FISHERINV"
        },
        {
          "locale": "sl-SI",
          "name": "FISHERINV"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "FISHERINV"
        },
        {
          "locale": "sv-SE",
          "name": "FISHERINV"
        },
        {
          "locale": "th-TH",
          "name": "FISHERINV"
        },
        {
          "locale": "tr-TR",
          "name": "FISHERTERS işlevi"
        },
        {
          "locale": "uk-UA",
          "name": "FISHERINV"
        },
        {
          "locale": "vi-VN",
          "name": "FISHERINV"
        },
        {
          "locale": "zh-CN",
          "name": "FISHERINV"
        },
        {
          "locale": "zh-HK",
          "name": "FISHERINV"
        },
        {
          "locale": "zh-TW",
          "name": "FISHERINV"
        }
      ],
      "signature": {
        "display": "FISHERINV(y)",
        "parameters": [
          {
            "description": null,
            "name": "y",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "FISHERINV",
      "version_marker": null,
      "xlcall": {
        "code": "284",
        "symbol": "xlfFisherinv"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/fisherinv-function-62504b39-415a-4284-a285-19c8e82f86bb"
  },
  "try_it": {
    "formula": "=FISHERINV(1)"
  },
  "url": "https://handbook.dnacalc.com/functions/FISHERINV.html",
  "variants": [],
  "versions": [
    {
      "behaviour": "41 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.FISHERINV.json"
      ]
    }
  ]
}