ak.sum
------

.. py:module: ak.sum

Defined in `awkward.operations.ak_sum <https://github.com/scikit-hep/awkward/blob/1f270435b3b969ae9b544a2d5788414723af534f/src/awkward/operations/ak_sum.py>`__ on `line 18 <https://github.com/scikit-hep/awkward/blob/1f270435b3b969ae9b544a2d5788414723af534f/src/awkward/operations/ak_sum.py#L18>`__.

.. py:function:: ak.sum(array, axis=None, *, keepdims=False, mask_identity=False, highlevel=True, behavior=None, attrs=None)


    :param array: Array-like data (anything :py:obj:`ak.to_layout` recognizes).
    :param axis: If None, combine all values from the array into
             a single scalar result; if an int, group by that axis: ``0`` is the
             outermost, ``1`` is the first level of nested lists, etc., and
             negative ``axis`` counts from the innermost: ``-1`` is the innermost,
             ``-2`` is the next level up, etc.
    :type axis: None or int
    :param keepdims: If False, this reducer decreases the number of
                 dimensions by 1; if True, the reduced values are wrapped in a new
                 length-1 dimension so that the result of this operation may be
                 broadcasted with the original array.
    :type keepdims: bool
    :param mask_identity: If True, reducing over empty lists results in
                      None (an option type); otherwise, reducing over empty lists
                      results in the operation's identity.
    :type mask_identity: bool
    :param highlevel: If True, return an :py:obj:`ak.Array`; otherwise, return
                  a low-level :py:obj:`ak.contents.Content` subclass.
    :type highlevel: bool
    :param behavior: Custom :py:obj:`ak.behavior` for the output array, if
                 high-level.
    :type behavior: None or dict
    :param attrs: Custom attributes for the output array, if
              high-level.
    :type attrs: None or dict

Sums over ``array`` (many types supported, including all Awkward Arrays
and Records). The identity of addition is ``0`` and it is usually not
masked. This operation is the same as NumPy's
`sum <https://docs.scipy.org/doc/numpy/reference/generated/numpy.sum.html>`__
if all lists at a given dimension have the same length and no None values,
but it generalizes to cases where they do not.

For example, consider this ``array``, in which all lists at a given dimension
have the same length.

.. code-block:: python


    >>> array = ak.Array([[ 0.1,  0.2,  0.3],
    ...                   [10.1, 10.2, 10.3],
    ...                   [20.1, 20.2, 20.3],
    ...                   [30.1, 30.2, 30.3]])

A sum over ``axis=-1`` combines the inner lists, leaving one value per
outer list:

.. code-block:: python


    >>> ak.sum(array, axis=-1)
    <Array [0.6, 30.6, 60.6, 90.6] type='4 * float64'>

while a sum over ``axis=0`` combines the outer lists, leaving one value
per inner list:

.. code-block:: python


    >>> ak.sum(array, axis=0)
    <Array [60.4, 60.8, 61.2] type='3 * float64'>

Now with some values missing,

.. code-block:: python


    >>> array = ak.Array([[ 0.1,  0.2      ],
    ...                   [10.1            ],
    ...                   [20.1, 20.2, 20.3],
    ...                   [30.1, 30.2      ]])

The sum over ``axis=-1`` results in

.. code-block:: python


    >>> ak.sum(array, axis=-1)
    <Array [0.3, 10.1, 60.6, 60.3] type='4 * float64'>

and the sum over ``axis=0`` results in

.. code-block:: python


    >>> ak.sum(array, axis=0)
    <Array [60.4, 50.6, 20.3] type='3 * float64'>

How we ought to sum over the innermost lists is unambiguous, but for all
other ``axis`` values, we must choose whether to align contents to the
left before summing, to the right before summing, or something else.
As suggested by the way the text has been aligned, we choose the
left-alignment convention: the first ``axis=0`` result is the sum of all
first elements

.. code-block:: python


    60.4 = 0.1 + 10.1 + 20.1 + 30.1

the second is the sum of all second elements

.. code-block:: python


    50.6 = 0.2 + 20.2 + 30.2

and the third is the sum of the only third element

