Pandas DataFrames and Series as Interactive Tables in Jupyter¶

Star

Turn pandas DataFrames and Series into interactive datatables in both your notebooks and their HTML representation with import itables.interactive:

Quick start¶

Install the package with

pip install itables

In Jupyter Lab, load the require Javascript library (this is not required in Jupyter Notebook):

In [1]:

# This is required only in Jupyter Lab - don't do this in Jupyter Notebook
# A PR is welcome if you know how to avoid this.
# See https://github.com/mwouts/itables/issues/3
from IPython.display import HTML, display
from time import sleep

display(HTML("""
<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
"""))

sleep(0.1)

Activate the interactive mode for all series and dataframes with

In [2]:

from itables import init_notebook_mode
init_notebook_mode(all_interactive=True)

In [3]:

import world_bank_data as wb

df = wb.get_countries()
df

Out[3]:

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

You don't see any table above? Please either open the HTML export of this notebook, or run this README on Binder!

Or display just one series or dataframe as an interactive table with the show function.

In [4]:

from itables import show

x = wb.get_series("SP.POP.TOTL", mrv=1, simplify_index=True)
show(x)

	SP.POP.TOTL
Country

Advanced usage¶

Row sorting¶

Select the order in which the row are sorted with the datatables' order argument. By default, the rows are sorted according to the first column (order = [[0, 'asc']]).

If you want to deactivate the sorting, set order = [], either in the show method, or as a global option:

In [5]:

import pandas as pd
import itables.options as opt

opt.order = []  # no sorting
pd.DataFrame({'a':[2,1]})

Out[5]:

a

How many rows per page¶

Select how many entries should appear at once in the table with either the lengthMenu argument of the show function, or with the global option itables.options.lengthMenu:

In [6]:

import itables.options as opt

opt.lengthMenu = [2, 5, 10, 20, 50, 100, 200, 500]
df

Out[6]:

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

Show the table in full¶

Show the table in full with the paging argument, either in the show method, or in the options:

In [7]:

show(df.head(), paging=False)

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

Scroll¶

If you prefer to replace the pagination with a vertical scroll, use for instance

In [8]:

show(df, scrollY="200px", scrollCollapse=True, paging=False)

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

Table and cell style¶

Select how your table should look like with the classes argument of the show function, or by changing itables.options.classes. For the list of possible values, see datatables' default style and the style examples.

In [9]:

opt.classes = ["display", "nowrap"]
df

Out[9]:

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

In [10]:

opt.classes = ["display", "cell-border"]
df

Out[10]:

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

Float precision¶

Floats are rounded using pd.options.display.float_format. Please change that format according to your preference.

In [11]:

import math
import pandas as pd

with pd.option_context("display.float_format", "{:,.2f}".format):
    show(pd.Series([i * math.pi for i in range(1, 6)]))

0

You may also choose to convert floating numbers to strings:

In [12]:

with pd.option_context("display.float_format", "${:,.2f}".format):
    show(pd.Series([i * math.pi for i in range(1, 6)]))

0

Advanced cell formatting¶

Datatables allows to set the cell or row style depending on the cell content, with either the createdRow or createdCell callback. For instance, if we want the cells with negative numbers to be colored in red, we can use the columnDefs.createdCell argument as follows:

In [13]:

show(
    pd.DataFrame([[-1, 2, -3, 4, -5], [6, -7, 8, -9, 10]], columns=list("abcde")),
    columnDefs=[
        {
            "targets": "_all",
            "createdCell": """function (td, cellData, rowData, row, col) {
      if ( cellData < 0 ) {
        $(td).css('color', 'red')
      }
    }""",
        }
    ],
)

a	b	c	d	e

Column width¶

For tables that are larger than the notebook, the columnDefs argument allows to specify the desired width. If you wish you can also change the default in itables.options.

In [14]:

show(x.to_frame().T, columnDefs=[{"width": "120px", "targets": "_all"}])

WARNING:itables.downsample:showing 1x20 of 1x266 as maxColumns=20. See https://mwouts.github.io/itables/#downsampling

