Ctrl+K

The DataTables Arguments

The DataTables Arguments#

ITables is a wrapper for the Javascript DataTables library, which has a great documentation, a huge collection of examples, and a useful forum.

Below we give a series of examples of how the DataTables examples can be ported to Python with itables.

As always, we initialize the itables library with

from itables import init_notebook_mode, show

init_notebook_mode(all_interactive=True)
This is the init_notebook_mode cell from ITables v2.0.1-dev
(you should not see this message - is your notebook trusted?)

Then we create two sample dataframes:

import pandas as pd

from itables.sample_dfs import get_countries

df_small = pd.DataFrame({"a": [2, 1]})
df = get_countries(html=False)

Tip

The rocket icon at the top of the page will let you run this notebook in Binder!

Caption#

You can set additional tags on the table like e.g. a caption:

show(df, "Countries from the World Bank Database")
Countries from the World Bank Database
region country capital longitude latitude
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

The caption appears at the bottom of the table by default (except in Jupyter Book). This is governed by caption-side:bottom in the style option.

You can also override the location of the caption in the caption tag itself:

show(
    df,
    tags='<caption style="caption-side: bottom">Countries from the World Bank Database</caption>',
)
Countries from the World Bank Database
region country capital longitude latitude
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Table layout#

By default, datatables that don’t fit in one page come with a search box, a pagination control, a table summary, etc. You can select which elements are actually displayed using DataTables’ layout option with e.g.:

show(df_small, layout={"topStart": "search", "topEnd": None})
a
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

The available positions are topStart, topEnd, bottomStart, bottomEnd. You can also use top2Start, etc… (see more in the DataTables documentation).

Like for the other arguments of show, you can change the default value of the dom option with e.g.:

import itables.options as opt

opt.layout =  {
    "topStart": "pageLength",
    "topEnd": "search",
    "bottomStart": "info",
    "bottomEnd": "paging"
}  # (default value)

Tip

The layout option was introduced with itables==2.0 and DataTables==2.0 and deprecates the former dom option. If you wish to continue using the dom option, set opt.warn_on_dom = False.

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:

show(df, lengthMenu=[2, 5, 10, 20, 50])
region country capital longitude latitude
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Show the table in full#

Use paging=False to show the table in full:

show(df.head(8), paging=False)
region country capital longitude latitude
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Scroll#

You can replace the pagination with a vertical scroll:

show(df, scrollY="200px", scrollCollapse=True, paging=False)
region country capital longitude latitude
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

In the context of the notebook, a horizontal scroll bar should appear when the table is too wide. In other contexts like here in Jupyter Book, you might want to use scrollX = True.

Column filters#

Use column_filters = "header" or "footer" if you wish to display individual column filters (remove the global search box with a layout modifier if desired).

alpha_numeric_df = pd.DataFrame(
    [["one", 1.5], ["two", 2.3]], columns=["string", "numeric"]
)

show(alpha_numeric_df, column_filters="footer", layout={"topEnd": None})
string numeric
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
stringnumeric

As always you can set activate column filters by default with e.g.

opt.column_filters = "footer"

Column filters also work on dataframes with multiindex columns:

from itables.sample_dfs import get_dict_of_test_dfs

get_dict_of_test_dfs()["multiindex"]
A B
1 2 1 2
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
NoneNone('A', 1)('A', 2)('B', 1)('B', 2)

Row order#

Since itables>=1.3.0, the interactive datatable shows the rows in the same order as the original dataframe:

from itables.sample_dfs import get_dict_of_test_dfs

for name, test_df in get_dict_of_test_dfs().items():
    if "sorted" in name:
        show(test_df, tags=f"<caption>{name}</caption>".replace("_", " ").title())
Sorted Index
x y
i
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
Reverse Sorted Index
x y
i
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
Sorted Multiindex
x y
i j
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
Unsorted Index
x y
i
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

You can also set an explicit order argument:

sorted_df = pd.DataFrame({"i": [1, 2], "a": [2, 1]}).set_index(["i"])
show(sorted_df, order=[[1, "asc"]])
a
i
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Showing the index#

By default, the index of a Series/DataFrame is shown only when it is not trivial, i.e. when it has a name, or when it differs from a range index. If you prefer, you can change the value of showIndex to either True or False to always or never show the index (the default value being "auto").

You can change this behavior globally with e.g.

import itables.options as opt

opt.showIndex = True

or locally by passing an argument showIndex to the show function:

df_with_range_index = pd.DataFrame({"letter": list("abcd")})
show(df_with_range_index, showIndex=True)
letter
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
Contents