ak.num
------

.. py:module: ak.num

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

.. py:function:: ak.num(array, axis=1, *, highlevel=True, behavior=None, attrs=None)


    :param array: Array-like data (anything :py:obj:`ak.to_layout` recognizes).
    :param axis: The dimension at which this operation is applied. The
             outermost dimension is ``0``, followed by ``1``, etc., and negative
             values count backward from the innermost: ``-1`` is the innermost
             dimension, ``-2`` is the next level up, etc.
    :type axis: int
    :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

Returns an array of integers specifying the number of elements at a
particular level.

For instance, given the following doubly nested ``array``,

.. code-block:: python


    >>> array = ak.Array([[[1.1, 2.2, 3.3],
    ...                    [],
    ...                    [4.4, 5.5],
    ...                    [6.6]
    ...                   ],
    ...                   [],
    ...                   [[7.7],
    ...                    [8.8, 9.9]]
    ...                   ])

The number of elements in ``axis=1`` is

.. code-block:: python


    >>> ak.num(array, axis=1)
    <Array [4, 0, 2] type='3 * int64'>

and the number of elements at the next level down, ``axis=2``, is

.. code-block:: python


    >>> ak.num(array, axis=2)
    <Array [[3, 0, 2, 1], [], [1, 2]] type='3 * var * int64'>

The ``axis=0`` case is special: it returns a scalar, the length of the array.

.. code-block:: python


    >>> ak.num(array, axis=0)
    3

This function is useful for ensuring that slices do not raise errors. For
instance, suppose that we want to select the first element from each
of the outermost nested lists of ``array``. One of these lists is empty, so
selecting the first element (``0``) would raise an error. However, if our
first selection is ``ak.num(array) > 0``, we are left with only those lists
that *do* have a first element:

.. code-block:: python


    >>> array[ak.num(array) > 0, 0]
    <Array [[1.1, 2.2, 3.3], [7.7]] type='2 * var * float64'>

To keep a placeholder (None) in each place we do not want to select,
consider using :py:obj:`ak.mask` instead of a :py:obj:`ak.Array.__getitem__`.

.. code-block:: python


    >>> array.mask[ak.num(array) > 0][:, 0]
    <Array [[1.1, 2.2, 3.3], None, [7.7]] type='3 * option[var * float64]'>