{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function will converge to the true differential entropy in the limit" } ] }, { "__type": "Math", "__tag": 4058, "value": "n \\to \\infty, \\quad m \\to \\infty, \\quad \\frac{m}{n} \\to 0" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The optimal choice of " }, { "__type": "InlineCode", "__tag": 4051, "value": "window_length" }, { "__type": "Text", "__tag": 4046, "value": " for a given sample size depends on the (unknown) distribution. Typically, the smoother the density of the distribution, the larger the optimal value of " }, { "__type": "InlineCode", "__tag": 4051, "value": "window_length" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following options are available for the " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " parameter." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "'vasicek'" }, { "__type": "Text", "__tag": 4046, "value": " uses the estimator presented in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". This is one of the first and most influential estimators of differential entropy." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "'van es'" }, { "__type": "Text", "__tag": 4046, "value": " uses the bias-corrected estimator presented in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ", which is not only consistent but, under some conditions, asymptotically normal." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "'ebrahimi'" }, { "__type": "Text", "__tag": 4046, "value": " uses an estimator presented in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": ", which was shown in simulation to have smaller bias and mean squared error than the Vasicek estimator." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "'correa'" }, { "__type": "Text", "__tag": 4046, "value": " uses the estimator presented in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "5" }, { "__type": "Text", "__tag": 4046, "value": " based on local linear regression. In a simulation study, it had consistently smaller mean square error than the Vasiceck estimator, but it is more expensive to compute." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "'auto'" }, { "__type": "Text", "__tag": 4046, "value": " selects the method automatically (default). Currently, this selects " }, { "__type": "InlineCode", "__tag": 4051, "value": "'van es'" }, { "__type": "Text", "__tag": 4046, "value": " for very small samples (<10), " }, { "__type": "InlineCode", "__tag": 4051, "value": "'ebrahimi'" }, { "__type": "Text", "__tag": 4046, "value": " for moderate sample sizes (11-1000), and " }, { "__type": "InlineCode", "__tag": 4051, "value": "'vasicek'" }, { "__type": "Text", "__tag": 4046, "value": " for larger samples, but this behavior is subject to change in future versions." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All estimators are implemented as described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "6" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Beginning in SciPy 1.9, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.matrix" }, { "__type": "Text", "__tag": 4046, "value": " inputs (not recommended for new code) are converted to " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " before the calculation is performed. In this case, the output will be a scalar or " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " of appropriate shape rather than a 2D " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.matrix" }, { "__type": "Text", "__tag": 4046, "value": ". Similarly, while masked elements of masked arrays are ignored, the output will be a scalar or " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " rather than a masked array with " }, { "__type": "InlineCode", "__tag": 4051, "value": "mask=False" }, { "__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": "differential_entropy", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._entropy:differential_entropy" }, "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": "entropy", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The calculated differential entropy." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given a sample of a distribution, estimate the differential entropy." } ] } ], "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": "values", "annotation": "sequence", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sample from a continuous distribution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "window_length", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Window length for computing Vasicek estimate. Must be an integer between 1 and half of the sample size. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " (the default), it uses the heuristic value" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\left \\lfloor \\sqrt{n} + 0.5 \\right \\rfloor" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineMath", "__tag": 4057, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " is the sample size. This heuristic was originally proposed in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " and has become common in the literature." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "base", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The logarithmic base to use, defaults to " }, { "__type": "InlineCode", "__tag": 4051, "value": "e" }, { "__type": "Text", "__tag": 4046, "value": " (natural logarithm)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int or None, default: 0", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If an int, the axis of the input along which to compute the statistic. The statistic of each axis-slice (e.g. row) of the input will appear in a corresponding element of the output. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", the input will be raveled before computing the statistic." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "{'vasicek', 'van es', 'ebrahimi', 'correa', 'auto'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The method used to estimate the differential entropy from the sample. Default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "'auto'" }, { "__type": "Text", "__tag": 4046, "value": ". See Notes for more information." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nan_policy", "annotation": "{'propagate', 'omit', 'raise'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines how to handle input NaNs." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "propagate" }, { "__type": "Text", "__tag": 4046, "value": ": if a NaN is present in the axis slice (e.g. row) along which the statistic is computed, the corresponding entry of the output will be NaN." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "omit" }, { "__type": "Text", "__tag": 4046, "value": ": NaNs will be omitted when performing the calculation. If insufficient data remains in the axis slice along which the statistic is computed, the corresponding entry of the output will be NaN." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "raise" }, { "__type": "Text", "__tag": 4046, "value": ": if a NaN is present, a " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": " will be raised." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "keepdims", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Several estimation methods are available using the " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " parameter. By default, a method is selected based the size of the sample." } ] } ], "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/_entropy.py", "item_line": 179, "item_type": "function", "aliases": [ "scipy.stats.differential_entropy" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.stats import differential_entropy, norm\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nEntropy of a standard normal distribution:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng()\nvalues = rng.standard_normal(100)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "differential_entropy(values)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nCompare with the true entropy:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "float(norm.entropy())\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFor several sample sizes between 5 and 1000, compare the accuracy of\nthe ``'vasicek'``, ``'van es'``, and ``'ebrahimi'`` methods. Specifically,\ncompare the root mean squared error (over 1000 trials) between the estimate\nand the true differential entropy of the distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy import stats\nimport matplotlib.pyplot as plt\ndef rmse(res, expected):\n '''Root mean squared error'''\n return np.sqrt(np.mean((res - expected)**2))\na, b = np.log10(5), np.log10(1000)\nns = np.round(np.logspace(a, b, 10)).astype(int)\nreps = 1000 # number of repetitions for each sample size\nexpected = stats.expon.entropy()\nmethod_errors = {'vasicek': [], 'van es': [], 'ebrahimi': []}\nfor method in method_errors:\n for n in ns:\n rvs = stats.expon.rvs(size=(reps, n), random_state=rng)\n res = stats.differential_entropy(rvs, method=method, axis=-1)\n error = rmse(res, expected)\n method_errors[method].append(error)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "for method, errors in method_errors.items():\n plt.loglog(ns, errors, label=method)\nplt.legend()\nplt.xlabel('sample size')\nplt.ylabel('RMSE (1000 trials)')\nplt.title('Entropy Estimator Error (Exponential Distribution)')\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "values", "annotation": "ArrayLike", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "window_length", "annotation": "int | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "base", "annotation": "float | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": "int", "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": "str", "kind": "KEYWORD_ONLY", "default": "auto" }, { "__type": "SigParam", "__tag": 4030, "name": "nan_policy", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "propagate" }, { "__type": "SigParam", "__tag": 4030, "name": "keepdims", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": "numpy.number | numpy.ndarray", "target_name": "differential_entropy" }, "references": [ ".. [1] Vasicek, O. (1976). A test for normality based on sample entropy.", " Journal of the Royal Statistical Society:", " Series B (Methodological), 38(1), 54-59.", ".. [2] Crzcgorzewski, P., & Wirczorkowski, R. (1999). Entropy-based", " goodness-of-fit test for exponentiality. Communications in", " Statistics-Theory and Methods, 28(5), 1183-1202.", ".. [3] Van Es, B. (1992). Estimating functionals related to a density by a", " class of statistics based on spacings. Scandinavian Journal of", " Statistics, 61-72.", ".. [4] Ebrahimi, N., Pflughoeft, K., & Soofi, E. S. (1994). Two measures", " of sample entropy. Statistics & Probability Letters, 20(3), 225-234.", ".. [5] Correa, J. C. (1995). A new estimator of entropy. Communications", " in Statistics-Theory and Methods, 24(10), 2439-2449.", ".. [6] Noughabi, H. A. (2015). Entropy Estimation Using Numerical Methods.", " Annals of Data Science, 2(2), 231-241.", " https://link.springer.com/article/10.1007/s40745-015-0045-9" ], "qa": "scipy.stats._entropy:differential_entropy", "arbitrary": [], "local_refs": [ "axis", "base", "entropy", "keepdims", "method", "nan_policy", "values", "window_length" ] }