ak.to_dataframe
---------------
.. py:module: ak.to_dataframe
Defined in `awkward.operations.ak_to_dataframe <https://github.com/scikit-hep/awkward/blob/36da52cfa8846355c390beb6555eac1d31c27c26/src/awkward/operations/ak_to_dataframe.py>`__ on `line 24 <https://github.com/scikit-hep/awkward/blob/36da52cfa8846355c390beb6555eac1d31c27c26/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