mindspore.numpy.choose
=================================

.. image:: https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg
    :target: https://gitee.com/mindspore/mindspore/blob/master/docs/api/api_python/numpy/mindspore.numpy.choose.rst
    :alt: 查看源文件


.. py:function:: mindspore.numpy.choose(a, choices, mode='clip')

    从索引数组和要选择的数组列表构造一个新数组。给定一个包含整数的“索引”数组 ``a`` 和一个由n个数组（ ``choices`` ）组成的序列， ``a`` 和每个选择数组首先会根据需要广播为相同shape的数组；我们称这些数组为 ``Ba`` 和 ``Bchoices[i], i=0,…,n-1`` ，并且对于每个 ``i`` ，必然有 :math:`Ba.shape == Bchoices[i].shape` 。然后，按照以下方式创建一个新数组，shape为 ``Ba.shape`` ：

    - 如果 ``mode='raise'`` （默认值），那么首先， ``a`` （因此 ``Ba`` ）的每个元素必须在 ``[0, n-1]`` 范围内；假设 ``i`` （在该范围内）是 ``Ba`` 中 ``(j0, j1, ..., jm)`` 位置的值——那么新数组中相同位置的值就是 ``Bchoices[i]`` 在该位置的值；
    - 如果 ``mode='wrap'`` ，则 ``a`` （因此 ``Ba`` ）中的值可以是任何（带符号）整数；使用模运算将超出 ``[0, n-1]`` 范围的整数映射回该范围内；然后像上述一样构造新数组；
    - 如果 ``mode='clip'`` ，则 ``a`` （因此 ``Ba`` ）中的值可以是任何（带符号）整数；负整数被映射为0；大于 ``n-1`` 的值被映射为 ``n-1`` ；然后像上述一样构造新数组。

    .. note::
        不支持Numpy的 ``out`` 参数。不支持 ``mode = 'raise'`` ，默认 ``mode`` 为 ``'clip'`` 。

    参数：
        - **a** (int array) - 该数组必须包含 ``[0, n-1]`` 范围内的整数，其中 ``n`` 是选择数组的数量，除非使用 ``mode=wrap`` 或 ``mode=clip`` ，在这些情况下，任何整数都可以。
        - **choices** (数组的序列) - 选择数组。 ``a`` 和所有 ``choices`` 必须可以广播为相同的shape。如果 ``choices`` 本身是一个数组，则其最外层维度（即 ``choices.shape[0]`` 对应的维度）定义为“sequence”。
        - **mode** ('raise', 'wrap', 'clip', 可选) - 指定如何处理超出 ``[0, n-1]`` 范围的索引：
        
          - 'raise' - 抛出错误；
          - 'wrap' - 循环；
          - 'clip' - 限制在范围内。'clip'模式意味着所有过大的索引都将被替换为该轴最后一个元素的索引。请注意，这将禁止使用负数进行索引。

    返回：
        Tensor，合并的结果。

    异常：
        - **ValueError** - 如果 ``a`` 与任一 ``choices`` 不能被广播。