{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To reduce the chance of misinterpretation, even though the following \"abuse\" is nominally supported, " }, { "__type": "ParamRef", "__tag": 4071, "name": "choices" }, { "__type": "Text", "__tag": 4046, "value": " should neither be, nor be thought of as, a single array, i.e., the outermost sequence-like container should be either a list or a tuple." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError: shape mismatch", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " and each choice array are not all broadcastable to the same shape." } ] } ] } ] } ], "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": "merged_array", "annotation": "array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The merged result." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct an array from an index array and a list of arrays to choose from." } ] } ], "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": "a", "annotation": "int array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This array must contain integers in " }, { "__type": "InlineCode", "__tag": 4051, "value": "[0, n-1]" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " is the number of choices, unless " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode=wrap" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode=clip" }, { "__type": "Text", "__tag": 4046, "value": ", in which cases any integers are permissible." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "choices", "annotation": "sequence of arrays", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Choice arrays. " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " and all of the choices must be broadcastable to the same shape. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "choices" }, { "__type": "Text", "__tag": 4046, "value": " is itself an array (not recommended), then its outermost dimension (i.e., the one corresponding to " }, { "__type": "InlineCode", "__tag": 4051, "value": "choices.shape[0]" }, { "__type": "Text", "__tag": 4046, "value": ") is taken as defining the \"sequence\"." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "out", "annotation": "array, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. Note that " }, { "__type": "ParamRef", "__tag": 4071, "name": "out" }, { "__type": "Text", "__tag": 4046, "value": " is always buffered if " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode='raise'" }, { "__type": "Text", "__tag": 4046, "value": "; use other modes for better performance." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mode", "annotation": "{'raise' (default), 'wrap', 'clip'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specifies how indices outside " }, { "__type": "InlineCode", "__tag": 4051, "value": "[0, n-1]" }, { "__type": "Text", "__tag": 4046, "value": " will be treated:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'raise'an exception is raised" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'wrap'value becomes value mod " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'clip'values < 0 are mapped to 0, values > n-1 are mapped to n-1" } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "First of all, if confused or uncertain, definitely look at the Examples - in its full generality, this function is less simple than it might seem from the following code description " } ] }, { "__type": "Code", "__tag": 4050, "value": "np.choose(a,c) == np.array([c[a[I]][I] for I in np.ndindex(a.shape)])", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "But this omits some subtleties. Here is a fully general summary:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given an \"index\" array (" }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": ") of integers and a sequence of " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " arrays (" }, { "__type": "ParamRef", "__tag": 4071, "name": "choices" }, { "__type": "Text", "__tag": 4046, "value": "), " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " and each choice array are first broadcast, as necessary, to arrays of a common shape; calling these " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Ba" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Bchoices[i], i =\n0,...,n-1" } ] }, { "__type": "Text", "__tag": 4046, "value": " we have that, necessarily, " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ba.shape == Bchoices[i].shape" }, { "__type": "Text", "__tag": 4046, "value": " for each " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": ". Then, a new array with shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ba.shape" }, { "__type": "Text", "__tag": 4046, "value": " is created as follows:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "if " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode='raise'" }, { "__type": "Text", "__tag": 4046, "value": " (the default), then, first of all, each element of " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " (and thus " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ba" }, { "__type": "Text", "__tag": 4046, "value": ") must be in the range " }, { "__type": "InlineCode", "__tag": 4051, "value": "[0, n-1]" }, { "__type": "Text", "__tag": 4046, "value": "; now, suppose that " }, { "__type": "InlineCode", "__tag": 4051, "value": "i" }, { "__type": "Text", "__tag": 4046, "value": " (in that range) is the value at the " }, { "__type": "InlineCode", "__tag": 4051, "value": "(j0, j1, ..., jm)" }, { "__type": "Text", "__tag": 4046, "value": " position in " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ba" }, { "__type": "Text", "__tag": 4046, "value": " - then the value at the same position in the new array is the value in " }, { "__type": "InlineCode", "__tag": 4051, "value": "Bchoices[i]" }, { "__type": "Text", "__tag": 4046, "value": " at that same position;" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "if " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode='wrap'" }, { "__type": "Text", "__tag": 4046, "value": ", values in " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " (and thus " }, { "__type": "InlineRole", "__tag": 4003, "value": "Ba", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ") may be any (signed) integer; modular arithmetic is used to map integers outside the range " }, { "__type": "InlineRole", "__tag": 4003, "value": "[0, n-1]", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " back into that range; and then the new array is constructed as above;" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "if " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode='clip'" }, { "__type": "Text", "__tag": 4046, "value": ", values in " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " (and thus " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ba" }, { "__type": "Text", "__tag": 4046, "value": ") may be any (signed) integer; negative integers are mapped to 0; values greater than " }, { "__type": "InlineCode", "__tag": 4051, "value": "n-1" }, { "__type": "Text", "__tag": 4046, "value": " are mapped to " }, { "__type": "InlineCode", "__tag": 4051, "value": "n-1" }, { "__type": "Text", "__tag": 4046, "value": "; and then the new array is constructed as above." } ] } ] } ] } ], "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": "/numpy/_core/fromnumeric.py", "item_line": 308, "item_type": "_ArrayFunctionDispatcher", "aliases": [ "numpy.choose" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nchoices = [[0, 1, 2, 3], [10, 11, 12, 13],\n [20, 21, 22, 23], [30, 31, 32, 33]]\nnp.choose([2, 3, 1, 0], choices\n# the first element of the result will be the first element of the\n# third (2+1) \"array\" in choices, namely, 20; the second element\n# will be the second element of the fourth (3+1) choice array, i.e.,\n# 31, etc.\n)\nnp.choose([2, 4, 1, 0], choices, mode='clip') # 4 goes to 3 (4-1)\nnp.choose([2, 4, 1, 0], choices, mode='wrap') # 4 goes to (4 mod 4)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nA couple examples illustrating how choose broadcasts:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = [[1, 0, 1], [0, 1, 0], [1, 0, 1]]\nchoices = [-10, 10]\nnp.choose(a, choices)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.array([0, 1]).reshape((2,1,1))\nc1 = np.array([1, 2, 3]).reshape((1,3,1))\nc2 = np.array([-1, -2, -3, -4, -5]).reshape((1,1,5))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.choose(a, (c1, c2)) # result is 2x3x5, res[0,:,:]=c1, res[1,:,:]=c2\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "ndarray.choose", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "ndarray.choose" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "equivalent method" } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "numpy.take_along_axis", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:take_along_axis" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Preferable if " }, { "__type": "InlineRole", "__tag": 4003, "value": "choices", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is an array" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "choices", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "out", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "mode", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "raise" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "choose" }, "references": null, "qa": "numpy:choose", "arbitrary": [], "local_refs": [ "a", "choices", "merged_array", "mode", "out" ] }