Country	Africa Eastern and Southern	Africa Western and Central	Arab World	Caribbean small states	Central Europe and the Baltics	Early-demographic dividend	East Asia & Pacific	East Asia & Pacific (excluding high income)	East Asia & Pacific (IDA & IBRD countries)	Euro area	Uruguay	Uzbekistan	Vanuatu	Venezuela, RB	Vietnam	Virgin Islands (U.S.)	West Bank and Gaza	Yemen, Rep.	Zambia	Zimbabwe

Cell alignment¶

You can use the datatables.net cell classes like dt-left, dt-center, dt-right etc to set the cell alignment. Specify it for one table by using the columnDefs argument of show

In [15]:

show(df, columnDefs=[{"className":"dt-center",  "targets": "_all"}])

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

or globally by setting opt.columnDefs:

In [16]:

opt.columnDefs = [{"className":"dt-center", "targets": "_all"}]
df

Out[16]:

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
id

In [17]:

del opt.columnDefs

HTML in cells¶

In [18]:

import pandas as pd

show(
    pd.Series(
        [
            "<b>bold</b>",
            "<i>italic</i>",
            '<a href="https://github.com/mwouts/itables">link</a>',
        ],
        name="HTML",
    ),
    paging=False,
)

HTML

Select rows¶

Not currently implemented. May be made available at a later stage using the select extension for datatables.

Copy, CSV, PDF and Excel buttons¶

Not currently implemented. May be made available at a later stage thanks to the buttons extension for datatable.

Downsampling ¶

When the data in a table is larger than maxBytes, which is equal to 64KB by default, itables will display only a subset of the table - one that fits into maxBytes. If you wish, you can deactivate the limit with maxBytes=0, change the value of maxBytes, or similarly set a limit on the number of rows (maxRows, defaults to 0) or columns (maxColumns, defaults to pd.get_option('display.max_columns')).

Note that datatables support server-side processing. At a later stage we may implement support for larger tables using this feature.

In [19]:

df = wb.get_indicators().head(500)
opt.maxBytes = 10000
df.values.nbytes

Out[19]:

In [20]:

df

WARNING:itables.downsample:showing 250x3 of 500x6 as nbytes=24000>10000=maxBytes. See https://mwouts.github.io/itables/#downsampling

Out[20]:

	name	unit	topics
id

To show the table in full, we can modify the value of maxBytes either locally:

In [21]:

show(df, maxBytes=0)

	name	unit	source	sourceNote	sourceOrganization	topics
id

or globally:

In [22]:

opt.maxBytes = 2**20
df

Out[22]:

	name	unit	source	sourceNote	sourceOrganization	topics
id

References¶

DataTables¶

DataTables is a plug-in for the jQuery Javascript library. It has a great documentation, and a large set of examples.
The R package DT uses datatables.net as the underlying library for both R notebooks and Shiny applications. In addition to the standard functionalities of the library (display, sort, filtering and row selection), RStudio seems to have implemented cell edition.
Marek Cermak has an interesting tutorial on how to use datatables within Jupyter. He also published jupyter-datatables, with a focus on numerical data and distribution plots.

Alternatives¶

ITables uses basic Javascript, and because of this it will only work in Jupyter Notebook, not in JupyterLab. It is not a Jupyter widget, which means that it does not allows you to edit the content of the dataframe.

If you are looking for Jupyter widgets, have a look at

QGrid by Quantopian
IPyaggrid by Louis Raison and Olivier Borderies
IPySheet by QuantStack.

If you are looking for a table component that will fit in Dash applications, see datatable by Dash.

Contributing¶

I think it would be very helpful to have an identical table component for both Jupyter and Dash. Please let us know if you are interested in drafting a new table component based on an existing Javascript library for Dash.

Also, if you happen to prefer another Javascript table library (say, ag-grid), and you would like to see it supported in itables, please open either an issue or a PR, and let us know what is the minimal code to display a table in Jupyter using your library.