{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function follows the contingency table approach of " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "p" } ] }, { "__type": "Text", "__tag": 4046, "value": "-values are computed based on an asymptotic approximation of the test statistic distribution under the null hypothesis " }, { "__type": "InlineMath", "__tag": 4057, "value": "D=0" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Theoretically, hypothesis tests based on Kendall's " }, { "__type": "InlineMath", "__tag": 4057, "value": "tau" }, { "__type": "Text", "__tag": 4046, "value": " and Somers' " }, { "__type": "InlineMath", "__tag": 4057, "value": "D" }, { "__type": "Text", "__tag": 4046, "value": " should be identical. However, the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "p" } ] }, { "__type": "Text", "__tag": 4046, "value": "-values returned by " }, { "__type": "InlineRole", "__tag": 4003, "value": "kendalltau", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " are based on the null hypothesis of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "independence" } ] }, { "__type": "Text", "__tag": 4046, "value": " between " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": " (i.e. the population from which pairs in " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": " are sampled contains equal numbers of all possible pairs), which is more specific than the null hypothesis " }, { "__type": "InlineMath", "__tag": 4057, "value": "D=0" }, { "__type": "Text", "__tag": 4046, "value": " used here. If the null hypothesis of independence is desired, it is acceptable to use the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "p" } ] }, { "__type": "Text", "__tag": 4046, "value": "-value returned by " }, { "__type": "InlineRole", "__tag": 4003, "value": "kendalltau", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " with the statistic returned by " }, { "__type": "CrossRef", "__tag": 4002, "value": "somersd", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:somersd" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " and vice versa. For more information, see " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Contingency tables are formatted according to the convention used by SAS and R: the first ranking supplied (" }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ") is the \"row\" variable, and the second ranking supplied (" }, { "__type": "InlineCode", "__tag": 4051, "value": "y" }, { "__type": "Text", "__tag": 4046, "value": ") is the \"column\" variable. This is opposite the convention of Somers' original paper " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__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": "somersd", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:somersd" }, "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": "SomersDResult", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A " }, { "__type": "CrossRef", "__tag": 4002, "value": "SomersDResult", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:SomersDResult" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " object with the following fields:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__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": "table" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "table" } ] } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculates Somers' D, an asymmetric measure of ordinal association." } ] } ], "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", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "1D array of rankings, treated as the (row) independent variable. Alternatively, a 2D contingency table." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " is a 1D array of rankings, " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " is a 1D array of rankings of the same length, treated as the (column) dependent variable. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " is 2D, " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " is ignored." } ] } ] }, { "__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: * 'two-sided': the rank correlation is nonzero * 'less': the rank correlation is negative (less than zero) * 'greater': the rank correlation is positive (greater than zero)" } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Like Kendall's " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\tau" }, { "__type": "Text", "__tag": 4046, "value": ", Somers' " }, { "__type": "InlineMath", "__tag": 4057, "value": "D" }, { "__type": "Text", "__tag": 4046, "value": " is a measure of the correspondence between two rankings. Both statistics consider the difference between the number of concordant and discordant pairs in two rankings " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": ", and both are normalized such that values close to 1 indicate strong agreement and values close to -1 indicate strong disagreement. They differ in how they are normalized. To show the relationship, Somers' " }, { "__type": "InlineMath", "__tag": 4057, "value": "D" }, { "__type": "Text", "__tag": 4046, "value": " can be defined in terms of Kendall's " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\tau_a" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Math", "__tag": 4058, "value": "D(Y|X) = \\frac{\\tau_a(X, Y)}{\\tau_a(X, X)}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose the first ranking " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " has " }, { "__type": "InlineMath", "__tag": 4057, "value": "r" }, { "__type": "Text", "__tag": 4046, "value": " distinct ranks and the second ranking " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": " has " }, { "__type": "InlineMath", "__tag": 4057, "value": "s" }, { "__type": "Text", "__tag": 4046, "value": " distinct ranks. These two lists of " }, { "__type": "InlineMath", "__tag": 4057, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " rankings can also be viewed as an " }, { "__type": "InlineMath", "__tag": 4057, "value": "r \\times s" }, { "__type": "Text", "__tag": 4046, "value": " contingency table in which element " }, { "__type": "InlineMath", "__tag": 4057, "value": "i, j" }, { "__type": "Text", "__tag": 4046, "value": " is the number of rank pairs with rank " }, { "__type": "InlineMath", "__tag": 4057, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " in ranking " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " and rank " }, { "__type": "InlineMath", "__tag": 4057, "value": "j" }, { "__type": "Text", "__tag": 4046, "value": " in ranking " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": ". Accordingly, " }, { "__type": "CrossRef", "__tag": 4002, "value": "somersd", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._hypotests:somersd" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " also allows the input data to be supplied as a single, 2D contingency table instead of as two separate, 1D rankings." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the definition of Somers' " }, { "__type": "InlineMath", "__tag": 4057, "value": "D" }, { "__type": "Text", "__tag": 4046, "value": " is asymmetric: in general, " }, { "__type": "InlineMath", "__tag": 4057, "value": "D(Y|X) \\neq D(X|Y)" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "somersd(x, y)" }, { "__type": "Text", "__tag": 4046, "value": " calculates Somers' " }, { "__type": "InlineMath", "__tag": 4057, "value": "D(Y|X)" }, { "__type": "Text", "__tag": 4046, "value": ": the \"row\" variable " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " is treated as an independent variable, and the \"column\" variable " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": " is dependent. For Somers' " }, { "__type": "InlineMath", "__tag": 4057, "value": "D(X|Y)" }, { "__type": "Text", "__tag": 4046, "value": ", swap the input lists or transpose the input table." } ] } ], "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": 775, "item_type": "function", "aliases": [ "scipy.stats.somersd" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "We calculate Somers' D for the example given in [4]_, in which a hotel\nchain owner seeks to determine the association between hotel room\ncleanliness and customer satisfaction. The independent variable, hotel\nroom cleanliness, is ranked on an ordinal scale: \"below average (1)\",\n\"average (2)\", or \"above average (3)\". The dependent variable, customer\nsatisfaction, is ranked on a second scale: \"very dissatisfied (1)\",\n\"moderately dissatisfied (2)\", \"neither dissatisfied nor satisfied (3)\",\n\"moderately satisfied (4)\", or \"very satisfied (5)\". 189 customers\nrespond to the survey, and the results are cast into a contingency table\nwith the hotel room cleanliness as the \"row\" variable and customer\nsatisfaction as the \"column\" variable.\n\n+-----+-----+-----+-----+-----+-----+\n| | (1) | (2) | (3) | (4) | (5) |\n+=====+=====+=====+=====+=====+=====+\n| (1) | 27 | 25 | 14 | 7 | 0 |\n+-----+-----+-----+-----+-----+-----+\n| (2) | 7 | 14 | 18 | 35 | 12 |\n+-----+-----+-----+-----+-----+-----+\n| (3) | 1 | 3 | 2 | 7 | 17 |\n+-----+-----+-----+-----+-----+-----+\n\nFor example, 27 customers assigned their room a cleanliness ranking of\n\"below average (1)\" and a corresponding satisfaction of \"very\ndissatisfied (1)\". We perform the analysis as follows.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.stats import somersd\ntable = [[27, 25, 14, 7, 0], [7, 14, 18, 35, 12], [1, 3, 2, 7, 17]]\nres = somersd(table)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe value of the Somers' D statistic is approximately 0.6, indicating\na positive correlation between room cleanliness and customer satisfaction\nin the sample.\nThe *p*-value is very small, indicating a very small probability of\nobserving such an extreme value of the statistic under the null\nhypothesis that the statistic of the entire population (from which\nour sample of 189 customers is drawn) is zero. This supports the\nalternative hypothesis that the true value of Somers' D for the population\nis nonzero." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "kendalltau", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "kendalltau" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculates Kendall's tau, another correlation measure." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "pearsonr", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "pearsonr" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculates a Pearson correlation coefficient." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "spearmanr", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "spearmanr" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculates a Spearman rank-order correlation coefficient." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "weightedtau", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:weightedtau" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Computes a weighted version of Kendall's tau." } ] } ], "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": "None" }, { "__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": "somersd" }, "references": [ ".. [1] Robert H. Somers, \"A New Asymmetric Measure of Association for", " Ordinal Variables\", *American Sociological Review*, Vol. 27, No. 6,", " pp. 799--811, 1962.", "", ".. [2] Morton B. Brown and Jacqueline K. Benedetti, \"Sampling Behavior of", " Tests for Correlation in Two-Way Contingency Tables\", *Journal of", " the American Statistical Association* Vol. 72, No. 358, pp.", " 309--315, 1977.", "", ".. [3] SAS Institute, Inc., \"The FREQ Procedure (Book Excerpt)\",", " *SAS/STAT 9.2 User's Guide, Second Edition*, SAS Publishing, 2009.", "", ".. [4] Laerd Statistics, \"Somers' d using SPSS Statistics\", *SPSS", " Statistics Tutorials and Statistical Guides*,", " https://statistics.laerd.com/spss-tutorials/somers-d-using-spss-statistics.php,", " Accessed July 31, 2020." ], "qa": "scipy.stats._hypotests:somersd", "arbitrary": [], "local_refs": [ "alternative", "res", "x", "y" ] }