.. code-block:: python


    20.3 = 20.3

The same is true if the values were None, rather than gaps:

.. code-block:: python


    >>> array = ak.Array([[ 0.1,  0.2, None],
    ...                   [10.1, None, None],
    ...                   [20.1, 20.2, 20.3],
    ...                   [30.1, 30.2, None]])

    >>> ak.sum(array, axis=-1)
    <Array [0.3, 10.1, 60.6, 60.3] type='4 * float64'>
    >>> ak.sum(array, axis=0)
    <Array [60.4, 50.6, 20.3] type='3 * float64'>

However, the missing value placeholder, None, allows us to align the
remaining data differently:

.. code-block:: python


    >>> array = ak.Array([[None,  0.1,  0.2],
    ...                   [None, None, 10.1],
    ...                   [20.1, 20.2, 20.3],
    ...                   [None, 30.1, 30.2]])

Now the ``axis=-1`` result is the same but the ``axis=0`` result has changed:

.. code-block:: python


    >>> ak.sum(array, axis=-1)
    <Array [0.3, 10.1, 60.6, 60.3] type='4 * float64'>
    >>> ak.sum(array, axis=0)
    <Array [20.1, 50.4, 60.8] type='3 * float64'>

because

.. code-block:: python


    20.1 = 20.1
    50.4 = 0.1 + 20.2 + 30.1
    60.8 = 0.2 + 10.1 + 20.3 + 30.2

If, instead of missing numbers, we had missing lists,

.. code-block:: python


    >>> array = ak.Array([[ 0.1,  0.2,  0.3],
    ...                   None,
    ...                   [20.1, 20.2, 20.3],
    ...                   [30.1, 30.2, 30.3]])

then the placeholder would pass through the ``axis=-1`` sum because summing
over the inner dimension shouldn't change the length of the outer
dimension.

.. code-block:: python


    >>> ak.sum(array, axis=-1)
    <Array [0.6, None, 60.6, 90.6] type='4 * ?float64'>

However, the ``axis=0`` sum loses information about the None value.

.. code-block:: python


    >>> ak.sum(array, axis=0)
    <Array [50.3, 50.6, 50.9] type='3 * float64'>

which is

.. code-block:: python


    50.3 = 0.1 + (None) + 20.1 + 30.1
    50.6 = 0.2 + (None) + 20.2 + 30.2
    50.9 = 0.3 + (None) + 20.3 + 30.3

An ``axis=0`` sum would be reducing that information if it had not been
None, anyway. If the None values were replaced with ``0``, the result for
``axis=0`` would be the same. The result for ``axis=-1`` would not be the
same because this None is in the ``0`` axis, not the axis that ``axis=-1``
sums over.

The ``keepdims`` parameter ensures that the number of dimensions does not
change: scalar results are put into new length-1 dimensions:

.. code-block:: python


    >>> ak.sum(array, axis=-1, keepdims=True)
    <Array [[0.6], None, [60.6], [90.6]] type='4 * option[1 * float64]'>
    >>> ak.sum(array, axis=0, keepdims=True)
    <Array [[50.3, 50.6, 50.9]] type='1 * var * float64'>

and ``axis=None`` ignores all None values and adds up everything in the
array (``keepdims`` has no effect).

.. code-block:: python


    >>> ak.sum(array, axis=None)
    151.8

The ``mask_identity``, which has no equivalent in NumPy, inserts None in
the output wherever a reduction takes place over zero elements. This is
different from reductions that are otherwise equal to the identity or
are equal to the identity by cancellation.

.. code-block:: python


    >>> array = ak.Array([[2.2, 2.2], [4.4, -2.2, -2.2], [], [0.0]])
    >>> ak.sum(array, axis=-1)
    <Array [4.4, 0, 0, 0] type='4 * float64'>
    >>> ak.sum(array, axis=-1, mask_identity=True)
    <Array [4.4, 0, None, 0] type='4 * ?float64'>

The third list is reduced to ``0`` if ``mask_identity=False`` because ``0`` is
the identity of addition, but it is reduced to None if
``mask_identity=True``.

See also :py:obj:`ak.nansum`.