Metadata-Version: 2.1
Name: df2img
Version: 0.2.3
Summary: Save a Pandas DataFrame as image
Home-page: https://github.com/andreas-vester/df2img
License: MIT
Keywords: pandas,dataframe,image
Author: Andreas Vester
Author-email: andreas@vester-online.de
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: docs
Requires-Dist: ipykernel (>=6.5.1,<7.0.0); extra == "docs"
Requires-Dist: ipython (>=7.29.0,<8.0.0); extra == "docs"
Requires-Dist: jupyter (>=1.0.0,<2.0.0); extra == "docs"
Requires-Dist: kaleido (==0.2.1)
Requires-Dist: nbsphinx (>=0.8.7,<0.9.0); extra == "docs"
Requires-Dist: numpydoc (>=1.1.0,<2.0.0); extra == "docs"
Requires-Dist: pandas (>=1.3.4,<2.0.0)
Requires-Dist: pandoc (>=1.1.0,<2.0.0); extra == "docs"
Requires-Dist: plotly (>=5.3.1,<6.0.0)
Requires-Dist: sphinx (>=4.3.0,<5.0.0); extra == "docs"
Requires-Dist: sphinx-copybutton (>=0.4.0,<0.5.0); extra == "docs"
Requires-Dist: sphinx-rtd-theme (>=1.0.0,<2.0.0); extra == "docs"
Project-URL: Repository, https://github.com/andreas-vester/df2img
Description-Content-Type: text/x-rst

########################################
df2img: Save a Pandas DataFrame as image
########################################

What is it all about?
*********************
| Have you ever tried to save a ``pd.DataFrame`` into an image file? This is not a straightforward process at all. Unfortunately, ``pandas`` itself doesn't provide this functionality out of the box.

| **df2img** tries to fill the gap. It is a Python library that greatly simplifies the process of saving a ``pd.DataFrame`` into an image file (e.g. ``png`` or ``jpg``).

It is a wrapper/convenience function in order to create a ``plotly`` Table. That is, one can use ``plotly``'s styling function to format the table.

Dependencies
************
**df2img** has a limited number of dependencies, namely

- ``pandas``
- ``plotly``
- ``kaleido``

Documentation
*************
An extensive documentation is available at https://df2img.readthedocs.io/.

Quickstart
**********

You can install the package via ``pip``.

.. code-block:: python

    pip install df2img

Using ``poetry``?

.. code-block:: python

    poetry add df2img

Let's create a simple ``pd.DataFrame`` with some dummy data:

.. code-block:: python

    import pandas as pd

    import df2img

    df = pd.DataFrame(
        data=dict(
            float_col=[1.4, float("NaN"), 250, 24.65],
            str_col=("string1", "string2", float("NaN"), "string4"),
        ),
        index=["row1", "row2", "row3", "row4"],
    )

.. code-block:: python

          float_col  str_col
    row1       1.40  string1
    row2        NaN  string2
    row3     250.00      NaN
    row4      24.65  string4

Basics
------

Saving ``df`` into a png-file now takes just two lines of code including some styling out of the box.

* First, we create a ``plotly`` figure.
* Second, we save the figure to disk.

.. code-block:: python

    fig = df2img.plot_dataframe(df, fig_size=(500, 140))

    df2img.save_dataframe(fig=fig, filename="plot1.png")


.. image:: ./docs/source/images/plot1.png
    :alt: plot1.png

Formatting
----------

You can control the settings for the header row via the ``tbl_header`` input argument. This accepts a regular ``dict``.
This ``dict`` can comprise various key/value pairs that are also accepted by ``plotly``. All available key/value pairs
can be seen at ``plotly``'s website at https://plotly.com/python/reference/table/#table-header.

Let's set the header row in a different color and size. Also, let's set the alignment to "left".

.. code-block:: python

    fig = df2img.plot_dataframe(
        df,
        tbl_header=dict(
            align="left",
            fill_color="blue",
            font_color="white",
            font_size=14,
        ),
        fig_size=(500, 140),
    )

.. image:: ./docs/source/images/plot2.png
    :alt: plot2.png


Controlling the table body (cells) is basically the same. Just use the ``tbl_cells`` input argument, which happens to be
a ``dict``, too. See https://plotly.com/python/reference/table/#table-cells for all the possible key/value pairs.

Let's print the table cell values in yellow on a green background and align them "right".

.. code-block:: python

    fig = df2img.plot_dataframe(
        df,
        tbl_cells=dict(
            align="right",
            fill_color="green",
            font_color="yellow",
        ),
        fig_size=(500, 140),
    )

.. image:: ./docs/source/images/plot3.png
    :alt: plot3.png


You can alternate row colors for better readability by using the ``row_fill_color`` input argument. Using HEX colors is also possible:

.. code-block:: python

    fig = df2img.plot_dataframe(
        df,
        row_fill_color=("#ffffff", "#d7d8d6"),
        fig_size=(500, 140),
    )

.. image:: ./docs/source/images/plot4.png
    :alt: plot4.png


Setting the title will be controlled via the ``title`` input argument. You can find the relevant key/value pairs here:
https://plotly.com/python/reference/layout/#layout-title.

Let's put the title in a different font and size. In addition, we can control the alignment via the ``x`` key/value pair.
It sets the x (horizontal) position in normalized coordinates from "0" (left) to "1" (right).

.. code-block:: python

    fig = df2img.plot_dataframe(
        df,
        title=dict(
            font_color="darkred",
            font_family="Times New Roman",
            font_size=24,
            text="This is a title starting at the x-value x=0.1",
            x=0.1,
            xanchor="left",
        ),
        fig_size=(500, 140),
    )

.. image:: ./docs/source/images/plot5.png
    :alt: plot5.png


You can also control relative column width via the ``col_width`` argument. Let's set the first column's width triple
the width of the third column and the second column's width double the width of the third column.

.. code-block:: python

    fig = df2img.plot_dataframe(
        df,
        col_width=[3, 2, 1],
        fig_size=(500, 140),
    )

.. image:: ./docs/source/images/plot6.png
    :alt: plot6.png

Contributing to df2img
**********************
All bug reports and bug fixes, improvements to the documentation, or general ideas are welcome. Simply open an
`issue <https://github.com/andreas-vester/df2img/issues>`_.

