{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The logrank test " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " compares the observed number of events to the expected number of events under the null hypothesis that the two samples were drawn from the same distribution. The statistic is" } ] }, { "__type": "Math", "__tag": 4058, "value": "Z_i = \\frac{\\sum_{j=1}^J(O_{i,j}-E_{i,j})}{\\sqrt{\\sum_{j=1}^J V_{i,j}}}\n\\rightarrow \\mathcal{N}(0,1)" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where" } ] }, { "__type": "Math", "__tag": 4058, "value": "E_{i,j} = O_j \\frac{N_{i,j}}{N_j},\n\\qquad\nV_{i,j} = E_{i,j} \\left(\\frac{N_j-O_j}{N_j}\\right)\n\\left(\\frac{N_j-N_{i,j}}{N_j-1}\\right)," }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineMath", "__tag": 4057, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " denotes the group (i.e. it may assume values " }, { "__type": "InlineMath", "__tag": 4057, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineMath", "__tag": 4057, "value": "y" }, { "__type": "Text", "__tag": 4046, "value": ", or it may be omitted to refer to the combined sample) " }, { "__type": "InlineMath", "__tag": 4057, "value": "j" }, { "__type": "Text", "__tag": 4046, "value": " denotes the time (at which an event occurred), " }, { "__type": "InlineMath", "__tag": 4057, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " is the number of subjects at risk just before an event occurred, and " }, { "__type": "InlineMath", "__tag": 4057, "value": "O" }, { "__type": "Text", "__tag": 4046, "value": " is the observed number of events at that time." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "InlineMath", "__tag": 4057, "value": "Z_x" }, { "__type": "Text", "__tag": 4046, "value": " returned by " }, { "__type": "CrossRef", "__tag": 4002, "value": "logrank", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._survival:logrank" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is the (signed) square root of the statistic returned by many other implementations. Under the null hypothesis, " }, { "__type": "InlineMath", "__tag": 4057, "value": "Z_x**2" }, { "__type": "Text", "__tag": 4046, "value": " is asymptotically distributed according to the chi-squared distribution with one degree of freedom. Consequently, " }, { "__type": "InlineMath", "__tag": 4057, "value": "Z_x" }, { "__type": "Text", "__tag": 4046, "value": " is asymptotically distributed according to the standard normal distribution. The advantage of using " }, { "__type": "InlineMath", "__tag": 4057, "value": "Z_x" }, { "__type": "Text", "__tag": 4046, "value": " is that the sign information (i.e. whether the observed number of events tends to be less than or greater than the number expected under the null hypothesis) is preserved, allowing " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.logrank", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._survival:logrank" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to offer one-sided alternative hypotheses." } ] }, { "__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": "logrank", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._survival:logrank" }, "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": "`~scipy.stats._result_classes.LogRankResult`", "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": "Compare the survival distributions of two samples via the logrank test." } ] } ], "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 or CensoredData", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Samples to compare based on their empirical survival functions." } ] } ] }, { "__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." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The null hypothesis is that the survival distributions of the two groups, say " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "X" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Y" } ] }, { "__type": "Text", "__tag": 4046, "value": ", are identical." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following alternative hypotheses " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": " are available (default is 'two-sided'):" } ] }, { "__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 survival distributions of the two groups are not identical." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'less': survival of group " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "X" } ] }, { "__type": "Text", "__tag": 4046, "value": " is favored: the group " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "X" } ] }, { "__type": "Text", "__tag": 4046, "value": " failure rate function is less than the group " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Y" } ] }, { "__type": "Text", "__tag": 4046, "value": " failure rate function at some times." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'greater': survival of group " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Y" } ] }, { "__type": "Text", "__tag": 4046, "value": " is favored: the group " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "X" } ] }, { "__type": "Text", "__tag": 4046, "value": " failure rate function is greater than the group " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Y" } ] }, { "__type": "Text", "__tag": 4046, "value": " failure rate function at some times." } ] } ] } ] } ] } ] } ], "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/_survival.py", "item_line": 488, "item_type": "function", "aliases": [ "scipy.stats.logrank" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Reference [2]_ compared the survival times of patients with two different\ntypes of recurrent malignant gliomas. The samples below record the time\n(number of weeks) for which each patient participated in the study. The\n`scipy.stats.CensoredData` class is used because the data is\nright-censored: the uncensored observations correspond with observed deaths\nwhereas the censored observations correspond with the patient leaving the\nstudy for another reason.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy import stats\nx = stats.CensoredData(\n uncensored=[6, 13, 21, 30, 37, 38, 49, 50,\n 63, 79, 86, 98, 202, 219],\n right=[31, 47, 80, 82, 82, 149]\n)\ny = stats.CensoredData(\n uncensored=[10, 10, 12, 13, 14, 15, 16, 17, 18, 20, 24, 24,\n 25, 28,30, 33, 35, 37, 40, 40, 46, 48, 76, 81,\n 82, 91, 112, 181],\n right=[34, 40, 70]\n)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe can calculate and visualize the empirical survival functions\nof both groups as follows.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport matplotlib.pyplot as plt\nax = plt.subplot()\necdf_x = stats.ecdf(x)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ecdf_x.sf.plot(ax, label='Astrocytoma')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "ecdf_y = stats.ecdf(y)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ecdf_y.sf.plot(ax, label='Glioblastoma')\nax.set_xlabel('Time to death (weeks)')\nax.set_ylabel('Empirical SF')\nplt.legend()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-6767fc9143fde164.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nVisual inspection of the empirical survival functions suggests that the\nsurvival times tend to be different between the two groups. To formally\nassess whether the difference is significant at the 1% level, we use the\nlogrank test.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res = stats.logrank(x=x, y=y)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.statistic\nres.pvalue\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe p-value is less than 1%, so we can consider the data to be evidence\nagainst the null hypothesis in favor of the alternative that there is a\ndifference between the two survival functions." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.ecdf", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._survival:ecdf" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": "npt.ArrayLike | CensoredData", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": "npt.ArrayLike | CensoredData", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "alternative", "annotation": "Literal['two-sided', 'less', 'greater']", "kind": "POSITIONAL_OR_KEYWORD", "default": "two-sided" } ], "return_annotation": "LogRankResult", "target_name": "logrank" }, "references": [ ".. [1] Mantel N. \"Evaluation of survival data and two new rank order", " statistics arising in its consideration.\"", " Cancer Chemotherapy Reports, 50(3):163-170, PMID: 5910392, 1966", ".. [2] Bland, Altman, \"The logrank test\", BMJ, 328:1073,", " :doi:`10.1136/bmj.328.7447.1073`, 2004", ".. [3] \"Logrank test\", Wikipedia,", " https://en.wikipedia.org/wiki/Logrank_test", ".. [4] Brown, Mark. \"On the choice of variance for the log rank test.\"", " Biometrika 71.1 (1984): 65-74.", ".. [5] Klein, John P., and Melvin L. Moeschberger. Survival analysis:", " techniques for censored and truncated data. Vol. 1230. New York:", " Springer, 2003." ], "qa": "scipy.stats._survival:logrank", "arbitrary": [], "local_refs": [ "alternative", "res", "x", "y" ] }