{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lloyd-Max algorithm is an iterative process with the purpose of improving the dispersion of samples. For given sample: (i) compute a Voronoi Tessellation; (ii) find the centroid of each Voronoi cell; (iii) move the samples toward the centroid of their respective cell. See " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A relaxation factor is used to control how fast samples can move at each iteration. This factor is starting at 2 and ending at 1 after " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxiter" }, { "__type": "Text", "__tag": 4046, "value": " following an exponential decay." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The process converges to equally spaced samples. It implies that measures like the discrepancy could suffer from too many iterations. On the other hand, L1 and L2 distances should improve. This is especially true with QMC methods which tend to favor the discrepancy over other criteria." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The current implementation does not intersect the Voronoi Tessellation with the boundaries. This implies that for a low number of samples, empirically below 20, no Voronoi cell is touching the boundaries. Hence, samples cannot be moved close to the boundaries." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Further improvements could consider the samples at infinity so that all boundaries are segments of some Voronoi cells. This would fix the computation of the centroid position." } ] } ] }, { "__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 Voronoi Tessellation step is expensive and quickly becomes intractable with dimensions as low as 10 even for a sample of size as low as 1000." } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.9.0" } ] } ] } ], "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": "sample", "annotation": "array_like (n, d)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The sample after being processed by Lloyd-Max algorithm." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Approximate Centroidal Voronoi Tessellation." } ] } ], "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 iterate on. With " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " the number of samples and " }, { "__type": "InlineCode", "__tag": 4051, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " the dimension. Samples must be in " }, { "__type": "InlineMath", "__tag": 4057, "value": "[0, 1]^d" }, { "__type": "Text", "__tag": 4046, "value": ", with " }, { "__type": "InlineCode", "__tag": 4051, "value": "d>=2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tolerance for termination. If the min of the L1-norm over the samples changes less than " }, { "__type": "ParamRef", "__tag": 4071, "name": "tol" }, { "__type": "Text", "__tag": 4046, "value": ", it stops the algorithm. Default is 1e-5." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of iterations. It will stop the algorithm even if " }, { "__type": "ParamRef", "__tag": 4071, "name": "tol" }, { "__type": "Text", "__tag": 4046, "value": " is above the threshold. Too many iterations tend to cluster the samples as a hypersphere. Default is 10." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "qhull_options", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additional options to pass to Qhull. See Qhull manual for details. (Default: \"Qbb Qc Qz Qj Qx\" for ndim > 4 and \"Qbb Qc Qz Qj\" otherwise.)" } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Perturb samples in N-dimensions using Lloyd-Max algorithm." } ] } ], "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": 2747, "item_type": "function", "aliases": [ "scipy.stats._qmc._lloyd_centroidal_voronoi_tessellation" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.spatial import distance\nfrom scipy.stats._qmc import _lloyd_centroidal_voronoi_tessellation\nrng = np.random.default_rng()\nsample = rng.random((128, 2))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n.. note::\n\n The samples need to be in :math:`[0, 1]^d`. `scipy.stats.qmc.scale`\n can be used to scale the samples from their\n original bounds to :math:`[0, 1]^d`. And back to their original bounds.\n\nCompute the quality of the sample using the L1 criterion.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def l1_norm(sample):\n return distance.pdist(sample, 'cityblock').min()\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "l1_norm(sample)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nNow process the sample using Lloyd's algorithm and check the improvement\non the L1. The value should increase.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "sample = _lloyd_centroidal_voronoi_tessellation(sample)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "l1_norm(sample)\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "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": "tol", "annotation": "DecimalNumber", "kind": "KEYWORD_ONLY", "default": "1e-05" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": "IntNumber", "kind": "KEYWORD_ONLY", "default": "10" }, { "__type": "SigParam", "__tag": 4030, "name": "qhull_options", "annotation": "str | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "kwargs", "annotation": "dict", "kind": "VAR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } } ], "return_annotation": "np.ndarray", "target_name": "_lloyd_centroidal_voronoi_tessellation" }, "references": [ ".. [1] Lloyd. \"Least Squares Quantization in PCM\".", " IEEE Transactions on Information Theory, 1982.", ".. [2] Max J. \"Quantizing for minimum distortion\".", " IEEE Transactions on Information Theory, 1960." ], "qa": "scipy.stats._qmc:_lloyd_centroidal_voronoi_tessellation", "arbitrary": [], "local_refs": [ "maxiter", "qhull_options", "sample", "tol" ] }