.. _op_ai_onnx_Scatter:

Scatter
=======

.. warning::
   This operator is **deprecated**.

- **Domain**: ``ai.onnx``
- **Since version**: 11

This operator is deprecated. Please use ScatterElements, which provides the same functionality.

Scatter takes three inputs ``data``, ``updates``, and ``indices`` of the same
rank r >= 1 and an optional attribute axis that identifies an axis of ``data``
(by default, the outer-most axis, that is axis 0). The output of the operation
is produced by creating a copy of the input ``data``, and then updating its value
to values specified by ``updates`` at specific index positions specified by
``indices``. Its output shape is the same as the shape of ``data``.

For each entry in ``updates``, the target index in ``data`` is obtained by combining
the corresponding entry in ``indices`` with the index of the entry itself: the
index-value for dimension = axis is obtained from the value of the corresponding
entry in ``indices`` and the index-value for dimension != axis is obtained from the
index of the entry itself.

For instance, in a 2-D tensor case, the update corresponding to the [i][j] entry
is performed as below:

.. code-block::

      output[indices[i][j]][j] = updates[i][j] if axis = 0,
      output[i][indices[i][j]] = updates[i][j] if axis = 1,


This operator is the inverse of GatherElements. It is similar to Torch's Scatter operation.

Example 1:

.. code-block::

      data = [
          [0.0, 0.0, 0.0],
          [0.0, 0.0, 0.0],
          [0.0, 0.0, 0.0],
      ]
      indices = [
          [1, 0, 2],
          [0, 2, 1],
      ]
      updates = [
          [1.0, 1.1, 1.2],
          [2.0, 2.1, 2.2],
      ]
      output = [
          [2.0, 1.1, 0.0]
          [1.0, 0.0, 2.2]
          [0.0, 2.1, 1.2]
      ]

Example 2:

.. code-block::

      data = [[1.0, 2.0, 3.0, 4.0, 5.0]]
      indices = [[1, 3]]
      updates = [[1.1, 2.1]]
      axis = 1
      output = [[1.0, 1.1, 3.0, 2.1, 5.0]]


**Inputs**

- **data** (*T*): Tensor of rank r >= 1.
- **indices** (*Tind*): Tensor of int32/int64 indices, of r >= 1 (same rank as input). All index values are expected to be within bounds [-s, s-1] along axis of size s. It is an error if any of the index values are out of bounds.
- **updates** (*T*): Tensor of rank r >=1 (same rank and shape as indices)

**Outputs**

- **output** (*T*): Tensor of rank r >= 1 (same rank as input).

**Attributes**

- **axis** (*int*): Which axis to scatter on. Negative value means counting dimensions from the back. Accepted range is [-r, r-1] where r = rank(data).

**Type Constraints**

- **T**: Input and output types can be of any tensor type.
  Allowed types: tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8).
- **Tind**: Constrain indices to integer types
  Allowed types: tensor(int32), tensor(int64).

Differences with previous version (9)
-------------------------------------

**SchemaDiff**: ``Scatter`` (domain ``'ai.onnx'``)

* old version: 9
* new version: 11
* breaking: **yes**

**Breaking reasons:**

* operator deprecated: False -> True

**Deprecation:**

* [BREAKING] deprecated False -> True

**Documentation:**

* line similarity: 0.60 (+28/-6 lines)

.. code-block:: diff

    --- Scatter v9
    +++ Scatter v11
    @@ -1,11 +1,30 @@
     
    -Given `data`, `updates` and `indices` input tensors of rank r >= 1, write the values provided by `updates`
    -into the first input, `data`, along `axis` dimension of `data` (by default outer-most one as axis=0) at corresponding `indices`.
    -For each entry in `updates`, the target index in `data` is specified by corresponding entry in `indices`
    -for dimension = axis, and index in source for dimension != axis. For instance, in a 2-D tensor case,
    -data[indices[i][j]][j] = updates[i][j] if axis = 0, or data[i][indices[i][j]] = updates[i][j] if axis = 1,
    -where i and j are loop counters from 0 up to the respective size in `updates` - 1.
    +This operator is deprecated. Please use ScatterElements, which provides the same functionality.
    +
    +Scatter takes three inputs `data`, `updates`, and `indices` of the same
    +rank r >= 1 and an optional attribute axis that identifies an axis of `data`
    +(by default, the outer-most axis, that is axis 0). The output of the operation
    +is produced by creating a copy of the input `data`, and then updating its value
    +to values specified by `updates` at specific index positions specified by
    +`indices`. Its output shape is the same as the shape of `data`.
    +
    +For each entry in `updates`, the target index in `data` is obtained by combining
    +the corresponding entry in `indices` with the index of the entry itself: the
    +index-value for dimension = axis is obtained from the value of the corresponding
    +entry in `indices` and the index-value for dimension != axis is obtained from the
    +index of the entry itself.
    +
    +For instance, in a 2-D tensor case, the update corresponding to the [i][j] entry
    +is performed as below:
    +```
    +  output[indices[i][j]][j] = updates[i][j] if axis = 0,
    +  output[i][indices[i][j]] = updates[i][j] if axis = 1,
    +```
    +
    +This operator is the inverse of GatherElements. It is similar to Torch's Scatter operation.
    +
     Example 1:
    +```
       data = [
           [0.0, 0.0, 0.0],
           [0.0, 0.0, 0.0],
    @@ -24,9 +43,12 @@
           [1.0, 0.0, 2.2]
           [0.0, 2.1, 1.2]
       ]
    +```
     Example 2:
    +```
       data = [[1.0, 2.0, 3.0, 4.0, 5.0]]
       indices = [[1, 3]]
       updates = [[1.1, 2.1]]
       axis = 1
       output = [[1.0, 1.1, 3.0, 2.1, 5.0]]
    +```

Version History
---------------

- :doc:`Version 9 <Scatter-9>`