ak.ptp
------

.. py:module: ak.ptp

Defined in `awkward.operations.ak_ptp <https://github.com/scikit-hep/awkward/blob/bf1c8746812d55cb9cec23e954188044b9a7fcfc/src/awkward/operations/ak_ptp.py>`__ on `line 22 <https://github.com/scikit-hep/awkward/blob/bf1c8746812d55cb9cec23e954188044b9a7fcfc/src/awkward/operations/ak_ptp.py#L22>`__.

.. py:function:: ak.ptp(array, axis=None, *, keepdims=False, mask_identity=True, 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 of 0.
    :type mask_identity: bool

Returns the range of values in each group of elements from ``array`` (many
types supported, including all Awkward Arrays and Records). The range of
an empty list is None, unless ``mask_identity=False``, in which case it is 0.
This operation is the same as NumPy's
`ptp <https://docs.scipy.org/doc/numpy/reference/generated/numpy.ptp.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, with

.. code-block:: python


    >>> array = ak.Array([[0, 1, 2, 3],
    ...                   [          ],
    ...                   [4, 5      ]])

The range of the innermost lists is

.. code-block:: python


    >>> ak.ptp(array, axis=-1)
    <Array [3, None, 1] type='3 * ?int64'>

because there are three lists, the first has a range of ``3``, the second is
``None`` because the list is empty, and the third has a range of ``1``. Similarly,

.. code-block:: python


    >>> ak.ptp(array, axis=-1, mask_identity=False)
    <Array [3, 0, 1] type='3 * float64'>

The second value is ``0`` because the list is empty.

See :py:obj:`ak.sum` for a more complete description of nested list and missing
value (None) handling in reducers.