ak.to_dataframe
---------------

.. py:module: ak.to_dataframe

Defined in `awkward.operations.ak_to_dataframe <https://github.com/scikit-hep/awkward/blob/76cb66b946cbf2ae355bddf2530b323465395bae/src/awkward/operations/ak_to_dataframe.py>`__ on `line 24 <https://github.com/scikit-hep/awkward/blob/76cb66b946cbf2ae355bddf2530b323465395bae/src/awkward/operations/ak_to_dataframe.py#L24>`__.

.. py:function:: ak.to_dataframe(array, *, how='inner', levelname=_default_levelname, anonymous='values')


    :param array: Array-like data (anything :py:obj:`ak.to_layout` recognizes).
    :param how: Passed to
            `pd.merge <https://pandas.pydata.org/pandas-docs/version/1.0.3/reference/api/pandas.merge.html>`__
            to combine DataFrames for each multiplicity into one DataFrame. If
            None, a list of Pandas DataFrames is returned.
    :type how: None or str
    :param levelname: Computes a name for each level of the row index
                  from the number of levels deep.
    :type levelname: int -> str
    :param anonymous: Column name to use if the ``array`` does not contain
                  records; otherwise, column names are derived from record fields.
    :type anonymous: str

Converts Awkward data structures into Pandas
`MultiIndex <https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html>`__
rows and columns. The resulting DataFrame(s) contains no Awkward structures.

:py:obj:`ak.Array` structures can't be losslessly converted into a single DataFrame;
different fields in a record structure might have different nested list
lengths, but a DataFrame can have only one index.

If ``how`` is None, this function always returns a list of DataFrames (even
if it contains only one DataFrame); otherwise ``how`` is passed to
`pd.merge <https://pandas.pydata.org/pandas-docs/version/1.0.3/reference/api/pandas.merge.html>`__
to merge them into a single DataFrame with the associated loss of data.

In the following example, nested lists are converted into MultiIndex rows.
The index level names ``"entry"``, ``"subentry"`` and ``"subsubentry"`` can be
controlled with the ``levelname`` parameter. The column name ``"values"`` is
assigned because this array has no fields; it can be controlled with the
``anonymous`` parameter.

.. code-block:: python


    >>> ak.to_dataframe(ak.Array([[[1.1, 2.2], [], [3.3]],
    ...                           [],
    ...                           [[4.4], [5.5, 6.6]],
    ...                           [[7.7]],
    ...                           [[8.8]]]))
                                values
    entry subentry subsubentry
    0     0        0               1.1
                   1               2.2
          2        0               3.3
    2     0        0               4.4
          1        0               5.5
                   1               6.6
    3     0        0               7.7
    4     0        0               8.8

In this example, nested records are converted into MultiIndex columns.
(MultiIndex rows and columns can be mixed; these examples are deliberately
simple.)

.. code-block:: python


    >>> ak.to_dataframe(ak.Array([
    ...     {"I": {"a": _, "b": {"i": _}}, "II": {"x": {"y": {"z": _}}}}
    ...     for _ in range(0, 50, 10)]))
            I      II
            a   b   x
                i   y
                    z
    entry
    0       0   0   0
    1      10  10  10
    2      20  20  20
    3      30  30  30
    4      40  40  40

The following two examples show how fields of different length lists are
merged. With ``how="inner"`` (default), only subentries that exist for all
fields are preserved; with ``how="outer"``, all subentries are preserved at
the expense of requiring missing values.

.. code-block:: python


    >>> ak.to_dataframe(ak.Array([{"x": [], "y": [4.4, 3.3, 2.2, 1.1]},
    ...                           {"x": [1], "y": [3.3, 2.2, 1.1]},
    ...                           {"x": [1, 2], "y": [2.2, 1.1]},
    ...                           {"x": [1, 2, 3], "y": [1.1]},
    ...                           {"x": [1, 2, 3, 4], "y": []}]),
    ...                          how="inner")
                    x    y
    entry subentry
    1     0         1  3.3
    2     0         1  2.2
          1         2  1.1
    3     0         1  1.1

The same with ``how="outer"``:

.. code-block:: python


    >>> ak.to_dataframe(ak.Array([{"x": [], "y": [4.4, 3.3, 2.2, 1.1]},
    ...                           {"x": [1], "y": [3.3, 2.2, 1.1]},
    ...                           {"x": [1, 2], "y": [2.2, 1.1]},
    ...                           {"x": [1, 2, 3], "y": [1.1]},
    ...                           {"x": [1, 2, 3, 4], "y": []}]),
    ...                          how="outer")
                      x    y
    entry subentry
    0     0         NaN  4.4
          1         NaN  3.3
          2         NaN  2.2
          3         NaN  1.1
    1     0         1.0  3.3
          1         NaN  2.2
          2         NaN  1.1
    2     0         1.0  2.2
          1         2.0  1.1
    3     0         1.0  1.1
          1         2.0  NaN
          2         3.0  NaN
    4     0         1.0  NaN
          1         2.0  NaN
          2         3.0  NaN
          3         4.0  NaN