Make your Pandas or Polars DataFrames Interactive with ITables 2.0

Published in

Jupyter Blog

4 min readMar 19, 2024

ITables, or Interactive Tables, is a MIT-licensed Python package that renders Python DataFrames using the DataTables JavaScript library. ITables 2.0, that I have just released, adds support for the DataTables Extensions. In this post we review the functionalities brought by this release.

How to use ITables, and what you get

ITables can be installed using either pip or conda:

pip install itables

conda install itables

ITables is essentially a Python wrapper for DataTables. We have managed to keep its dependencies to a minimum: ITables only requires IPython, pandas and numpy, which you must already have if you use Pandas in Jupyter (add polars and pyarrow if you wish to use ITables with Polars DataFrames).

To use ITables in your notebook, run this code snippet:

from itables import init_notebook_mode

init_notebook_mode(all_interactive=True)

After that, every Pandas or Polars DataFrame will be displayed using the DataTables library. With DataTables, you get an easier and more complete access to your data. You can expand the table, explore the various pages, sort the data or even search through it, without having to go back to the Python prompt.

A Pandas DataFrame rendered with ITables

To render only specific tables as interactive DataTables, or pass arguments to the DataTable constructor, you can use the show function:

from itables import show

A brief history of ITables

I started the ITables project back in 2019. The full changelog is available here, but let me highlight a few important milestones:

v1.0 (June 2022): Offline mode
v1.2 (Aug 2022): In addition to Jupyter Lab, Notebook, Book, HTML export, VS Code, PyCharm, Google Colab, RISE presentations, Voilà applications, ITables works in Shiny applications
v1.3.5 (Nov 2022): Large tables are fast too
v1.5 (March 2023): Polars DataFrames are supported
v1.6 (Sep 2023): Pandas Style objects can be displayed with ITables
v1.7 (Feb 2024): ITables works with Quarto
v2.0 (March 2024): ITables support the DataTables Extensions!

It took me much research (and two years I am afraid) to reach v2 and the DataTables Extensions. But we’re finally there! Let’s review what these extensions mean to your data workflow.

My favorite DataTables Extensions

Download your data!

If you think of a Jupyter Notebook, it might sound strange that we are considering downloading the table data, since we have it already in the Python session. Actually, ITables does not stop at the Notebook. The interactive DataTables continue to be interactive even if you export the notebook to an HTML document with e.g. Jupyter nbconvert (jupyter nbconvert --to html). The are also interactive in a RISE or Quarto presentation. ITables also works in Jupyter Book (which we use for the ITables documentation), and in interactive applications build with e.g. Voilà or Shiny.

Hopefully it’s clearer now why we might want to make the data downloadable! And the good news is that, with the Buttons extension of DataTables, is it as easy as:

show(df, buttons=["copyHtml5", "csvHtml5", "excelHtml5"])

Cascade search

The SearchPanes extension lets you proceed to a quick and visual search through the columns that have repeated values:

Search builder

I find the SearchBuilder extension very useful. Also, I love the option to set a pre-defined search and display only the part of the dataset we want to focus on.

Downsampling

Last but not least, I need to tell you about ITables’ down-sampling mechanism. By default, only a subset of the table with an estimated size of not more than 64kB (and not more than 200 columns) is displayed. You can change this with e.g.

import itables.options as opt

opt.maxBytes = 131072
opt.maxColumns = 0

You can tell whether your table was down-sampled by looking at the table summary at the bottom right of your table.

Please keep the following in mind: when down-sampling occurs, only a fraction of the data is passed on to DataTables, and hence the search or data export functions will only have access to that partial dataset.

Down-sampling is what makes ITables fast. Think twice before setting opt.maxBytes to a large number or to 0, as this might well freeze your notebook. Displaying a 1G DataFrame will make your notebook at least as big (probably bigger as the data is exported to JSON), and it's not clear that your browser will support this.

Acknowledgments

ITables would not exist without the beautiful DataTables JavaScript library. The DataTables library (MIT license) is authored and maintained by Allan Jardine. DataTables has a great documentation, many examples, and also a useful forum. Allan also provided precious advice on how to bundle the extensions with ITables.

The point in using DataTables in the context of data exploration and analysis had been demonstrated prior to ITables by the DT package for R.

Last but not least, ITables owes a lot to my brother François Wouts. François patiently helped me find a way to provide DataTables and its extensions that would be compatible with all the editors and rendering contexts that we want to support in ITables.