{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "`~scipy.stats.ConstantInputWarning`", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Raised if an input is a constant array. The correlation coefficient is not defined in this case, so " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.nan" }, { "__type": "Text", "__tag": 4046, "value": " is returned." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " is not 0, 1 or None, or if the number of dimensions of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is greater than 2, or if " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " is None and the number of dimensions of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is less than 2." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "res", "annotation": "SignificanceResult", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An object containing attributes:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "statistic" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Spearman correlation matrix or correlation coefficient (if only 2 variables are given as parameters). Correlation matrix is square with length equal to total number of variables (columns or rows) in " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " combined." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "pvalue" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The p-value for a hypothesis test whose null hypothesis is that two samples have no ordinal correlation. See " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " above for alternative hypotheses. " }, { "__type": "InlineRole", "__tag": 4003, "value": "pvalue", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " has the same shape as " }, { "__type": "InlineRole", "__tag": 4003, "value": "statistic", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate a Spearman correlation coefficient with associated p-value." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "a, b", "annotation": "1D or 2D array_like, b is optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One or two 1-D or 2-D arrays containing multiple variables and observations. When these are 1-D, each represents a vector of observations of a single variable. For the behavior in the 2-D case, see under " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis" }, { "__type": "Text", "__tag": 4046, "value": ", below. Both arrays need to have the same length in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis" }, { "__type": "Text", "__tag": 4046, "value": " dimension." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int or None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If axis=0 (default), then each column represents a variable, with observations in the rows. If axis=1, the relationship is transposed: each row represents a variable, while the columns contain observations. If axis=None, then both arrays will be raveled." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nan_policy", "annotation": "{'propagate', 'raise', 'omit'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines how to handle when input contains nan. The following options are available (default is 'propagate'):" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'propagate': returns nan" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'raise': throws an error" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'omit': performs the calculations ignoring nan values" } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "alternative", "annotation": "{'two-sided', 'less', 'greater'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines the alternative hypothesis. Default is 'two-sided'. The following options are available:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'two-sided': the correlation is nonzero" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'less': the correlation is negative (less than zero)" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'greater': the correlation is positive (greater than zero)" } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.7.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Spearman rank-order correlation coefficient is a nonparametric measure of the monotonicity of the relationship between two datasets. Like other correlation coefficients, this one varies between -1 and +1 with 0 implying no correlation. Correlations of -1 or +1 imply an exact monotonic relationship. Positive correlations imply that as x increases, so does y. Negative correlations imply that as x increases, y decreases." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The p-value roughly indicates the probability of an uncorrelated system producing datasets that have a Spearman correlation at least as extreme as the one computed from these datasets. Although calculation of the p-value does not make strong assumptions about the distributions underlying the samples, it is only accurate for very large samples (>500 observations). For smaller sample sizes, consider a permutation test (see Examples section below)." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "build-install/usr/lib/python3.14/site-packages/scipy/stats/_stats_py.py", "item_line": 5226, "item_type": "function", "aliases": [ "scipy.stats.spearmanr" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\nres = stats.spearmanr([1, 2, 3, 4, 5], [5, 6, 7, 8, 7])\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure", "out": "np.float64(0.08858700531354384)\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng()\nx2n = rng.standard_normal((100, 2))\ny2n = rng.standard_normal((100, 2))\nres = stats.spearmanr(x2n)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic, res.pvalue\n", "execution_status": "failure", "out": "(np.float64(-0.000504050405040504), np.float64(0.9960288396182977))\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanr(x2n[:, 0], x2n[:, 1])\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic, res.pvalue\n", "execution_status": "failure", "out": "(np.float64(-0.000504050405040504), np.float64(0.9960288396182977))\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanr(x2n, y2n)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure", "out": "array([[0. , 0.99603, 0.51011, 0.2328 ],\n [0.99603, 0. , 0.76119, 0.42432],\n [0.51011, 0.76119, 0. , 0.32015],\n [0.2328 , 0.42432, 0.32015, 0. ]])\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanr(x2n.T, y2n.T, axis=1)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\n", "execution_status": "failure", "out": "array([[ 1. , -0.0005 , 0.06663, 0.1204 ],\n [-0.0005 , 1. , 0.03077, -0.08078],\n [ 0.06663, 0.03077, 1. , -0.10043],\n [ 0.1204 , -0.08078, -0.10043, 1. ]])\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanr(x2n, y2n, axis=None)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic, res.pvalue\n", "execution_status": "failure", "out": "(np.float64(-0.009339233480837022), np.float64(0.895576195191417))\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanr(x2n.ravel(), y2n.ravel())\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic, res.pvalue\n", "execution_status": "failure", "out": "(np.float64(-0.009339233480837022), np.float64(0.895576195191417))\n" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng()\nxint = rng.integers(10, size=(100, 2))\nres = stats.spearmanr(xint)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic, res.pvalue\n", "execution_status": "failure", "out": "(np.float64(-0.08692352519613988), np.float64(0.3898243103792412))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nFor small samples, consider performing a permutation test instead of\nrelying on the asymptotic p-value. Note that to calculate the null\ndistribution of the statistic (for all possibly pairings between\nobservations in sample ``x`` and ``y``), only one of the two inputs needs\nto be permuted.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = [1.76405235, 0.40015721, 0.97873798,\n2.2408932, 1.86755799, -0.97727788]\ny = [2.71414076, 0.2488, 0.87551913,\n2.6514917, 2.01160156, 0.47699563]\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "def statistic(x): # permute only `x`\n return stats.spearmanr(x, y).statistic\nres_exact = stats.permutation_test((x,), statistic,\n permutation_type='pairings')\nres_asymptotic = stats.spearmanr(x, y)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res_exact.pvalue, res_asymptotic.pvalue # asymptotic pvalue is too low\n", "execution_status": "failure", "out": "(np.float64(0.10277777777777777), np.float64(0.07239650145772594))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nFor a more detailed example, see :ref:`hypothesis_spearmanr`." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "hypothesis_spearmanr", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "hypothesis_spearmanr" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extended example" } ] } ], "type": "ref" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "nan_policy", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "propagate" }, { "__type": "SigParam", "__tag": 4030, "name": "alternative", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "two-sided" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "spearmanr" }, "references": [ ".. [1] Zwillinger, D. and Kokoska, S. (2000). CRC Standard", " Probability and Statistics Tables and Formulae. Chapman & Hall: New", " York. 2000.", " Section 14.7", ".. [2] Kendall, M. G. and Stuart, A. (1973).", " The Advanced Theory of Statistics, Volume 2: Inference and Relationship.", " Griffin. 1973.", " Section 31.18" ], "qa": "scipy.stats._stats_py:spearmanr", "arbitrary": [], "local_refs": [ "a", "alternative", "axis", "b", "nan_policy", "res" ] }