{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Bandwidth selection strongly influences the estimate obtained from the KDE (much more so than the actual shape of the kernel). Bandwidth selection can be done by a \"rule of thumb\", by cross-validation, by \"plug-in methods\" or by other means; see " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": " for reviews. " }, { "__type": "CrossRef", "__tag": 4002, "value": "gaussian_kde", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._kde:gaussian_kde" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " uses a rule of thumb, the default is Scott's Rule." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Scott's Rule " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", implemented as " }, { "__type": "InlineRole", "__tag": 4003, "value": "scotts_factor", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", is " } ] }, { "__type": "Code", "__tag": 4050, "value": "n**(-1./(d+4)),", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " the number of data points and " }, { "__type": "InlineCode", "__tag": 4051, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " the number of dimensions. In the case of unequally weighted points, " }, { "__type": "InlineRole", "__tag": 4003, "value": "scotts_factor", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " becomes " } ] }, { "__type": "Code", "__tag": 4050, "value": "neff**(-1./(d+4)),", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with " }, { "__type": "InlineCode", "__tag": 4051, "value": "neff" }, { "__type": "Text", "__tag": 4046, "value": " the effective number of datapoints. Silverman's suggestion for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "multivariate" } ] }, { "__type": "Text", "__tag": 4046, "value": " data " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", implemented as " }, { "__type": "InlineRole", "__tag": 4003, "value": "silverman_factor", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", is " } ] }, { "__type": "Code", "__tag": 4050, "value": "(n * (d + 2) / 4.)**(-1. / (d + 4)).", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "or in the case of unequally weighted points " } ] }, { "__type": "Code", "__tag": 4050, "value": "(neff * (d + 2) / 4.)**(-1. / (d + 4)).", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that this is not the same as \"Silverman's rule of thumb\" " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "6" }, { "__type": "Text", "__tag": 4046, "value": ", which may be more robust in the univariate case; see documentation of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "set_bandwidth" }, { "__type": "Text", "__tag": 4046, "value": " method for implementing a custom bandwidth rule." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Good general descriptions of kernel density estimation can be found in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", the mathematics for this multi-dimensional implementation can be found in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "With a set of weighted samples, the effective number of datapoints " }, { "__type": "InlineCode", "__tag": 4051, "value": "neff" }, { "__type": "Text", "__tag": 4046, "value": " is defined by " } ] }, { "__type": "Code", "__tag": 4050, "value": "neff = sum(weights)^2 / sum(weights^2)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "as detailed in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "5" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "gaussian_kde", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._kde:gaussian_kde" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " does not currently support data that lies in a lower-dimensional subspace of the space in which it is expressed. For such data, consider performing principal component analysis / dimensionality reduction and using " }, { "__type": "CrossRef", "__tag": 4002, "value": "gaussian_kde", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._kde:gaussian_kde" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " with the transformed data." } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "evaluate", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "__call__", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "integrate_gaussian", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "integrate_box_1d", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "integrate_box", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "integrate_kde", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "pdf", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "logpdf", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "resample", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "set_bandwidth", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "covariance_factor", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "marginal", "annotation": "", "desc": [] } ] } ], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Representation of a kernel-density estimate using Gaussian kernels." } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "dataset", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The dataset with which " }, { "__type": "CrossRef", "__tag": 4002, "value": "gaussian_kde", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._kde:gaussian_kde" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " was initialized." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "d", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of dimensions." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "n", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of datapoints." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "neff", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Effective number of datapoints." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.2.0" } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "factor", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The bandwidth factor obtained from " }, { "__type": "CrossRef", "__tag": 4002, "value": "covariance_factor", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "covariance_factor" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "covariance", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The kernel covariance matrix; this is the data covariance matrix multiplied by the square of the bandwidth factor, e.g. " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.cov(dataset) * factor**2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "inv_cov", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The inverse of " }, { "__type": "CrossRef", "__tag": 4002, "value": "covariance", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "covariance" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "dataset", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Datapoints to estimate from. In case of univariate data this is a 1-D array, otherwise a 2-D array with shape (# of dims, # of data)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "bw_method", "annotation": "str, scalar or callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The method used to calculate the bandwidth factor. This can be 'scott', 'silverman', a scalar constant or a callable. If a scalar, this will be used directly as " }, { "__type": "CrossRef", "__tag": 4002, "value": "factor", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "factor" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": ". If a callable, it should take a " }, { "__type": "CrossRef", "__tag": 4002, "value": "gaussian_kde", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._kde:gaussian_kde" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " instance as only parameter and return a scalar. If None (default), 'scott' is used. See Notes for more details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "weights", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "weights of datapoints. This must be the same shape as dataset. If None (default), the samples are assumed to be equally weighted" } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Kernel density estimation is a way to estimate the probability density function (PDF) of a random variable in a non-parametric way. " }, { "__type": "CrossRef", "__tag": 4002, "value": "gaussian_kde", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._kde:gaussian_kde" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " works for both uni-variate and multi-variate data. It includes automatic bandwidth determination. The estimation works best for a unimodal distribution; bimodal or multi-modal distributions tend to be oversmoothed." } ] } ], "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/_kde.py", "item_line": 36, "item_type": "class", "aliases": [ "scipy.stats.gaussian_kde" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generate some random two-dimensional data:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\ndef measure(n):\n \"Measurement model, return two coupled measurements.\"\n m1 = np.random.normal(size=n)\n m2 = np.random.normal(scale=0.5, size=n)\n return m1+m2, m1-m2\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "m1, m2 = measure(2000)\nxmin = m1.min()\nxmax = m1.max()\nymin = m2.min()\nymax = m2.max()\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nPerform a kernel density estimate on the data:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "X, Y = np.mgrid[xmin:xmax:100j, ymin:ymax:100j]\npositions = np.vstack([X.ravel(), Y.ravel()])\nvalues = np.vstack([m1, m2])\nkernel = stats.gaussian_kde(values)\nZ = np.reshape(kernel(positions).T, X.shape)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nPlot the results:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nfig, ax = plt.subplots()\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax.imshow(np.rot90(Z), cmap=plt.cm.gist_earth_r,\n extent=[xmin, xmax, ymin, ymax])\nax.plot(m1, m2, 'k.', markersize=2)\nax.set_xlim([xmin, xmax])\nax.set_ylim([ymin, ymax])\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-9ba3ff8fd93b9911.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nCompare against manual KDE at a point:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "point = [1, 2]\nmean = values.T\ncov = kernel.factor**2 * np.cov(values)\nX = stats.multivariate_normal(cov=cov)\nres = kernel.pdf(point)\nref = X.pdf(point - mean).sum() / len(mean)\nnp.allclose(res, ref)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "dataset", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "bw_method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "weights", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "gaussian_kde" }, "references": [ ".. [1] D.W. Scott, \"Multivariate Density Estimation: Theory, Practice, and", " Visualization\", John Wiley & Sons, New York, Chicester, 1992.", ".. [2] B.W. Silverman, \"Density Estimation for Statistics and Data", " Analysis\", Vol. 26, Monographs on Statistics and Applied Probability,", " Chapman and Hall, London, 1986.", ".. [3] B.A. Turlach, \"Bandwidth Selection in Kernel Density Estimation: A", " Review\", CORE and Institut de Statistique, Vol. 19, pp. 1-33, 1993.", ".. [4] D.M. Bashtannyk and R.J. Hyndman, \"Bandwidth selection for kernel", " conditional density estimation\", Computational Statistics & Data", " Analysis, Vol. 36, pp. 279-298, 2001.", ".. [5] Gray P. G., 1969, Journal of the Royal Statistical Society.", " Series A (General), 132, 272", ".. [6] Kernel density estimation. *Wikipedia.*", " https://en.wikipedia.org/wiki/Kernel_density_estimation" ], "qa": "scipy.stats._kde:gaussian_kde", "arbitrary": [], "local_refs": [ "__call__", "bw_method", "covariance", "covariance_factor", "d", "dataset", "evaluate", "factor", "integrate_box", "integrate_box_1d", "integrate_gaussian", "integrate_kde", "inv_cov", "logpdf", "marginal", "n", "neff", "pdf", "resample", "set_bandwidth", "weights" ] }