{
  "category": "Statistical functions",
  "display_name": "CORREL",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.CORREL",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 7 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 7 recorded answers",
    "workbook_corpus": {
      "cells": 7,
      "matched": 7
    }
  },
  "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#L362-L364"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "ported/paired_stats_common::means",
        "ported/paired_stats_common::correlation_from_pairs"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/statistics.rs#L362-L364",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 7 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CORREL.json",
  "name": "CORREL",
  "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- **[PEARSON](FUNC.PEARSON.md)** — documented as computing the same coefficient. Excel ships two\n  spellings of one statistic. Neither is deprecated, neither is in the Compatibility category, and\n  the Handbook has **not** checked whether they return identical bits; a shared definition is not a\n  shared implementation. Comparing them is one of the cheapest interesting probes in the whole\n  statistical lane.\n- **`COVARIANCE.P` / `COVARIANCE.S`** — the unnormalized\n  cousins. `CORREL` is covariance divided by the product of the standard deviations, and the\n  population/sample choice cancels out of that ratio.\n- **[FISHER](FUNC.FISHER.md)** — the variance-stabilizing transform `artanh(r)` used to build\n  confidence intervals for a correlation. It is the natural next function after this one, and its\n  own page is where the `r → ±1` sensitivity gets its proper treatment.\n- **Confused with**: causation, and with `SLOPE`. `r` is unitless and symmetric in its arguments;\n  `SLOPE` is neither.\n\n\n",
    "how-to-implement": "\n### Numerical notes\n\n\nCorrelation is the classic worked example in the numerical-statistics literature, and for a good\nreason: the textbook formula is a subtraction of two nearly equal large numbers.\n\n**The unstable form.** Expanding the centred sums gives\n\n    Σ(xᵢ−x̄)(yᵢ−ȳ) = Σxᵢyᵢ − (Σxᵢ)(Σyᵢ)/n\n\nwhich is attractive because it accumulates in one pass with five running sums. It is also\ncatastrophic when the data have a large mean relative to their spread: both terms grow like `n·x̄·ȳ`\nwhile their difference is only `n·cov`, so the relative error is amplified by roughly\n`|x̄ȳ| / |cov|`. On data like `(10⁸ + small)` the correlation can come out as `0`, as `2`, or as\n`#DIV/0!` from a negative sum of squares. Chan, Golub & LeVeque (1983) is the standard analysis of\nexactly this failure, and the Gnumeric/Welinder tradition of auditing spreadsheet statistics grew\nout of finding this formula in shipped products.\n\n**Overflow.** With the centred two-pass form, `Σ(xᵢ−x̄)²` can still overflow for data near the\ndouble-precision ceiling. Scaling by the maximum absolute deviation before accumulating — the same\ntrick used in a careful `hypot` — is the standard defence and costs one extra pass.\n\n**Range guarantee.** Mathematically `|r| ≤ 1`; numerically, the ratio of independently rounded\nquantities is not guaranteed to satisfy it. An implementation that intends to promise the bound has\nto clamp explicitly, and clamping is a decision to record rather than a neutral cleanup: it changes\nwhat `ACOS(CORREL(...))` does at the boundary.\n\nNone of this is a claim about how Excel computes `CORREL`. It is the map of where the errors live\nfor anyone measuring it.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns `Number` in `[−1, 1]`.\n\nDocumented behaviour:\n\n- **Different numbers of data points → `#N/A`.** Not `#VALUE!`. This is the length check, and it is\n  performed on the *raw* extents, before the ignore-rule has removed anything.\n- **Either array empty, or a standard deviation of zero → `#DIV/0!`.** A constant column is not a\n  correlation of zero; it is an error.\n- Text, logicals and blanks inside the ranges are ignored; zeros are included.\n\nBehaviour the documentation does not settle:\n\nErrors in a scanned cell propagate: an error value inside either range becomes the result, which is\nconsistent with the general rule that coercion never silently discards a worksheet error\n([chapter 02](../model/02-coercion-and-lifting.md)).\n\n\n",
    "sources": "- Chan, Golub & LeVeque, \"Algorithms for Computing the Sample Variance\", *The American\n  Statistician* 37 (1983) — the error analysis of naive versus two-pass versus updating formulas.\n- Welford, \"Note on a Method for Calculating Corrected Sums of Squares and Products\",\n  *Technometrics* 4 (1962) — the stable updating recurrence.\n- Handbook call-model chapters [01 The value universe](../model/01-value-universe.md) and\n  [02 Coercion and lifting](../model/02-coercion-and-lifting.md) — the direct-argument versus\n  range-scan distinction that governs the ignore rule.\n- Handbook projections `data/functions/FUNC.CORREL.json`, `data/presence/FUNC.CORREL.json`.\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`CORREL(array1, array2)` returns the **Pearson product-moment correlation coefficient** of two\npaired data sets.\n\nFor pairs `(x₁,y₁), …, (xₙ,yₙ)` with means `x̄` and `ȳ`,\n\n    r  =  Σ (xᵢ − x̄)(yᵢ − ȳ)  /  √( Σ (xᵢ − x̄)² · Σ (yᵢ − ȳ)² )\n\nequivalently `r = cov(x,y) / (σ_x σ_y)`, and equivalently again the cosine of the angle between the\ntwo mean-centred data vectors. Microsoft's page states the same formula with `x̄` and `ȳ` given as\n`AVERAGE(array1)` and `AVERAGE(array2)`.\n\nNote that the `n` versus `n − 1` question — population or sample divisor — **does not arise**. The\nsame divisor appears in the numerator and in both factors of the denominator and cancels\nidentically. `CORREL` is therefore the one member of this cluster with no population/sample split:\nthere is no `CORREL.P` and there could not be one.\n\nRange and interpretation. By Cauchy–Schwarz, `r ∈ [−1, 1]` exactly, with `|r| = 1` if and only if\nthe points lie on a straight line. `r = +1` is a perfectly increasing line, `r = −1` a perfectly\ndecreasing one, `r = 0` no *linear* association. The last qualifier is the one that costs people\nmoney: `r` measures linear association only, and a perfect parabola through symmetric `x` values has\n`r = 0`.\n\nInvariance. `r` is unchanged by any increasing affine transformation of either variable —\n`r(ax+b, cy+d) = r(x,y)` for `a, c > 0` — and flips sign when exactly one of `a`, `c` is negative.\nThis scale invariance is what distinguishes `r` from `COVARIANCE.P`, whose value carries the units\nof `x` times the units of `y` and is therefore uncomparable across data sets.\n\nDegenerate cases. `r` is undefined when either variable has zero spread — the denominator vanishes\nbecause every point of that variable sits on its own mean — and undefined when fewer than two pairs\nsurvive. Both surface as errors rather than as values; see below.\n\n\n\n### Arguments\n\n| Argument | Meaning (as documented) |\n|---|---|\n| `array1` | \"A range of cell values\" |\n| `array2` | \"A second range of cell values\" |\n\nThe documented filtering rule is the important one: **text, logical values and empty cells inside\nan array or reference argument are ignored, and cells containing zero are included.** This is a\nrange-scan policy, not a coercion policy — the text `\"3\"` in a cell does not become the number `3`\nhere, it is skipped. See [Coercion and lifting](../model/02-coercion-and-lifting.md) for why the\nsame value behaves differently as a direct argument than as a scanned cell.\n\n\n"
  },
  "signature": {
    "display": "CORREL(array1, array2)",
    "parameters": [
      {
        "description": null,
        "name": "array1",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "array2",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 2,
        "min": 2
      },
      "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": "Pearson correlation coefficient of two data sets",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the correlation coefficient between two data sets",
        "microsoft_url": "https://support.microsoft.com/en-us/office/correl-function-995dcef7-0c0a-4bed-a3fb-239d7b68ca92"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "CORREL"
        },
        {
          "locale": "bg-BG",
          "name": "CORREL"
        },
        {
          "locale": "cs-CZ",
          "name": "CORREL"
        },
        {
          "locale": "da-DK",
          "name": "KORRELATION"
        },
        {
          "locale": "de-DE",
          "name": "CORREL"
        },
        {
          "locale": "el-GR",
          "name": "CORREL"
        },
        {
          "locale": "en-AU",
          "name": "CORREL"
        },
        {
          "locale": "en-GB",
          "name": "CORREL"
        },
        {
          "locale": "en-US",
          "name": "CORREL"
        },
        {
          "locale": "es-ES",
          "name": "COEF.DE.CORREL"
        },
        {
          "locale": "et-EE",
          "name": "CORREL"
        },
        {
          "locale": "fi-FI",
          "name": "KORRELAATIO"
        },
        {
          "locale": "fr-FR",
          "name": "COEFFICIENT.CORRELATION*"
        },
        {
          "locale": "he-IL",
          "name": "CORREL"
        },
        {
          "locale": "hr-HR",
          "name": "CORREL"
        },
        {
          "locale": "hu-HU",
          "name": "KORREL"
        },
        {
          "locale": "id-ID",
          "name": "CORREL"
        },
        {
          "locale": "it-IT",
          "name": "CORREL"
        },
        {
          "locale": "ja-JP",
          "name": "CORREL"
        },
        {
          "locale": "ko-KR",
          "name": "CORREL"
        },
        {
          "locale": "lt-LT",
          "name": "CORREL"
        },
        {
          "locale": "lv-LV",
          "name": "CORREL"
        },
        {
          "locale": "nb-NO",
          "name": "CORREL"
        },
        {
          "locale": "nl-NL",
          "name": "CORRELATIE"
        },
        {
          "locale": "pl-PL",
          "name": "WSP.KORELACJI"
        },
        {
          "locale": "pt-BR",
          "name": "CORREL"
        },
        {
          "locale": "pt-PT",
          "name": "CORREL"
        },
        {
          "locale": "ro-RO",
          "name": "CORREL"
        },
        {
          "locale": "ru-RU",
          "name": "КОРРЕЛ"
        },
        {
          "locale": "sk-SK",
          "name": "CORREL"
        },
        {
          "locale": "sl-SI",
          "name": "CORREL"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "CORREL"
        },
        {
          "locale": "sv-SE",
          "name": "KORREL"
        },
        {
          "locale": "th-TH",
          "name": "CORREL"
        },
        {
          "locale": "tr-TR",
          "name": "KORELASYON Denklemi"
        },
        {
          "locale": "uk-UA",
          "name": "CORREL"
        },
        {
          "locale": "vi-VN",
          "name": "CORREL"
        },
        {
          "locale": "zh-CN",
          "name": "CORREL"
        },
        {
          "locale": "zh-HK",
          "name": "CORREL"
        },
        {
          "locale": "zh-TW",
          "name": "CORREL"
        }
      ],
      "signature": {
        "display": "CORREL(array1, array2)",
        "parameters": [
          {
            "description": null,
            "name": "array1",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "array2",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "CORREL",
      "version_marker": null,
      "xlcall": {
        "code": "307",
        "symbol": "xlfCorrel"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/correl-function-995dcef7-0c0a-4bed-a3fb-239d7b68ca92"
  },
  "try_it": {
    "formula": "=CORREL({1;2;3},{1;2;3})"
  },
  "url": "https://handbook.dnacalc.com/functions/CORREL.html",
  "variants": [],
  "versions": []
}