{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Poisson disk sampling is an iterative sampling strategy. Starting from a seed sample, " }, { "__type": "ParamRef", "__tag": 4071, "name": "ncandidates" }, { "__type": "Text", "__tag": 4046, "value": " are sampled in the hypersphere surrounding the seed. Candidates below a certain " }, { "__type": "ParamRef", "__tag": 4071, "name": "radius" }, { "__type": "Text", "__tag": 4046, "value": " or outside the domain are rejected. New samples are added in a pool of sample seed. The process stops when the pool is empty or when the number of required samples is reached." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum number of point that a sample can contain is directly linked to the " }, { "__type": "ParamRef", "__tag": 4071, "name": "radius" }, { "__type": "Text", "__tag": 4046, "value": ". As the dimension of the space increases, a higher radius spreads the points further and help overcome the curse of dimensionality. See the " }, { "__type": "InlineRole", "__tag": 4003, "value": "quasi monte carlo tutorial ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more details." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The algorithm is more suitable for low dimensions and sampling size due to its iterative nature and memory requirements. Selecting a small radius with a high dimension would mean that the space could contain more samples than using lower dimension or a bigger radius." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some code taken from " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", written consent given on 31.03.2021 by the original author, Shamis, for free use in SciPy under the 3-clause BSD." } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Poisson disk sampling." } ] } ], "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": "d", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Dimension of the parameter space." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "radius", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Minimal distance to keep between points when sampling new candidates." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "hypersphere", "annotation": "{\"volume\", \"surface\"}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sampling strategy to generate potential candidates to be added in the final sample. Default is \"volume\"." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "volume" }, { "__type": "Text", "__tag": 4046, "value": ": original Bridson algorithm as described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". New candidates are sampled " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "within" } ] }, { "__type": "Text", "__tag": 4046, "value": " the hypersphere." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "surface" }, { "__type": "Text", "__tag": 4046, "value": ": only sample the surface of the hypersphere." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "ncandidates", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of candidates to sample per iteration. More candidates result in a denser sampling as more candidates can be accepted per iteration." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "optimization", "annotation": "{None, \"random-cd\", \"lloyd\"}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to use an optimization scheme to improve the quality after sampling. Note that this is a post-processing step that does not guarantee that all properties of the sample will be conserved. Default is None." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "random-cd" }, { "__type": "Text", "__tag": 4046, "value": ": random permutations of coordinates to lower the centered discrepancy. The best sample based on the centered discrepancy is constantly updated. Centered discrepancy-based sampling shows better space-filling robustness toward 2D and 3D subprojections compared to using other discrepancy measures." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "lloyd" }, { "__type": "Text", "__tag": 4046, "value": ": Perturb samples using a modified Lloyd-Max algorithm. The process converges to equally spaced samples." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.10.0" } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rng", "annotation": "`numpy.random.Generator`, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pseudorandom number generator state. When " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " is None, a new " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is created using entropy from the operating system. Types other than " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "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": "api", "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": "." } ] }, { "__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": "api", "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": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", this keyword was changed from " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__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": "seed" }, { "__type": "Text", "__tag": 4046, "value": " keyword will emit warnings. Following a deprecation period, the " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " keyword will be removed." } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "l_bounds, u_bounds", "annotation": "array_like (d,)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lower and upper bounds of target sample data." } ] } ] } ] } ], "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": 1960, "item_type": "ABCMeta", "aliases": [ "scipy.stats._qmc.PoissonDisk" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generate a 2D sample using a `radius` of 0.2.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport matplotlib.pyplot as plt\nfrom matplotlib.collections import PatchCollection\nfrom scipy.stats import qmc\nrng = np.random.default_rng()\nradius = 0.2\nengine = qmc.PoissonDisk(d=2, radius=radius, rng=rng)\nsample = engine.random(20)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nVisualizing the 2D sample and showing that no points are closer than\n`radius`. ``radius/2`` is used to visualize non-intersecting circles.\nIf two samples are exactly at `radius` from each other, then their circle\nof radius ``radius/2`` will touch.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fig, ax = plt.subplots()\n_ = ax.scatter(sample[:, 0], sample[:, 1])\ncircles = [plt.Circle((xi, yi), radius=radius/2, fill=False)\n for xi, yi in sample]\ncollection = PatchCollection(circles, match_original=True)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax.add_collection(collection)\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "_ = ax.set(aspect='equal', xlabel=r'$x_1$', ylabel=r'$x_2$',\n xlim=[0, 1], ylim=[0, 1])\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-8c3133c451363349.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nSuch visualization can be seen as circle packing: how many circle can\nwe put in the space. It is a np-hard problem. The method `fill_space`\ncan be used to add samples until no more samples can be added. This is\na hard problem and parameters may need to be adjusted manually. Beware of\nthe dimension: as the dimensionality increases, the number of samples\nrequired to fill the space increases exponentially\n(curse-of-dimensionality)." } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "d", "annotation": "int | numpy.integer", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "radius", "annotation": "float | numpy.floating | numpy.integer", "kind": "KEYWORD_ONLY", "default": "0.05" }, { "__type": "SigParam", "__tag": 4030, "name": "hypersphere", "annotation": "Literal['volume', 'surface']", "kind": "KEYWORD_ONLY", "default": "volume" }, { "__type": "SigParam", "__tag": 4030, "name": "ncandidates", "annotation": "int | numpy.integer", "kind": "KEYWORD_ONLY", "default": "30" }, { "__type": "SigParam", "__tag": 4030, "name": "optimization", "annotation": "Literal['random-cd', 'lloyd'] | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rng", "annotation": "int | numpy.integer | numpy.random._generator.Generator | numpy.random.mtrand.RandomState | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "l_bounds", "annotation": "npt.ArrayLike | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "u_bounds", "annotation": "npt.ArrayLike | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "seed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": "None", "target_name": "PoissonDisk" }, "references": [ ".. [1] Robert Bridson, \"Fast Poisson Disk Sampling in Arbitrary", " Dimensions.\" SIGGRAPH, 2007.", ".. [2] `StackOverflow `__." ], "qa": "scipy.stats._qmc:PoissonDisk", "arbitrary": [], "local_refs": [ "d", "hypersphere", "l_bounds", "ncandidates", "optimization", "radius", "rng", "u_bounds" ] }