Pandas DataFrames and Series as Interactive DataTables

Star

Turn pandas DataFrames and Series into interactive datatables in your notebooks!

Quick start

Install the package with

pip install itables

Activate the interactive mode for all series and dataframes with

from itables import init_notebook_mode
init_notebook_mode(all_interactive=True)

Then any dataframe will be displayed as an interactive datatables table:

import world_bank_data as wb

df = wb.get_countries()
df

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

If you want to display just one series or dataframe as an interactive table, use itables.show:

from itables import show

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

	SP.POP.TOTL
Loading... (need help?)

(NB: In Jupyter Notebook and Jupyter NBconvert, you need to call init_notebook_mode() before using show).

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

Supported environments

itables has been tested in the following editors:

• Jupyter Notebook
• Jupyter Lab
• Jupyter nbconvert (i.e. the tables are still interactive in the HTML export of a notebook)
• Google Colab
• VS Code (for both Jupyter Notebooks and Python scripts)
• PyCharm (for Jupyter Notebooks)

Table not loading?

If the table just says "Loading...", then maybe

• You loaded a notebook that is not trusted (run "Trust Notebook" in View / Activate Command Palette)
• Or you are offline?

At the moment itables does not have an offline mode. While the table data is embedded in the notebook, the jquery and datatables.net are loaded from a CDN, see our require.config and our table template, so an internet connection is required to display the tables.

Advanced usage

As itables is mostly a wrapper for the Javascript datatables.net library, you should be able to find help on the datatables.net forum and examples for most formatting issues.

Below we give a few examples of how the datatables.net examples can be translated to Python with itables.

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:

import pandas as pd
import itables.options as opt

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

a
Loading... (need help?)

Pagination

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:

import itables.options as opt

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

Show the table in full

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

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

Scroll

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

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

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.

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

Float precision

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

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
Loading... (need help?)

You may also choose to convert floating numbers to strings:

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

0
Loading... (need help?)

Advanced cell formatting with JS callbacks

You can use Javascript callbacks to set the cell or row style depending on the cell content.

The example below, in which we color in red the cells with negative numbers, is directly inspired by the corresponding datatables.net example.

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')
    }
}
""",
        }
    ],
    eval_functions=True,
)

a	b	c	d	e
Loading... (need help?)

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.

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

	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	Europe & Central Asia	Europe & Central Asia (excluding high income)	Europe & Central Asia (IDA & IBRD countries)	European Union	Fragile and conflict affected situations	Heavily indebted poor countries (HIPC)	High income	IBRD only	IDA & IBRD total	IDA blend	IDA only	IDA total	Late-demographic dividend	Latin America & Caribbean	Latin America & Caribbean (excluding high income)	Latin America & the Caribbean (IDA & IBRD countries)	Least developed countries: UN classification	Low & middle income	Low income	Lower middle income	Middle East & North Africa	Middle East & North Africa (excluding high income)	Middle East & North Africa (IDA & IBRD countries)	Middle income	North America	Not classified	OECD members	Other small states	Pacific island small states	Post-demographic dividend	Pre-demographic dividend	Small states	South Asia	South Asia (IDA & IBRD)	Sub-Saharan Africa	Sub-Saharan Africa (excluding high income)	Sub-Saharan Africa (IDA & IBRD countries)	Upper middle income	World	Afghanistan	Albania	Algeria	American Samoa	Andorra	Angola	Antigua and Barbuda	Argentina	Armenia	Aruba	Australia	Austria	Azerbaijan	Bahamas, The	Bahrain	Bangladesh	Barbados	Belarus	Belgium	Belize	Benin	Bermuda	Bhutan	Bolivia	Bosnia and Herzegovina	Botswana	Brazil	British Virgin Islands	Brunei Darussalam	Bulgaria	Burkina Faso	Burundi	Cabo Verde	Cambodia	Cameroon	Canada	Cayman Islands	Central African Republic	Chad	Channel Islands	Chile	China	Colombia	Comoros	Congo, Dem. Rep.	Congo, Rep.	Costa Rica	Cote d'Ivoire	Croatia	Cuba	Curacao	Cyprus	Czech Republic	Denmark	Djibouti	Dominica	Dominican Republic	Ecuador	Egypt, Arab Rep.	El Salvador	Equatorial Guinea	Eritrea	Estonia	Eswatini	Ethiopia	Faroe Islands	Fiji	Finland	France	French Polynesia	Gabon	Gambia, The	Georgia	Germany	Ghana	Gibraltar	Greece	Greenland	Grenada	Guam	Guatemala	Guinea	Guinea-Bissau	Guyana	Haiti	Honduras	Hong Kong SAR, China	Hungary	Iceland	India	Indonesia	Iran, Islamic Rep.	Iraq	Ireland	Isle of Man	Israel	Italy	Jamaica	Japan	Jordan	Kazakhstan	Kenya	Kiribati	Korea, Dem. People's Rep.	Korea, Rep.	Kosovo	Kuwait	Kyrgyz Republic	Lao PDR	Latvia	Lebanon	Lesotho	Liberia	Libya	Liechtenstein	Lithuania	Luxembourg	Macao SAR, China	Madagascar	Malawi	Malaysia	Maldives	Mali	Malta	Marshall Islands	Mauritania	Mauritius	Mexico	Micronesia, Fed. Sts.	Moldova	Monaco	Mongolia	Montenegro	Morocco	Mozambique	Myanmar	Namibia	Nauru	Nepal	Netherlands	New Caledonia	New Zealand	Nicaragua	Niger	Nigeria	North Macedonia	Northern Mariana Islands	Norway	Oman	Pakistan	Palau	Panama	Papua New Guinea	Paraguay	Peru	Philippines	Poland	Portugal	Puerto Rico	Qatar	Romania	Russian Federation	Rwanda	Samoa	San Marino	Sao Tome and Principe	Saudi Arabia	Senegal	Serbia	Seychelles	Sierra Leone	Singapore	Sint Maarten (Dutch part)	Slovak Republic	Slovenia	Solomon Islands	Somalia	South Africa	South Sudan	Spain	Sri Lanka	St. Kitts and Nevis	St. Lucia	St. Martin (French part)	St. Vincent and the Grenadines	Sudan	Suriname	Sweden	Switzerland	Syrian Arab Republic	Tajikistan	Tanzania	Thailand	Timor-Leste	Togo	Tonga	Trinidad and Tobago	Tunisia	Turkey	Turkmenistan	Turks and Caicos Islands	Tuvalu	Uganda	Ukraine	United Arab Emirates	United Kingdom	United States	Uruguay	Uzbekistan	Vanuatu	Venezuela, RB	Vietnam	Virgin Islands (U.S.)	West Bank and Gaza	Yemen, Rep.	Zambia	Zimbabwe
Loading... (need help?)

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

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

or globally by setting opt.columnDefs:

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

	iso2Code	name	region	adminregion	incomeLevel	lendingType	capitalCity	longitude	latitude
Loading... (need help?)

del opt.columnDefs

HTML in cells

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
Loading... (need help?)

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.

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

24000

df

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

	name	unit	topics
Loading... (need help?)

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

show(df, maxBytes=0)

	name	unit	source	sourceNote	sourceOrganization	topics
Loading... (need help?)

or globally:

opt.maxBytes = 2**20
df

	name	unit	source	sourceNote	sourceOrganization	topics
Loading... (need help?)

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.

Alternatives

ITables uses basic Javascript. 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.

Please also checkout D-Tale for exploring your Python DataFrames in the browser, using a local server.