{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The energy distance between two distributions " }, { "__type": "InlineMath", "__tag": 4057, "value": "u" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "v" }, { "__type": "Text", "__tag": 4046, "value": ", whose respective CDFs are " }, { "__type": "InlineMath", "__tag": 4057, "value": "U" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "V" }, { "__type": "Text", "__tag": 4046, "value": ", equals to:" } ] }, { "__type": "Math", "__tag": 4058, "value": "D(u, v) = \\left( 2\\mathbb E|X - Y| - \\mathbb E|X - X'| -\n\\mathbb E|Y - Y'| \\right)^{1/2}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineMath", "__tag": 4057, "value": "X" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "X'" }, { "__type": "Text", "__tag": 4046, "value": " (resp. " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "Y'" }, { "__type": "Text", "__tag": 4046, "value": ") are independent random variables whose probability distribution is " }, { "__type": "InlineMath", "__tag": 4057, "value": "u" }, { "__type": "Text", "__tag": 4046, "value": " (resp. " }, { "__type": "InlineMath", "__tag": 4057, "value": "v" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sometimes the square of this quantity is referred to as the \"energy distance\" (e.g. in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": "), but as noted in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ", only the definition above satisfies the axioms of a distance function (metric)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As shown in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", for one-dimensional real-valued variables, the energy distance is linked to the non-distribution-free version of the Cramér-von Mises distance:" } ] }, { "__type": "Math", "__tag": 4058, "value": "D(u, v) = \\sqrt{2} l_2(u, v) = \\left( 2 \\int_{-\\infty}^{+\\infty} (U-V)^2\n\\right)^{1/2}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the common Cramér-von Mises criterion uses the distribution-free version of the distance. See " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " (section 2), for more details about both versions of the distance." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The input distributions can be empirical, therefore coming from samples whose values are effectively inputs of the function, or they can be seen as generalized functions, in which case they are weighted sums of Dirac delta functions located at the specified values." } ] }, { "__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": "energy_distance", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._stats_py:energy_distance" }, "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": "distance", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The computed distance between the distributions." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the energy distance between two 1D distributions." } ] } ], "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": "u_values, v_values", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Values observed in the (empirical) distribution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "u_weights, v_weights", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Weight for each value. If unspecified, each value is assigned the same weight. " }, { "__type": "ParamRef", "__tag": 4071, "name": "u_weights" }, { "__type": "Text", "__tag": 4046, "value": " (resp. " }, { "__type": "ParamRef", "__tag": 4071, "name": "v_weights" }, { "__type": "Text", "__tag": 4046, "value": ") must have the same length as " }, { "__type": "ParamRef", "__tag": 4071, "name": "u_values" }, { "__type": "Text", "__tag": 4046, "value": " (resp. " }, { "__type": "ParamRef", "__tag": 4071, "name": "v_values" }, { "__type": "Text", "__tag": 4046, "value": "). If the weight sum differs from 1, it must still be positive and finite so that the weights can be normalized to sum to 1." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.0.0" } ] } ] } ], "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/_stats_py.py", "item_line": 9687, "item_type": "function", "aliases": [ "scipy.stats.energy_distance" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "from scipy.stats import energy_distance\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "energy_distance([0], [2])\nenergy_distance([0, 8], [0, 8], [3, 1], [2, 2])\nenergy_distance([0.7, 7.4, 2.4, 6.8], [1.4, 8. ],\n [2.1, 4.2, 7.4, 8. ], [7.6, 8.8])\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "u_values", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "v_values", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "u_weights", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "v_weights", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "energy_distance" }, "references": [ ".. [1] Rizzo, Szekely \"Energy distance.\" Wiley Interdisciplinary Reviews:", " Computational Statistics, 8(1):27-38 (2015).", ".. [2] Szekely \"E-statistics: The energy of statistical samples.\" Bowling", " Green State University, Department of Mathematics and Statistics,", " Technical Report 02-16 (2002).", ".. [3] \"Energy distance\", https://en.wikipedia.org/wiki/Energy_distance", ".. [4] Bellemare, Danihelka, Dabney, Mohamed, Lakshminarayanan, Hoyer,", " Munos \"The Cramer Distance as a Solution to Biased Wasserstein", " Gradients\" (2017). :arXiv:`1705.10743`." ], "qa": "scipy.stats._stats_py:energy_distance", "arbitrary": [], "local_refs": [ "distance", "u_values", "u_weights", "v_values", "v_weights" ] }