{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An often quoted guideline for the validity of this calculation is that the test should be used only if the observed and expected frequencies in each cell are at least 5." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is a test for the independence of different categories of a population. The test is only meaningful when the dimension of " }, { "__type": "ParamRef", "__tag": 4071, "name": "observed" }, { "__type": "Text", "__tag": 4046, "value": " is two or more. Applying the test to a one-dimensional table will always result in " }, { "__type": "InlineRole", "__tag": 4003, "value": "expected", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " equal to " }, { "__type": "ParamRef", "__tag": 4071, "name": "observed" }, { "__type": "Text", "__tag": 4046, "value": " and a chi-square statistic equal to 0." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function does not handle masked arrays, because the calculation does not make sense with missing values." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Like " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.chisquare", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._stats_py:chisquare" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", this function computes a chi-square statistic; the convenience this function provides is to figure out the expected frequencies and degrees of freedom from the given contingency table. If these were already known, and if the Yates' correction was not required, one could use " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.chisquare", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._stats_py:chisquare" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". That is, if one calls " } ] }, { "__type": "Code", "__tag": 4050, "value": "res = chi2_contingency(obs, correction=False)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "then the following is true " } ] }, { "__type": "Code", "__tag": 4050, "value": "(res.statistic, res.pvalue) == stats.chisquare(obs.ravel(),\n f_exp=ex.ravel(),\n ddof=obs.size - 1 - dof)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "ParamRef", "__tag": 4071, "name": "lambda_" }, { "__type": "Text", "__tag": 4046, "value": " argument was added in version 0.13.0 of scipy." } ] }, { "__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": "chi2_contingency", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats.contingency:chi2_contingency" }, "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": "Chi2ContingencyResult", "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" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "dof" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "dof" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "expected_freq" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "expected_freq" } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Chi-square test of independence of variables in a contingency table." } ] } ], "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": "observed", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The contingency table. The table contains the observed frequencies (i.e. number of occurrences) in each category. In the two-dimensional case, the table is often described as an \"R x C table\"." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "correction", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "and" } ] }, { "__type": "Text", "__tag": 4046, "value": " the degrees of freedom is 1, apply Yates' correction for continuity. The effect of the correction is to adjust each observed value by 0.5 towards the corresponding expected value." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "lambda_", "annotation": "float or str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By default, the statistic computed in this test is Pearson's chi-squared statistic " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "ParamRef", "__tag": 4071, "name": "lambda_" }, { "__type": "Text", "__tag": 4046, "value": " allows a statistic from the Cressie-Read power divergence family " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " to be used instead. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.power_divergence", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._stats_py:power_divergence" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__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. Compatible only with " }, { "__type": "InlineRole", "__tag": 4003, "value": "correction=False", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", default " }, { "__type": "ParamRef", "__tag": 4071, "name": "lambda_" }, { "__type": "Text", "__tag": 4046, "value": ", and two-way tables. 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 as documented in the notes. Note that if " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is an instance of " }, { "__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 " }, { "__type": "InlineCode", "__tag": 4051, "value": "rvs" }, { "__type": "Text", "__tag": 4046, "value": " attribute must be left unspecified; Monte Carlo samples are always drawn using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "rvs" }, { "__type": "Text", "__tag": 4046, "value": " method of " }, { "__type": "InlineRole", "__tag": 4003, "value": "scipy.stats.random_table", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.15.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function computes the chi-square statistic and p-value for the hypothesis test of independence of the observed frequencies in the contingency table " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "ParamRef", "__tag": 4071, "name": "observed" }, { "__type": "Text", "__tag": 4046, "value": ". The expected frequencies are computed based on the marginal sums under the assumption of independence; see " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.contingency.expected_freq", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats.contingency:expected_freq" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". The number of degrees of freedom is (expressed using numpy functions and attributes) " } ] }, { "__type": "Code", "__tag": 4050, "value": "dof = observed.size - sum(observed.shape) + observed.ndim - 1", "execution_status": null } ], "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/contingency.py", "item_line": 148, "item_type": "function", "aliases": [ "scipy.stats.chi2_contingency" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "A two-way example (2 x 3):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.stats import chi2_contingency\nobs = np.array([[10, 10, 20], [20, 20, 20]])\nres = chi2_contingency(obs)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "res.dof\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.expected_freq\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nPerform the test using the log-likelihood ratio (i.e. the \"G-test\")\ninstead of Pearson's chi-squared statistic.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res = chi2_contingency(obs, lambda_=\"log-likelihood\")\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nA four-way example (2 x 2 x 2 x 2):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "obs = np.array(\n [[[[12, 17],\n [11, 16]],\n [[11, 12],\n [15, 16]]],\n [[[23, 15],\n [30, 22]],\n [[14, 17],\n [15, 16]]]])\nres = chi2_contingency(obs)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWhen the sum of the elements in a two-way table is small, the p-value\nproduced by the default asymptotic approximation may be inaccurate.\nConsider passing a `PermutationMethod` or `MonteCarloMethod` as the\n`method` parameter with `correction=False`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.stats import PermutationMethod\nobs = np.asarray([[12, 3],\n [17, 16]])\nres = chi2_contingency(obs, correction=False)\nref = chi2_contingency(obs, correction=False, method=PermutationMethod())\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.pvalue, ref.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nFor a more detailed example, see :ref:`hypothesis_chi2_contingency`." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "hypothesis_chi2_contingency", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "hypothesis_chi2_contingency" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extended example" } ] } ], "type": "ref" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.barnard_exact", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:barnard_exact" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.boschloo_exact", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:boschloo_exact" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.chisquare", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:chisquare" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.contingency.expected_freq", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats.contingency:expected_freq" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.fisher_exact", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:fisher_exact" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.power_divergence", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:power_divergence" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "observed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "correction", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "lambda_", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "chi2_contingency" }, "references": [ ".. [1] \"Contingency table\",", " https://en.wikipedia.org/wiki/Contingency_table", ".. [2] \"Pearson's chi-squared test\",", " https://en.wikipedia.org/wiki/Pearson%27s_chi-squared_test", ".. [3] Cressie, N. and Read, T. R. C., \"Multinomial Goodness-of-Fit", " Tests\", J. Royal Stat. Soc. Series B, Vol. 46, No. 3 (1984),", " pp. 440-464." ], "qa": "scipy.stats.contingency:chi2_contingency", "arbitrary": [], "local_refs": [ "correction", "lambda_", "method", "observed", "res" ] }