{
  "__type": "IngestedDoc",
  "__tag": 4010,
  "_content": {
    "Notes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The discrepancy can serve as a simple measure of quality of a random sample. This measure is based on the geometric properties of the distribution of points in the sample, such as the minimum distance between any pair of points, or the mean edge length in a minimum spanning tree."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The higher the value is, the better the coverage of the parameter space is. Note that this is different from "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "scipy.stats.qmc.discrepancy",
              "reference": {
                "__type": "RefInfo",
                "__tag": 4000,
                "module": "scipy",
                "version": "*",
                "kind": "api",
                "path": "scipy.stats._qmc:discrepancy"
              },
              "kind": "module"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", where lower values correspond to higher quality of the sample."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Also note that when comparing different sampling strategies using this function, the sample size must be kept constant."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "It is possible to calculate two metrics from the minimum spanning tree: the mean edge length and the standard deviation of edges lengths. Using both metrics offers a better picture of uniformity than either metric alone, with higher mean and lower standard deviation being preferable (see "
            },
            {
              "__type": "FootnoteReference",
              "__tag": 4066,
              "label": "1"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " for a brief discussion). This function currently only calculates the mean edge length."
            }
          ]
        }
      ],
      "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": "discrepancy",
              "annotation": "float",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Discrepancy (higher values correspond to greater sample uniformity)."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Discrepancy of a given sample based on its geometric properties."
            }
          ]
        }
      ],
      "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": "sample",
              "annotation": "array_like (n, d)",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "The sample to compute the discrepancy from."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "method",
              "annotation": "{\"mindist\", \"mst\"}, optional",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "The method to use. One of "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "mindist"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " for minimum distance (default) or "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "mst"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " for minimum spanning tree."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "metric",
              "annotation": "str or callable, optional",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "The distance metric to use. See the documentation for "
                    },
                    {
                      "__type": "CrossRef",
                      "__tag": 4002,
                      "value": "scipy.spatial.distance.pdist",
                      "reference": {
                        "__type": "LocalRef",
                        "__tag": 4022,
                        "kind": "module",
                        "path": "scipy.spatial.distance:pdist"
                      },
                      "kind": "module"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " for the available metrics and the default."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "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/_qmc.py",
  "item_line": 339,
  "item_type": "function",
  "aliases": [
    "scipy.stats._qmc.geometric_discrepancy"
  ],
  "example_section_data": {
    "__type": "Section",
    "__tag": 4015,
    "children": [
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "Calculate the quality of the sample using the minimum euclidean distance\n(the defaults):\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "import numpy as np\nfrom scipy.stats import qmc\nrng = np.random.default_rng(191468432622931918890291693003068437394)\nsample = qmc.LatinHypercube(d=2, rng=rng).random(50)\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "qmc.geometric_discrepancy(sample)\n",
        "execution_status": "failure"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nCalculate the quality using the mean edge length in the minimum\nspanning tree:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "qmc.geometric_discrepancy(sample, method='mst')\n",
        "execution_status": "failure"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nDisplay the minimum spanning tree and the points with\nthe smallest distance:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "import matplotlib.pyplot as plt\nfrom matplotlib.lines import Line2D\nfrom scipy.sparse.csgraph import minimum_spanning_tree\nfrom scipy.spatial.distance import pdist, squareform\ndist = pdist(sample)\nmst = minimum_spanning_tree(squareform(dist))\nedges = np.where(mst.toarray() > 0)\nedges = np.asarray(edges).T\nmin_dist = np.min(dist)\nmin_idx = np.argwhere(squareform(dist) == min_dist)[0]\nfig, ax = plt.subplots(figsize=(10, 5))\n_ = ax.set(aspect='equal', xlabel=r'$x_1$', ylabel=r'$x_2$',\n           xlim=[0, 1], ylim=[0, 1])\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "for edge in edges:\n    ax.plot(sample[edge, 0], sample[edge, 1], c='k')\nax.scatter(sample[:, 0], sample[:, 1])\nax.add_patch(plt.Circle(sample[min_idx[0]], min_dist, color='red', fill=False))\n",
        "execution_status": "failure"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "markers = [\n    Line2D([0], [0], marker='o', lw=0, label='Sample points'),\n    Line2D([0], [0], color='k', label='Minimum spanning tree'),\n    Line2D([0], [0], marker='o', lw=0, markerfacecolor='w', markeredgecolor='r',\n           label='Minimum point-to-point distance'),\n]\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "ax.legend(handles=markers, loc='center left', bbox_to_anchor=(1, 0.5));\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-ba64800c68973e04.png"
        }
      }
    ],
    "title": [],
    "level": 0,
    "target": null
  },
  "see_also": [
    {
      "__type": "SeeAlsoItem",
      "__tag": 4028,
      "name": {
        "__type": "CrossRef",
        "__tag": 4002,
        "value": "discrepancy",
        "reference": {
          "__type": "LocalRef",
          "__tag": 4022,
          "kind": "module",
          "path": "scipy.stats._qmc:discrepancy"
        },
        "kind": "module"
      },
      "descriptions": [],
      "type": null
    }
  ],
  "signature": {
    "__type": "SignatureNode",
    "__tag": 4029,
    "kind": "function",
    "parameters": [
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "sample",
        "annotation": "npt.ArrayLike",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": {
          "__type": "Empty",
          "__tag": 4031
        }
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "method",
        "annotation": "Literal['mindist', 'mst']",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "mindist"
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "metric",
        "annotation": "str",
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "euclidean"
      }
    ],
    "return_annotation": "float",
    "target_name": "geometric_discrepancy"
  },
  "references": [
    ".. [1] Franco J. et al. \"Minimum Spanning Tree: A new approach to assess the quality",
    "   of the design of computer experiments.\" Chemometrics and Intelligent Laboratory",
    "   Systems, 97 (2), pp. 164-169, 2009."
  ],
  "qa": "scipy.stats._qmc:geometric_discrepancy",
  "arbitrary": [],
  "local_refs": [
    "discrepancy",
    "method",
    "metric",
    "sample"
  ]
}