{ "category": "Statistical functions", "display_name": "RSQ", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.RSQ", "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#L368-L370", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/paired_stats_common.rs#L91-L93" ], "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#L368-L370", "state": "matches", "suite": null, "summary": "Matches all 7 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.RSQ.json", "name": "RSQ", "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- **[CORREL](FUNC.CORREL.md) and [PEARSON](FUNC.PEARSON.md)** return `r` itself; `RSQ` is `r^2`.\n `RSQ` therefore discards the *sign* of the relationship, which is usually the first thing a\n reader wants. `CORREL` and `PEARSON` are documented as the same quantity and are two separate\n published entries; whether they are one computation is a question for their own pages.\n- **[SLOPE](FUNC.SLOPE.md)** satisfies `RSQ(y,x) = SLOPE(y,x) * SLOPE(x,y)`. The two functions\n answer different questions about the same line — how steep, and how tight.\n- **[STEYX](FUNC.STEYX.md)** is the standard error of the regression, `sqrt(SSE/(n-2))`, and is\n the absolute-scale companion to `RSQ`'s relative one. `RSQ` near `1` with a large `STEYX` means\n the data spans a large range, not that the fit is tight in absolute terms.\n- **[LINEST](FUNC.LINEST.md)** returns `RSQ` as one cell of its extended statistics block, along\n with the standard errors and the `F` statistic that `RSQ` alone cannot supply.\n- **[INTERCEPT](FUNC.INTERCEPT.md), [TREND](FUNC.TREND.md),\n [FORECAST.LINEAR](FUNC.FORECAST.LINEAR.md)** round out the simple-regression set.\n- Readers confuse `RSQ` with the adjusted `R^2` reported by statistics packages, which penalises\n for the number of predictors. With one predictor the two differ by a factor in `n`; Excel\n publishes no adjusted form.\n\n\n", "how-to-implement": "\n### Numerical notes\n\nWritten out, the implemented route is\n\n r = ( Sxy/(n-1) ) / ( sqrt(Sxx/(n-1)) * sqrt(Syy/(n-1)) )\n RSQ = r * r\n\nagainst the direct route\n\n RSQ = (Sxy * Sxy) / (Sxx * Syy)\n\nThey are algebraically identical and numerically are not. The implemented route performs two\nsquare roots, a multiplication of the roots, a division and finally a squaring — five rounded\noperations where the direct route needs three, and two of them are the square roots that the\ndirect route does not need at all. The direct route is both faster and shorter in its error\nchain.\n\nThe visible consequence is at the top of the range. For exactly collinear data the true value is\n`1`, and the implemented route reaches it through `r`, which is itself a rounded quotient\nslightly below `1`; squaring a value slightly below `1` moves it further below. The reference\nengine's own witness assertions for this kernel record a returned value strictly less than `1` on\nperfectly collinear input, with the correlation and its square each landing a small number of\nunits in the last place short. The Handbook does not restate those figures — they belong to the\nevidence layer — but the *shape* of the result is a mathematical consequence and worth stating:\n**`RSQ` on collinear data is not exactly `1`, and should not be tested for equality with `1`.**\nThe direct closed form would not automatically fix this either; a genuinely exact answer at the\ntop of the range requires either a fused multiply-add formulation or an explicit clamp, and both\nare decisions to record rather than defaults.\n\nThe same argument applies to the bottom of the range with the opposite sign: `Sxy` near zero is a\ncancelling sum of mixed-sign terms, so `RSQ` near zero has poor *relative* accuracy. Its absolute\naccuracy stays good, which is usually what a reader of an `RSQ` near zero cares about.\n\n**The centred versus raw forms.** Everything said on [SLOPE](FUNC.SLOPE.md) about the two-pass\ncentred accumulation applies here and applies twice, because `RSQ` needs `Sxx` and `Syy` and\n`Sxy`. The one-pass form `n*sum(x^2) - sum(x)^2` loses digits in proportion to the square of the\nmean-to-spread ratio and can return a negative sum of squares; the centred form the reference\nengine uses does not. Chan, Golub and LeVeque (1983) is the analysis. **This page does not assert\nwhat Excel does internally** — only that the two are distinguishable by measurement on\nill-conditioned data, and that the measurement has not been made here.\n\n**Residual hazards in the good form.** The means and all three centred sums are accumulated by\nnaive left-to-right summation, so the error grows with `n` where compensated or pairwise\nsummation would bound it. `Sxx` and `Syy` have non-negative terms and are well-conditioned;\n`Sxy` does not and is not. The `Sxx == 0` and `Syy == 0` guards are exact comparisons, not\ntolerances, so data with real but tiny spread yields a number rather than a diagnostic.\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Number` in `[0, 1]`.\n\n- **Fewer than two complete pairs.** `#DIV/0!`.\n- **`Sxx = 0` or `Syy = 0`** — no spread in one of the variables. `#DIV/0!`. There is no\n defensible value: with `Syy = 0` there is nothing to explain, and with `Sxx = 0` there is\n nothing to explain it with. Note the guard is an exact comparison against zero, so data with a\n real but vanishing spread produces a number rather than an error.\n- **Perfect collinearity.** Mathematically `1`. In floating point the returned value can fall a\n few units in the last place *short* of `1`; see Numerical notes. Code that tests\n `RSQ(...) = 1` will fail on data that is exactly collinear.\n- **Unequal element counts.** `#N/A`, documented and implemented.\n- **Errors in either argument** propagate as themselves.\n\n\n", "sources": "- Microsoft, *RSQ function* —\n \n (signature and argument order, the stated equation, the ignore-text-and-logicals rule for\n arrays, and the documented `#N/A` and `#DIV/0!` conditions). Retrieval was blocked by the\n upstream host for this page; the documented behaviour above is stated as documented behaviour\n and should be re-checked against the page.\n- T. F. Chan, G. H. Golub and R. J. LeVeque, \"Algorithms for Computing the Sample Variance:\n Analysis and Recommendations\", *The American Statistician* 37(3), 1983, pp. 242–247.\n- F. J. Anscombe, \"Graphs in Statistical Analysis\", *The American Statistician* 27(1), 1973 —\n the quartet behind the warning that `RSQ` does not test model adequacy.\n- N. J. Higham, *Accuracy and Stability of Numerical Algorithms*, 2nd ed., chapter 4 — the\n summation error bounds behind the residual-hazards list.\n- Handbook `data/functions/FUNC.RSQ.json`, `data/presence/FUNC.RSQ.json`.\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`RSQ(known_y's, known_x's)` returns `r^2`, the **coefficient of determination** of the simple\nlinear regression of `y` on `x` — equivalently, the square of the Pearson product-moment\ncorrelation coefficient.\n\nFor pairs `(x_i, y_i)` with means `xbar`, `ybar` and centred sums\n\n Sxx = sum (x_i - xbar)^2 , Syy = sum (y_i - ybar)^2 , Sxy = sum (x_i - xbar)(y_i - ybar)\n\nthe correlation and its square are\n\n r = Sxy / sqrt( Sxx * Syy )\n RSQ = r^2 = Sxy^2 / ( Sxx * Syy )\n\nIts range is `[0, 1]`, and the two ends have plain meanings: `1` exactly when the points are\ncollinear (with nonzero spread in both coordinates), `0` exactly when `Sxy = 0`, meaning the\nleast-squares line is flat and knowing `x` tells you nothing about `y` in a linear sense.\n\nThree readings are worth carrying:\n\n1. **Variance explained.** `RSQ = 1 - SSE/SST`, where `SST = Syy` is the total sum of squares of\n `y` about its mean and `SSE = Syy - Sxy^2/Sxx` is what the fitted line leaves. `RSQ` is the\n fraction of the variation in `y` that the line accounts for. This is the reading that makes\n it a *goodness of fit* rather than a strength of association.\n2. **A product of two slopes.** `RSQ(y,x) = SLOPE(y,x) * SLOPE(x,y)`. The regression of `y` on\n `x` and the regression of `x` on `y` are different lines; `r^2` is exactly the amount by which\n their slopes fail to be reciprocals. This identity is why `RSQ` is **symmetric in its\n arguments** while [SLOPE](FUNC.SLOPE.md) is not — swapping `known_y's` and `known_x's` changes\n nothing about the answer.\n3. **A squared cosine.** `r` is the cosine of the angle between the centred `x` and `y` vectors,\n so `RSQ` is that cosine squared. This reading explains why the value is dimensionless and why\n it is invariant under any positive affine rescaling of either variable.\n\nTwo things `RSQ` is emphatically not. It is not a measure of whether a linear model is\n*appropriate* — Anscombe's quartet is four data sets with the same `RSQ` and four completely\ndifferent pictures. And it is not a measure of slope magnitude: a tiny slope measured precisely\ngives `RSQ` near `1`, and a steep slope measured noisily gives `RSQ` near `0`. Read `RSQ` next to\n[SLOPE](FUNC.SLOPE.md) and [STEYX](FUNC.STEYX.md), never alone.\n\n\n\n### Arguments\n\n\n| Argument | Meaning | Required |\n|---|---|---|\n| `known_y's` | The dependent values. First. | yes |\n| `known_x's` | The independent values. Second. | yes |\n\nThe `y` argument comes first, matching [SLOPE](FUNC.SLOPE.md), [INTERCEPT](FUNC.INTERCEPT.md) and\n[STEYX](FUNC.STEYX.md). Unlike those three, getting the order wrong here is harmless: `RSQ` is\nsymmetric, so the answer is the same either way. (It is not harmless in\n[CORREL](FUNC.CORREL.md)'s cousin functions when the sign of `r` matters, and `RSQ` discards the\nsign entirely — which is its principal weakness as a reported statistic.)\n\nBoth arguments are consumed by scanning, and pairing is **positional**, row-major over each\nargument; only the element counts must match, not the shapes.\n\n" }, "signature": { "display": "RSQ(known_ys, known_xs)", "parameters": [ { "description": null, "name": "known_ys", "optional": false, "repeats": false }, { "description": null, "name": "known_xs", "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": "Square of the Pearson correlation coefficient of two data sets", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the square of the Pearson product moment correlation coefficient", "microsoft_url": "https://support.microsoft.com/en-us/office/rsq-function-d7161715-250d-4a01-b80d-a8364f2be08f" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "RSQ" }, { "locale": "bg-BG", "name": "RSQ" }, { "locale": "cs-CZ", "name": "RSQ" }, { "locale": "da-DK", "name": "FORKLARINGSGRAD" }, { "locale": "de-DE", "name": "RSQ" }, { "locale": "el-GR", "name": "RSQ" }, { "locale": "en-AU", "name": "RSQ" }, { "locale": "en-GB", "name": "RSQ" }, { "locale": "en-US", "name": "RSQ" }, { "locale": "es-ES", "name": "COEFICIENTE.R2" }, { "locale": "et-EE", "name": "RSQ" }, { "locale": "fi-FI", "name": "PEARSON.NELIÖ" }, { "locale": "fr-FR", "name": "COEFFICIENT.DETERMINATION*" }, { "locale": "he-IL", "name": "RSQ" }, { "locale": "hr-HR", "name": "RSQ" }, { "locale": "hu-HU", "name": "RNÉGYZET" }, { "locale": "id-ID", "name": "RSQ" }, { "locale": "it-IT", "name": "RSQ" }, { "locale": "ja-JP", "name": "RSQ" }, { "locale": "ko-KR", "name": "RSQ" }, { "locale": "lt-LT", "name": "RSQ" }, { "locale": "lv-LV", "name": "RSQ" }, { "locale": "nb-NO", "name": "RKVADRAT" }, { "locale": "nl-NL", "name": "R.KWADRAAT" }, { "locale": "pl-PL", "name": "R.KWADRAT" }, { "locale": "pt-BR", "name": "RSQ" }, { "locale": "pt-PT", "name": "RQUAD" }, { "locale": "ro-RO", "name": "RSQ" }, { "locale": "ru-RU", "name": "КВПИРСОН" }, { "locale": "sk-SK", "name": "RSQ" }, { "locale": "sl-SI", "name": "RSQ" }, { "locale": "sr-Latn-RS", "name": "RSQ" }, { "locale": "sv-SE", "name": "RKV" }, { "locale": "th-TH", "name": "RSQ" }, { "locale": "tr-TR", "name": "RKARE işlevi" }, { "locale": "uk-UA", "name": "RSQ" }, { "locale": "vi-VN", "name": "RSQ" }, { "locale": "zh-CN", "name": "RSQ" }, { "locale": "zh-HK", "name": "RSQ" }, { "locale": "zh-TW", "name": "RSQ" } ], "signature": { "display": "RSQ(known_ys, known_xs)", "parameters": [ { "description": null, "name": "known_ys", "optional": false, "repeats": false }, { "description": null, "name": "known_xs", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "RSQ", "version_marker": null, "xlcall": { "code": "313", "symbol": "xlfRsq" } }, "microsoft": "https://support.microsoft.com/en-us/office/rsq-function-d7161715-250d-4a01-b80d-a8364f2be08f" }, "try_it": { "formula": "=RSQ({2;4;7},{1;2;3})" }, "url": "https://handbook.dnacalc.com/functions/RSQ.html", "variants": [], "versions": [] }