Advanced Parameters

Advanced Parameters#

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

import itables

itables.init_notebook_mode()

Then we create two sample dataframes:

import pandas as pd

df_small = pd.DataFrame({"a": [2, 1]})
df = itables.sample_dfs.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:

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

The caption appears at the bottom of the table by default: this is governed by caption-side:bottom in the style option (but for some reason this is not effective in Jupyter Book 😕).

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.:

itables.show(df_small, layout={"topStart": "search", "topEnd": None})
a
Loading ITables v2.4.0-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.:

itables.options.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 itables.options.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:

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

Show the table in full#

Use paging=False to show the table in full:

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

Scroll#

You can replace the pagination with a vertical scroll:

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

Since ITables 2.1.2, the .dt-layout-table div has a default overflow equal to auto, so in most cases you won’t need to use the scrollX option of datatables.

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"]
)

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

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

itables.options.column_filters = "footer"

Column filters also work on dataframes with multiindex columns:

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

Row order#

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

for name, test_df in itables.sample_dfs.get_dict_of_test_dfs().items():
    if "sorted" in name:
        itables.show(
            test_df, tags=f"<caption>{name}</caption>".replace("_", " ").title()
        )
Sorted Index
x y
i
Loading ITables v2.4.0-dev from the init_notebook_mode cell... (need help?)
Reverse Sorted Index
x y
i
Loading ITables v2.4.0-dev from the init_notebook_mode cell... (need help?)
Sorted Multiindex
x y
i j
Loading ITables v2.4.0-dev from the init_notebook_mode cell... (need help?)
Unsorted Index
x y
i
Loading ITables v2.4.0-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"])
itables.show(sorted_df, order=[[1, "asc"]])
a
i
Loading ITables v2.4.0-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.

itables.options.showIndex = True

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

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