{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The two methods do not return the same sequence of variates." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The \"count\" algorithm is roughly equivalent to the following numpy code " } ] }, { "__type": "Code", "__tag": 4050, "value": "choices = np.repeat(np.arange(len(colors)), colors)\nselection = np.random.choice(choices, nsample, replace=False)\nvariate = np.bincount(selection, minlength=len(colors))", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The \"count\" algorithm uses a temporary array of integers with length " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum(colors)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The \"marginals\" algorithm generates a variate by using repeated calls to the univariate hypergeometric sampler. It is roughly equivalent to " } ] }, { "__type": "Code", "__tag": 4050, "value": "variate = np.zeros(len(colors), dtype=np.int64)\n# `remaining` is the cumulative sum of `colors` from the last\n# element to the first; e.g. if `colors` is [3, 1, 5], then\n# `remaining` is [9, 6, 5].\nremaining = np.cumsum(colors[::-1])[::-1]\nfor i in range(len(colors)-1):\n if nsample < 1:\n break\n variate[i] = hypergeometric(colors[i], remaining[i+1],\n nsample)\n nsample -= variate[i]\nvariate[-1] = nsample", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default method is \"marginals\". For some cases (e.g. when " }, { "__type": "ParamRef", "__tag": 4071, "name": "colors" }, { "__type": "Text", "__tag": 4046, "value": " contains relatively small integers), the \"count\" method can be significantly faster than the \"marginals\" method. If performance of the algorithm is important, test the two methods with typical inputs to decide which works best." } ] } ], "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": "variates", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array of variates drawn from the multivariate hypergeometric distribution." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generate variates from a multivariate hypergeometric distribution." } ] } ], "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": "colors", "annotation": "sequence of integers", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of each type of item in the collection from which a sample is drawn. The values in " }, { "__type": "InlineCode", "__tag": 4051, "value": "colors" }, { "__type": "Text", "__tag": 4046, "value": " must be nonnegative. To avoid loss of precision in the algorithm, " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum(colors)" }, { "__type": "Text", "__tag": 4046, "value": " must be less than " }, { "__type": "InlineCode", "__tag": 4051, "value": "10**9" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is \"marginals\"." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nsample", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of items selected. " }, { "__type": "InlineCode", "__tag": 4051, "value": "nsample" }, { "__type": "Text", "__tag": 4046, "value": " must not be greater than " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum(colors)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "size", "annotation": "int or tuple of ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of variates to generate, either an integer or a tuple holding the shape of the array of variates. If the given size is, e.g., " }, { "__type": "InlineCode", "__tag": 4051, "value": "(k, m)" }, { "__type": "Text", "__tag": 4046, "value": ", then " }, { "__type": "InlineCode", "__tag": 4051, "value": "k * m" }, { "__type": "Text", "__tag": 4046, "value": " variates are drawn, where one variate is a vector of length " }, { "__type": "InlineCode", "__tag": 4051, "value": "len(colors)" }, { "__type": "Text", "__tag": 4046, "value": ", and the return value has shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(k, m, len(colors))" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "ParamRef", "__tag": 4071, "name": "size" }, { "__type": "Text", "__tag": 4046, "value": " is an integer, the output has shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(size, len(colors))" }, { "__type": "Text", "__tag": 4046, "value": ". Default is None, in which case a single variate is returned as an array with shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(len(colors),)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "string, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specify the algorithm that is used to generate the variates. Must be 'count' or 'marginals' (the default). See the Notes for a description of the methods." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The multivariate hypergeometric distribution is a generalization of the hypergeometric distribution." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Choose " }, { "__type": "InlineCode", "__tag": 4051, "value": "nsample" }, { "__type": "Text", "__tag": 4046, "value": " items at random without replacement from a collection with " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " distinct types. " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " is the length of " }, { "__type": "InlineCode", "__tag": 4051, "value": "colors" }, { "__type": "Text", "__tag": 4046, "value": ", and the values in " }, { "__type": "InlineCode", "__tag": 4051, "value": "colors" }, { "__type": "Text", "__tag": 4046, "value": " are the number of occurrences of that type in the collection. The total number of items in the collection is " }, { "__type": "InlineCode", "__tag": 4051, "value": "sum(colors)" }, { "__type": "Text", "__tag": 4046, "value": ". Each random variate generated by this function is a vector of length " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " holding the counts of the different types that occurred in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "nsample" }, { "__type": "Text", "__tag": 4046, "value": " items." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The name " }, { "__type": "InlineCode", "__tag": 4051, "value": "colors" }, { "__type": "Text", "__tag": 4046, "value": " comes from a common description of the distribution: it is the probability distribution of the number of marbles of each color selected without replacement from an urn containing marbles of different colors; " }, { "__type": "InlineCode", "__tag": 4051, "value": "colors[i]" }, { "__type": "Text", "__tag": 4046, "value": " is the number of marbles in the urn with color " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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": null, "item_line": null, "item_type": "cython_function_or_method", "aliases": [ "numpy.random.Generator.multivariate_hypergeometric" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "colors = [16, 8, 4]\nseed = 4861946401452\ngen = np.random.Generator(np.random.PCG64(seed))\ngen.multivariate_hypergeometric(colors, 6)\ngen.multivariate_hypergeometric(colors, 6, size=3)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "gen.multivariate_hypergeometric(colors, 6, size=(2, 2))\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "hypergeometric", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._generator:Generator.hypergeometric" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Draw samples from the (univariate) hypergeometric distribution." } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "colors", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "nsample", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "size", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "marginals" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "multivariate_hypergeometric" }, "references": null, "qa": "numpy.random._generator:Generator.multivariate_hypergeometric", "arbitrary": [], "local_refs": [ "colors", "method", "nsample", "size", "variates" ] }