{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Barnard's test is an exact test used in the analysis of contingency tables. It examines the association of two categorical variables, and is a more powerful alternative than Fisher's exact test for 2x2 contingency tables." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Let's define " }, { "__type": "InlineMath", "__tag": 4057, "value": "X_0" }, { "__type": "Text", "__tag": 4046, "value": " a 2x2 matrix representing the observed sample, where each column stores the binomial experiment, as in the example below. Let's also define " }, { "__type": "InlineMath", "__tag": 4057, "value": "p_1, p_2" }, { "__type": "Text", "__tag": 4046, "value": " the theoretical binomial probabilities for " }, { "__type": "InlineMath", "__tag": 4057, "value": "x_{11}" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "x_{12}" }, { "__type": "Text", "__tag": 4046, "value": ". When using Barnard exact test, we can assert three different null hypotheses :" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineMath", "__tag": 4057, "value": "H_0 : p_1 \\geq p_2" }, { "__type": "Text", "__tag": 4046, "value": " versus " }, { "__type": "InlineMath", "__tag": 4057, "value": "H_1 : p_1 < p_2" }, { "__type": "Text", "__tag": 4046, "value": ", with " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " = \"less\"" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineMath", "__tag": 4057, "value": "H_0 : p_1 \\leq p_2" }, { "__type": "Text", "__tag": 4046, "value": " versus " }, { "__type": "InlineMath", "__tag": 4057, "value": "H_1 : p_1 > p_2" }, { "__type": "Text", "__tag": 4046, "value": ", with " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " = \"greater\"" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineMath", "__tag": 4057, "value": "H_0 : p_1 = p_2" }, { "__type": "Text", "__tag": 4046, "value": " versus " }, { "__type": "InlineMath", "__tag": 4057, "value": "H_1 : p_1 \\neq p_2" }, { "__type": "Text", "__tag": 4046, "value": ", with " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " = \"two-sided\" (default one)" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In order to compute Barnard's exact test, we are using the Wald statistic " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " with pooled or unpooled variance. Under the default assumption that both variances are equal (" }, { "__type": "InlineCode", "__tag": 4051, "value": "pooled = True" }, { "__type": "Text", "__tag": 4046, "value": "), the statistic is computed as:" } ] }, { "__type": "Math", "__tag": 4058, "value": "T(X) = \\frac{\n \\hat{p}_1 - \\hat{p}_2\n}{\n \\sqrt{\n \\hat{p}(1 - \\hat{p})\n (\\frac{1}{c_1} +\n \\frac{1}{c_2})\n }\n}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\hat{p}_1, \\hat{p}_2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\hat{p}" }, { "__type": "Text", "__tag": 4046, "value": " the estimator of " }, { "__type": "InlineMath", "__tag": 4057, "value": "p_1, p_2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "p" }, { "__type": "Text", "__tag": 4046, "value": ", the latter being the combined probability, given the assumption that " }, { "__type": "InlineMath", "__tag": 4057, "value": "p_1 = p_2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this assumption is invalid (" }, { "__type": "InlineCode", "__tag": 4051, "value": "pooled = False" }, { "__type": "Text", "__tag": 4046, "value": "), the statistic is:" } ] }, { "__type": "Math", "__tag": 4058, "value": "T(X) = \\frac{\n \\hat{p}_1 - \\hat{p}_2\n}{\n \\sqrt{\n \\frac{\\hat{p}_1 (1 - \\hat{p}_1)}{c_1} +\n \\frac{\\hat{p}_2 (1 - \\hat{p}_2)}{c_2}\n }\n}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The p-value is then computed as:" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\sum\n \\binom{c_1}{x_{11}}\n \\binom{c_2}{x_{12}}\n \\pi^{x_{11} + x_{12}}\n (1 - \\pi)^{t - x_{11} - x_{12}}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where the sum is over all 2x2 contingency tables " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " such that: * " }, { "__type": "InlineMath", "__tag": 4057, "value": "T(X) \\leq T(X_0)" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " = \"less\", * " }, { "__type": "InlineMath", "__tag": 4057, "value": "T(X) \\geq T(X_0)" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " = \"greater\", or * " }, { "__type": "InlineMath", "__tag": 4057, "value": "T(X) \\geq |T(X_0)|" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " = \"two-sided\". Above, " }, { "__type": "InlineMath", "__tag": 4057, "value": "c_1, c_2" }, { "__type": "Text", "__tag": 4046, "value": " are the sum of the columns 1 and 2, and " }, { "__type": "InlineMath", "__tag": 4057, "value": "t" }, { "__type": "Text", "__tag": 4046, "value": " the total (sum of the 4 sample's element)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The returned p-value is the maximum p-value taken over the nuisance parameter " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\pi" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineMath", "__tag": 4057, "value": "0 \\leq \\pi \\leq 1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function's complexity is " }, { "__type": "InlineMath", "__tag": 4057, "value": "O(n c_1 c_2)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " is the number of sample points." } ] }, { "__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": "barnard_exact", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:barnard_exact" }, "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": "ber", "annotation": "BarnardExactResult", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A result object with the following 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": "Perform a Barnard exact test on a 2x2 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": "table", "annotation": "array_like of ints", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A 2x2 contingency table. Elements should be non-negative integers." } ] } ] }, { "__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 null and alternative hypotheses. Default is 'two-sided'. Please see explanations in the Notes section below." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "pooled", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to compute score statistic with pooled variance (as in Student's t-test, for example) or unpooled variance (as in Welch's t-test). Default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "n", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of sampling points used in the construction of the sampling method. Note that this argument will automatically be converted to the next higher power of 2 since " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Sobol", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Sobol" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is used to select sample points. Default is 32. Must be positive. In most cases, 32 points is enough to reach good precision. More points comes at performance cost." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "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/_hypotests.py", "item_line": 987, "item_type": "function", "aliases": [ "scipy.stats.barnard_exact" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "An example use of Barnard's test is presented in [2]_.\n\n Consider the following example of a vaccine efficacy study\n (Chan, 1998). In a randomized clinical trial of 30 subjects, 15 were\n inoculated with a recombinant DNA influenza vaccine and the 15 were\n inoculated with a placebo. Twelve of the 15 subjects in the placebo\n group (80%) eventually became infected with influenza whereas for the\n vaccine group, only 7 of the 15 subjects (47%) became infected. The\n data are tabulated as a 2 x 2 table::\n\n Vaccine Placebo\n Yes 7 12\n No 8 3\n\nWhen working with statistical hypothesis testing, we usually use a\nthreshold probability or significance level upon which we decide\nto reject the null hypothesis :math:`H_0`. Suppose we choose the common\nsignificance level of 5%.\n\nOur alternative hypothesis is that the vaccine will lower the chance of\nbecoming infected with the virus; that is, the probability :math:`p_1` of\ncatching the virus with the vaccine will be *less than* the probability\n:math:`p_2` of catching the virus without the vaccine. Therefore, we call\n`barnard_exact` with the ``alternative=\"less\"`` option:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import scipy.stats as stats\nres = stats.barnard_exact([[7, 12], [8, 3]], alternative=\"less\")\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nUnder the null hypothesis that the vaccine will not lower the chance of\nbecoming infected, the probability of obtaining test results at least as\nextreme as the observed data is approximately 3.4%. Since this p-value is\nless than our chosen significance level, we have evidence to reject\n:math:`H_0` in favor of the alternative.\n\nSuppose we had used Fisher's exact test instead:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "_, pvalue = stats.fisher_exact([[7, 12], [8, 3]], alternative=\"less\")\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWith the same threshold significance of 5%, we would not have been able\nto reject the null hypothesis in favor of the alternative. As stated in\n[2]_, Barnard's test is uniformly more powerful than Fisher's exact test\nbecause Barnard's test does not condition on any margin. Fisher's test\nshould only be used when both sets of marginals are fixed." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "boschloo_exact", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:boschloo_exact" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Boschloo's exact test on a 2x2 contingency table, which is an uniformly more powerful alternative to Fisher's exact test." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "chi2_contingency", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats.contingency:chi2_contingency" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Chi-square test of independence of variables in a contingency table." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "fisher_exact", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:fisher_exact" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Fisher exact test on a 2x2 contingency table." } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "table", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "alternative", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "two-sided" }, { "__type": "SigParam", "__tag": 4030, "name": "pooled", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "n", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "32" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "barnard_exact" }, "references": [ ".. [1] Barnard, G. A. \"Significance Tests for 2x2 Tables\". *Biometrika*.", " 34.1/2 (1947): 123-138. :doi:`dpgkg3`", "", ".. [2] Mehta, Cyrus R., and Pralay Senchaudhuri. \"Conditional versus", " unconditional exact tests for comparing two binomials.\"", " *Cytel Software Corporation* 675 (2003): 1-5.", "", ".. [3] \"Wald Test\". *Wikipedia*. https://en.wikipedia.org/wiki/Wald_test" ], "qa": "scipy.stats._hypotests:barnard_exact", "arbitrary": [], "local_refs": [ "alternative", "ber", "n", "pooled", "table" ] }