{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "spearmanrho", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:spearmanrho" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " was created to make improvements to SciPy's implementation of the Spearman correlation test without making backward-incompatible changes to " }, { "__type": "InlineRole", "__tag": 4003, "value": "spearmanr", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". Advantages of " }, { "__type": "CrossRef", "__tag": 4002, "value": "spearmanrho", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:spearmanrho" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " over " }, { "__type": "InlineRole", "__tag": 4003, "value": "spearmanr", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " include:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "spearmanrho", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:spearmanrho" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " follows standard array broadcasting rules." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "spearmanrho", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:spearmanrho" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is compatible with some non-NumPy arrays." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "spearmanrho", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:spearmanrho" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " can compute exact p-values, even in the presence of ties, when an appropriate instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "PermutationMethod", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:PermutationMethod" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is provided via the " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " argument." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Beginning in SciPy 1.9, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.matrix" }, { "__type": "Text", "__tag": 4046, "value": " inputs (not recommended for new code) are converted to " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " before the calculation is performed. In this case, the output will be a scalar or " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " of appropriate shape rather than a 2D " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.matrix" }, { "__type": "Text", "__tag": 4046, "value": ". Similarly, while masked elements of masked arrays are ignored, the output will be a scalar or " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " rather than a masked array with " }, { "__type": "InlineCode", "__tag": 4051, "value": "mask=False" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "spearmanrho", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:spearmanrho" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ⛔ \nPyTorch ✅ ⛔ \nJAX ✅ ✅ \nDask ⛔ n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "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": [], "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": "statistic" } ] } ] }, { "__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": "pvalue" } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate a Spearman rho 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": "x, y", "annotation": "array-like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The samples: corresponding observations of the independent and dependent variable. The (N-d) arrays must be broadcastable." } ] } ] }, { "__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": "DocParam", "__tag": 4016, "name": "method", "annotation": "ResamplingMethod, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines the method used to compute the p-value. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is an instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "PermutationMethod", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:PermutationMethod" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "/" }, { "__type": "CrossRef", "__tag": 4002, "value": "MonteCarloMethod", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:MonteCarloMethod" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", the p-value is computed using " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.permutation_test", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._resampling:permutation_test" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "/" }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.monte_carlo_test", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._resampling:monte_carlo_test" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " with the provided configuration options and other appropriate settings. Otherwise, the p-value is computed using an asymptotic approximation of the null distribution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int or None, default: 0", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If an int, the axis of the input along which to compute the statistic. The statistic of each axis-slice (e.g. row) of the input will appear in a corresponding element of the output. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", the input will be raveled before computing the statistic." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nan_policy", "annotation": "{'propagate', 'omit', 'raise'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines how to handle input NaNs." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "propagate" }, { "__type": "Text", "__tag": 4046, "value": ": if a NaN is present in the axis slice (e.g. row) along which the statistic is computed, the corresponding entry of the output will be NaN." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "omit" }, { "__type": "Text", "__tag": 4046, "value": ": NaNs will be omitted when performing the calculation. If insufficient data remains in the axis slice along which the statistic is computed, the corresponding entry of the output will be NaN." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "raise" }, { "__type": "Text", "__tag": 4046, "value": ": if a NaN is present, a " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": " will be raised." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "keepdims", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array." } ] } ] } ] } ], "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, it varies between -1 and +1 with 0 implying no correlation. Coefficients of -1 or +1 are associated with an exact monotonic relationship. Positive correlations indicate that as " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " increases, so does " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": "; negative correlations indicate that as " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " increases, " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " decreases. The p-value is the probability of an uncorrelated system producing datasets with a Spearman correlation at least as extreme as the one computed from the observed dataset." } ] } ], "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": "/scipy/stats/_correlation.py", "item_line": 246, "item_type": "function", "aliases": [ "scipy.stats.spearmanrho" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Univariate samples, approximate p-value.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\nx = [1, 2, 3, 4, 5]\ny = [5, 6, 7, 8, 7]\nres = stats.spearmanrho(x, y)\nres.statistic\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nUnivariate samples, exact p-value.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanrho(x, y, method=stats.PermutationMethod())\nres.statistic\nres.pvalue\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nBatch of univariate samples, one vectorized call.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng(98145152315484)\nx2 = rng.standard_normal((2, 100))\ny2 = rng.standard_normal((2, 100))\nres = stats.spearmanrho(x2, y2, axis=-1)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nBivariate samples using standard broadcasting rules.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.spearmanrho(x2[np.newaxis, :], x2[:, np.newaxis], axis=-1)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_ONLY", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_ONLY", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "alternative", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "two-sided" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "nan_policy", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "propagate" }, { "__type": "SigParam", "__tag": 4030, "name": "keepdims", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "spearmanrho" }, "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._correlation:spearmanrho", "arbitrary": [], "local_refs": [ "alternative", "axis", "keepdims", "method", "nan_policy", "res", "x", "y" ] }