Turn pandas DataFrames and Series into interactive datatables in both your notebooks and their HTML representation with a single additional import:
import itables.interactive
import world_bank_data as wb
df = wb.get_countries()
df
You don't see any table above? Please either open the HTML export of this notebook, or run this README on Binder!
Quick start¶
Install the package with
Activate the interactive mode for all series and dataframes with
import itables.interactive
Display just one series or dataframe as an interactive table with the show function.
from itables import show
x = wb.get_series("SP.POP.TOTL", mrv=1, simplify_index=True)
show(x)
Advanced usage¶
Pagination¶
How many rows per page¶
Select how many entries should appear at once in the table with the lengthMenu argument of the show function, or by changing itables.options.default:
import itables.options as opt
opt.lengthMenu = [2, 5, 10, 20, 50, 100, 200, 500]
df
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)
Scroll¶
If you prefer to replace the pagination with a vertical scroll, use for instance
show(df, scrollY="200px", scrollCollapse=True, paging=False)
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
opt.classes = ["display", "cell-border"]
df
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)]))
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)]))
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:
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')
}
}""",
}
],
)
Column width¶
FIXME: This does not appear to be working...
show(df, columnsDefs=[{"width": "200px", "target": 3}])
But in some cases - a table with many column like the one below, we can use the width parameter...
show(x.to_frame().T, columnDefs=[{"width": "80px", "targets": "_all"}])
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,
)
Large table support¶
itables will not display dataframes that are larger than maxBytes, which is equal to 1MB by default. Truncate the dataframe with df.head(), or set the maxBytes parameter or option to an other value to display the dataframe. Or deactivate the limit with maxBytes=0.
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()
df.values.nbytes
opt.maxBytes = 1000000
df
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 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
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.
Appendix¶
Below we initialize the github star button Star that appears on top of this notebook:
%%HTML
<script async defer src="https://buttons.github.io/buttons.js"></script>