{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There is currently no special handling of ties in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "; they are broken arbitrarily by the implementation. " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " recommends: \"if there are ties among the Xi's, then choose an increasing rearrangement as above by breaking ties uniformly at random.\" This is easily accomplished by adding a small amount of random noise to " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "; see examples." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " notes that the statistic is not symmetric in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "by design" } ] }, { "__type": "Text", "__tag": 4046, "value": ": \"...we may want to understand if " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": " is a function " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": ", and not just if one of the variables is a function of the other.\" See " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " Remark 1." } ] }, { "__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": "chatterjeexi", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._correlation:chatterjeexi" }, "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": [], "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": "Compute the xi correlation and perform a test of independence" } ] } ], "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": "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": "method", "annotation": "'asymptotic' or `PermutationMethod` instance, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Selects the method used to calculate the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "p" } ] }, { "__type": "Text", "__tag": 4046, "value": "-value. Default is 'asymptotic'. 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": "InlineCode", "__tag": 4051, "value": "'asymptotic'" }, { "__type": "Text", "__tag": 4046, "value": ": compares the standardized test statistic against the normal distribution." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__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": " instance. In this case, the p-value is computed using " }, { "__type": "CrossRef", "__tag": 4002, "value": "permutation_test", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:permutation_test" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " with the provided configuration options and other appropriate settings." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y_continuous", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " is assumed to be drawn from a continuous distribution. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " is drawn from a continuous distribution, results are valid whether this is assumed or not, but enabling this assumption will result in faster computation and typically produce similar results." } ] } ] }, { "__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 xi correlation coefficient is a measure of association between two variables; the value tends to be close to zero when the variables are independent and close to 1 when there is a strong association. Unlike other correlation coefficients, the xi correlation is effective even when the association is not monotonic." } ] } ], "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": 87, "item_type": "function", "aliases": [ "scipy.stats.chatterjeexi" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generate perfectly correlated data, and observe that the xi correlation is\nnearly 1.0.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\nrng = np.random.default_rng(348932549825235)\nx = rng.uniform(0, 10, size=100)\ny = np.sin(x)\nres = stats.chatterjeexi(x, y)\nres.statistic\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe probability of observing such a high value of the statistic under the\nnull hypothesis of independence is very low.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nAs noise is introduced, the correlation coefficient decreases.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "noise = rng.normal(scale=[[0.1], [0.5], [1]], size=(3, 100))\nres = stats.chatterjeexi(x, y + noise, axis=-1)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nBecause the distribution of `y` is continuous, it is valid to pass\n``y_continuous=True``. The statistic is identical, and the p-value\n(not shown) is only slightly different.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "stats.chatterjeexi(x, y + noise, y_continuous=True, axis=-1).statistic\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nConsider a case in which there are ties in `x`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = rng.integers(10, size=1000)\ny = rng.integers(10, size=1000)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n[1]_ recommends breaking the ties uniformly at random.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "d = rng.uniform(1e-5, size=x.size)\nres = stats.chatterjeexi(x + d, y)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nSince this gives a randomized estimate of the statistic, [1]_ also suggests\nconsidering the average over all possibilities of breaking ties. This is\ncomputationally infeasible when there are many ties, but a randomized estimate of\n*this* quantity can be obtained by considering many random possibilities of breaking\nties.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "d = rng.uniform(1e-5, size=(9999, x.size))\nres = stats.chatterjeexi(x + d, y, axis=1)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.mean(res.statistic)\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.kendalltau", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:kendalltau" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.pearsonr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:pearsonr" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.spearmanr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:spearmanr" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "y_continuous", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "asymptotic" }, { "__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": "chatterjeexi" }, "references": [ ".. [1] Chatterjee, Sourav. \"A new coefficient of correlation.\" Journal of", " the American Statistical Association 116.536 (2021): 2009-2022.", " :doi:`10.1080/01621459.2020.1758115`." ], "qa": "scipy.stats._correlation:chatterjeexi", "arbitrary": [], "local_refs": [ "axis", "keepdims", "method", "nan_policy", "res", "x", "y", "y_continuous" ] }