{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Elements of the confidence interval may be NaN for " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='BCa'" }, { "__type": "Text", "__tag": 4046, "value": " if the bootstrap distribution is degenerate (e.g. all elements are identical). In this case, consider using another " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " or inspecting " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " for indications that other analysis may be more appropriate (e.g. all observations are identical)." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "`~scipy.stats.DegenerateDataWarning`", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generated when " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='BCa'" }, { "__type": "Text", "__tag": 4046, "value": " and the bootstrap distribution is degenerate (e.g. all elements are identical)." } ] } ] } ] } ], "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": "BootstrapResult", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An object with attributes:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "confidence_interval" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The bootstrap confidence interval as an instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "collections.namedtuple", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "collections", "version": "?", "kind": "module", "path": "collections:namedtuple" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " with attributes " }, { "__type": "InlineRole", "__tag": 4003, "value": "low", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "high", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "bootstrap_distribution" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The bootstrap distribution, that is, the value of " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " for each resample. The last dimension corresponds with the resamples (e.g. " }, { "__type": "InlineCode", "__tag": 4051, "value": "res.bootstrap_distribution.shape[-1] == n_resamples" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "standard_error" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The bootstrap standard error, that is, the sample standard deviation of the bootstrap distribution." } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute a two-sided bootstrap confidence interval of a statistic." } ] } ], "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": "data", "annotation": "sequence of array-like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Each element of " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " is a sample containing scalar observations from an underlying distribution. Elements of " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " must be broadcastable to the same shape (with the possible exception of the dimension specified by " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "statistic", "annotation": "callable", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Statistic for which the confidence interval is to be calculated. " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " must be a callable that accepts " }, { "__type": "InlineCode", "__tag": 4051, "value": "len(data)" }, { "__type": "Text", "__tag": 4046, "value": " samples as separate arguments and returns the resulting statistic. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "vectorized" }, { "__type": "Text", "__tag": 4046, "value": " is set " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " must also accept a keyword argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " and be vectorized to compute the statistic along the provided " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "n_resamples", "annotation": "int, default: ``9999``", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of resamples performed to form the bootstrap distribution of the statistic." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "batch", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of resamples to process in each vectorized call to " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": ". Memory usage is O( " }, { "__type": "ParamRef", "__tag": 4071, "name": "batch" }, { "__type": "Text", "__tag": 4046, "value": " * " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " ), where " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " is the sample size. Default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", in which case " }, { "__type": "InlineCode", "__tag": 4051, "value": "batch = n_resamples" }, { "__type": "Text", "__tag": 4046, "value": " (or " }, { "__type": "InlineCode", "__tag": 4051, "value": "batch = max(n_resamples, n)" }, { "__type": "Text", "__tag": 4046, "value": " for " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='BCa'" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "vectorized", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "vectorized" }, { "__type": "Text", "__tag": 4046, "value": " is set " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " will not be passed keyword argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " and is expected to calculate the statistic only for 1D samples. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " will be passed keyword argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " and is expected to calculate the statistic along " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " when passed an ND sample array. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " (default), " }, { "__type": "ParamRef", "__tag": 4071, "name": "vectorized" }, { "__type": "Text", "__tag": 4046, "value": " will be set " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis" }, { "__type": "Text", "__tag": 4046, "value": " is a parameter of " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": ". Use of a vectorized statistic typically reduces computation time." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "paired", "annotation": "bool, default: ``False``", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether the statistic treats corresponding elements of the samples in " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " as paired. If True, " }, { "__type": "CrossRef", "__tag": 4002, "value": "bootstrap", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:bootstrap" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " resamples an array of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "indices" } ] }, { "__type": "Text", "__tag": 4046, "value": " and uses the same indices for all arrays in " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": "; otherwise, " }, { "__type": "CrossRef", "__tag": 4002, "value": "bootstrap", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:bootstrap" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " independently resamples the elements of each array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int, default: ``0``", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The axis of the samples in " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " along which the " }, { "__type": "ParamRef", "__tag": 4071, "name": "statistic" }, { "__type": "Text", "__tag": 4046, "value": " is calculated." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "confidence_level", "annotation": "float, default: ``0.95``", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The confidence level of the confidence interval." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "alternative", "annotation": "{'two-sided', 'less', 'greater'}, default: ``'two-sided'``", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Choose " }, { "__type": "InlineCode", "__tag": 4051, "value": "'two-sided'" }, { "__type": "Text", "__tag": 4046, "value": " (default) for a two-sided confidence interval, " }, { "__type": "InlineCode", "__tag": 4051, "value": "'less'" }, { "__type": "Text", "__tag": 4046, "value": " for a one-sided confidence interval with the lower bound at " }, { "__type": "InlineCode", "__tag": 4051, "value": "-np.inf" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineCode", "__tag": 4051, "value": "'greater'" }, { "__type": "Text", "__tag": 4046, "value": " for a one-sided confidence interval with the upper bound at " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.inf" }, { "__type": "Text", "__tag": 4046, "value": ". The other bound of the one-sided confidence intervals is the same as that of a two-sided confidence interval with " }, { "__type": "ParamRef", "__tag": 4071, "name": "confidence_level" }, { "__type": "Text", "__tag": 4046, "value": " twice as far from 1.0; e.g. the upper bound of a 95% " }, { "__type": "InlineCode", "__tag": 4051, "value": "'less'" }, { "__type": "Text", "__tag": 4046, "value": " confidence interval is the same as the upper bound of a 90% " }, { "__type": "InlineCode", "__tag": 4051, "value": "'two-sided'" }, { "__type": "Text", "__tag": 4046, "value": " confidence interval." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "{'percentile', 'basic', 'bca'}, default: ``'BCa'``", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to return the 'percentile' bootstrap confidence interval (" }, { "__type": "InlineCode", "__tag": 4051, "value": "'percentile'" }, { "__type": "Text", "__tag": 4046, "value": "), the 'basic' (AKA 'reverse') bootstrap confidence interval (" }, { "__type": "InlineCode", "__tag": 4051, "value": "'basic'" }, { "__type": "Text", "__tag": 4046, "value": "), or the bias-corrected and accelerated bootstrap confidence interval (" }, { "__type": "InlineCode", "__tag": 4051, "value": "'BCa'" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "bootstrap_result", "annotation": "BootstrapResult, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Provide the result object returned by a previous call to " }, { "__type": "CrossRef", "__tag": 4002, "value": "bootstrap", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:bootstrap" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to include the previous bootstrap distribution in the new bootstrap distribution. This can be used, for example, to change " }, { "__type": "ParamRef", "__tag": 4071, "name": "confidence_level" }, { "__type": "Text", "__tag": 4046, "value": ", change " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": ", or see the effect of performing additional resampling without repeating computations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rng", "annotation": "{None, int, `numpy.random.Generator`}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " is passed by keyword, types other than " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "?", "kind": "module", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " are passed to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.default_rng", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "?", "kind": "module", "path": "numpy.random:default_rng" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to instantiate a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " is already a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": " instance, then the provided instance is used. Specify " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " for repeatable function behavior." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this argument is passed by position or " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is passed by keyword, legacy behavior for the argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " applies:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is None (or " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "?", "kind": "module", "path": "numpy.random" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "), the " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.RandomState", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "?", "kind": "module", "path": "numpy.random.mtrand:RandomState" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " singleton is used." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is an int, a new " }, { "__type": "InlineCode", "__tag": 4051, "value": "RandomState" }, { "__type": "Text", "__tag": 4046, "value": " instance is used, seeded with " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is already a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "RandomState" }, { "__type": "Text", "__tag": 4046, "value": " instance then that instance is used." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 1.15.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As part of the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "SPEC-007" } ], "url": "https://scientific-python.org/specs/spec-0007/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " transition from use of " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.RandomState", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "?", "kind": "module", "path": "numpy.random.mtrand:RandomState" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "?", "kind": "module", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", this keyword was changed from " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": ". For an interim period, both keywords will continue to work, although only one may be specified at a time. After the interim period, function calls using the " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " keyword will emit warnings. The behavior of both " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " are outlined above, but only the " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " keyword should be used in new code." } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "'percentile'" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "alternative" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "'two-sided'" }, { "__type": "Text", "__tag": 4046, "value": ", a bootstrap confidence interval is computed according to the following procedure." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Resample the data: for each sample in " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " and for each of " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_resamples" }, { "__type": "Text", "__tag": 4046, "value": ", take a random sample of the original sample (with replacement) of the same size as the original sample." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the bootstrap distribution of the statistic: for each set of resamples, compute the test statistic." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determine the confidence interval: find the interval of the bootstrap distribution that is" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "symmetric about the median and" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "contains " }, { "__type": "ParamRef", "__tag": 4071, "name": "confidence_level" }, { "__type": "Text", "__tag": 4046, "value": " of the resampled statistic values." } ] } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "While the " }, { "__type": "InlineCode", "__tag": 4051, "value": "'percentile'" }, { "__type": "Text", "__tag": 4046, "value": " method is the most intuitive, it is rarely used in practice. Two more common methods are available, " }, { "__type": "InlineCode", "__tag": 4051, "value": "'basic'" }, { "__type": "Text", "__tag": 4046, "value": " ('reverse percentile') and " }, { "__type": "InlineCode", "__tag": 4051, "value": "'BCa'" }, { "__type": "Text", "__tag": 4046, "value": " ('bias-corrected and accelerated'); they differ in how step 3 is performed." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the samples in " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": " are taken at random from their respective distributions " }, { "__type": "InlineMath", "__tag": 4057, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " times, the confidence interval returned by " }, { "__type": "CrossRef", "__tag": 4002, "value": "bootstrap", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._resampling:bootstrap" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " will contain the true value of the statistic for those distributions approximately `confidence_level`" }, { "__type": "InlineMath", "__tag": 4057, "value": "\\, \\times \\, n" }, { "__type": "Text", "__tag": 4046, "value": " times." } ] } ], "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": "build-install/usr/lib/python3.14/site-packages/scipy/stats/_resampling.py", "item_line": 298, "item_type": "function", "aliases": [ "scipy.stats.bootstrap" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose we have sampled data from an unknown distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nrng = np.random.default_rng()\nfrom scipy.stats import norm\ndist = norm(loc=2, scale=4) # our \"unknown\" distribution\ndata = dist.rvs(size=100, random_state=rng)\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nWe are interested in the standard deviation of the distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "std_true = dist.std() # the true value of the statistic\nprint(std_true)\nstd_sample = np.std(data) # the sample statistic\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "print(std_sample)\n", "execution_status": "failure", "out": "4.510906254254069\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe bootstrap is used to approximate the variability we would expect if we\nwere to repeatedly sample from the unknown distribution and calculate the\nstatistic of the sample each time. It does this by repeatedly resampling\nvalues *from the original sample* with replacement and calculating the\nstatistic of each resample. This results in a \"bootstrap distribution\" of\nthe statistic.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nfrom scipy.stats import bootstrap\ndata = (data,) # samples must be in a sequence\nres = bootstrap(data, np.std, confidence_level=0.9, rng=rng)\nfig, ax = plt.subplots()\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "ax.hist(res.bootstrap_distribution, bins=25)\nax.set_title('Bootstrap Distribution')\nax.set_xlabel('statistic value')\nax.set_ylabel('frequency')\n", "execution_status": "failure", "out": "Text(0, 0.5, 'frequency')\n" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success", "out": "" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "2.0.0.dev0+git20260907.41eeb59", "kind": "assets", "path": "fig-84ddb75b48933509.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThe standard error quantifies this variability. It is calculated as the\nstandard deviation of the bootstrap distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res.standard_error\nres.standard_error == np.std(res.bootstrap_distribution, ddof=1)\n", "execution_status": "failure", "out": "np.True_\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe bootstrap distribution of the statistic is often approximately normal\nwith scale equal to the standard error.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.linspace(3, 5)\npdf = norm.pdf(x, loc=std_sample, scale=res.standard_error)\nfig, ax = plt.subplots()\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "ax.hist(res.bootstrap_distribution, bins=25, density=True)\nax.plot(x, pdf)\nax.set_title('Normal Approximation of the Bootstrap Distribution')\nax.set_xlabel('statistic value')\nax.set_ylabel('pdf')\n", "execution_status": "failure", "out": "Text(0, 0.5, 'pdf')\n" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success", "out": "" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "2.0.0.dev0+git20260907.41eeb59", "kind": "assets", "path": "fig-5f3dba9045f991c9.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThis suggests that we could construct a 90% confidence interval on the\nstatistic based on quantiles of this normal distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "norm.interval(0.9, loc=std_sample, scale=res.standard_error)\n", "execution_status": "failure", "out": "(np.float64(4.036422324436868), np.float64(4.985390184071269))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nDue to central limit theorem, this normal approximation is accurate for a\nvariety of statistics and distributions underlying the samples; however,\nthe approximation is not reliable in all cases. Because `bootstrap` is\ndesigned to work with arbitrary underlying distributions and statistics,\nit uses more advanced techniques to generate an accurate confidence\ninterval.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(res.confidence_interval)\n", "execution_status": "failure", "out": "ConfidenceInterval(low=np.float64(4.096528743341175), high=np.float64(5.05776707630471))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nIf we sample from the original distribution 100 times and form a bootstrap\nconfidence interval for each sample, the confidence interval\ncontains the true value of the statistic approximately 90% of the time.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "n_trials = 100\nci_contains_true_std = 0\nfor i in range(n_trials):\n data = (dist.rvs(size=100, random_state=rng),)\n res = bootstrap(data, np.std, confidence_level=0.9,\n n_resamples=999, rng=rng)\n ci = res.confidence_interval\n if ci[0] < std_true < ci[1]:\n ci_contains_true_std += 1\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "print(ci_contains_true_std)\n", "execution_status": "failure", "out": "90\n" }, { "__type": "Text", "__tag": 4046, "value": "\nRather than writing a loop, we can also determine the confidence intervals\nfor all 100 samples at once.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "data = (dist.rvs(size=(n_trials, 100), random_state=rng),)\nres = bootstrap(data, np.std, axis=-1, confidence_level=0.9,\n n_resamples=999, rng=rng)\nci_l, ci_u = res.confidence_interval\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nHere, `ci_l` and `ci_u` contain the confidence interval for each of the\n``n_trials = 100`` samples.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(ci_l[:5])\nprint(ci_u[:5])\n", "execution_status": "failure", "out": "[3.67079 4.70746 4.42485 4.98482 4.82633]\n" }, { "__type": "Text", "__tag": 4046, "value": "\nAnd again, approximately 90% contain the true value, ``std_true = 4``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(np.sum((ci_l < std_true) & (std_true < ci_u)))\n", "execution_status": "failure", "out": "90\n" }, { "__type": "Text", "__tag": 4046, "value": "\n`bootstrap` can also be used to estimate confidence intervals of\nmulti-sample statistics. For example, to get a confidence interval\nfor the difference between means, we write a function that accepts\ntwo sample arguments and returns only the statistic. The use of the\n``axis`` argument ensures that all mean calculations are perform in\na single vectorized call, which is faster than looping over pairs\nof resamples in Python.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def my_statistic(sample1, sample2, axis=-1):\n mean1 = np.mean(sample1, axis=axis)\n mean2 = np.mean(sample2, axis=axis)\n return mean1 - mean2\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nHere, we use the 'percentile' method with the default 95% confidence level.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "sample1 = norm.rvs(scale=1, size=100, random_state=rng)\nsample2 = norm.rvs(scale=2, size=100, random_state=rng)\ndata = (sample1, sample2)\nres = bootstrap(data, my_statistic, method='basic', rng=rng)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "print(my_statistic(sample1, sample2))\nprint(res.confidence_interval)\n", "execution_status": "failure", "out": "ConfidenceInterval(low=np.float64(-0.3510745535458074), high=np.float64(0.620786692447663))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe bootstrap estimate of the standard error is also available.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(res.standard_error)\n", "execution_status": "failure", "out": "0.24719203054535713\n" }, { "__type": "Text", "__tag": 4046, "value": "\nPaired-sample statistics work, too. For example, consider the Pearson\ncorrelation coefficient.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.stats import pearsonr\nn = 100\nx = np.linspace(0, 10, n)\ny = x + rng.uniform(size=n)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "print(pearsonr(x, y)[0]) # element 0 is the statistic\n", "execution_status": "failure", "out": "0.9958094126228576\n" }, { "__type": "Text", "__tag": 4046, "value": "\nWe wrap `pearsonr` so that it returns only the statistic, ensuring\nthat we use the `axis` argument because it is available.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def my_statistic(x, y, axis=-1):\n return pearsonr(x, y, axis=axis)[0]\n", "execution_status": "success", "out": "" }, { "__type": "Text", "__tag": 4046, "value": "\nWe call `bootstrap` using ``paired=True``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res = bootstrap((x, y), my_statistic, paired=True, rng=rng)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "print(res.confidence_interval)\n", "execution_status": "failure", "out": "ConfidenceInterval(low=np.float64(0.9944484231820774), high=np.float64(0.9967319578696644))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe result object can be passed back into `bootstrap` to perform additional\nresampling:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "len(res.bootstrap_distribution)\nres = bootstrap((x, y), my_statistic, paired=True,\n n_resamples=1000, rng=rng,\n bootstrap_result=res)\nlen(res.bootstrap_distribution)\n", "execution_status": "success", "out": "10999\n" }, { "__type": "Text", "__tag": 4046, "value": "\nor to change the confidence interval options:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res2 = bootstrap((x, y), my_statistic, paired=True,\n n_resamples=0, rng=rng, bootstrap_result=res,\n method='percentile', confidence_level=0.9)\nnp.testing.assert_equal(res2.bootstrap_distribution,\n res.bootstrap_distribution)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "res.confidence_interval\n", "execution_status": "failure", "out": "ConfidenceInterval(low=np.float64(0.9944462074273099), high=np.float64(0.9967321359970698))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nwithout repeating computation of the original bootstrap distribution." } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "data", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "statistic", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "n_resamples", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "9999" }, { "__type": "SigParam", "__tag": 4030, "name": "batch", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "vectorized", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "paired", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "confidence_level", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0.95" }, { "__type": "SigParam", "__tag": 4030, "name": "alternative", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "two-sided" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "BCa" }, { "__type": "SigParam", "__tag": 4030, "name": "bootstrap_result", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rng", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "random_state", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "bootstrap" }, "references": [ ".. [1] B. Efron and R. J. Tibshirani, An Introduction to the Bootstrap,", " Chapman & Hall/CRC, Boca Raton, FL, USA (1993)", ".. [2] Nathaniel E. Helwig, \"Bootstrap Confidence Intervals\",", " http://users.stat.umn.edu/~helwig/notes/bootci-Notes.pdf", ".. [3] Bootstrapping (statistics), Wikipedia,", " https://en.wikipedia.org/wiki/Bootstrapping_%28statistics%29" ], "qa": "scipy.stats._resampling:bootstrap", "arbitrary": [], "local_refs": [ "alternative", "axis", "batch", "bootstrap_result", "confidence_level", "data", "method", "n_resamples", "paired", "res", "rng", "statistic", "vectorized" ] }