Ctrl+K

DataTables Extensions

DataTables Extensions#

DataTables comes with a series of extensions, which are supported by ITables since v2.0. A selection of these extensions are included in ITables.

As usual, we activate ITables with:

from itables import init_notebook_mode, show

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

and then, we create a few example dataframes:

Hide code cell source 
import string

import numpy as np
import pandas as pd

from itables.sample_dfs import get_countries

df = get_countries(html=False)
# Add columns for the searchPanes demo
df["climate_zone"] = np.where(
    df["latitude"].abs() < 23.43615,
    "Tropical",
    np.where(
        df["latitude"].abs() < 35,
        "Sub-tropical",
        # Artic circle is 66.563861 but there is no capital there => using 64
        np.where(df["latitude"].abs() < 64, "Temperate", "Frigid"),
    ),
)
df["hemisphere"] = np.where(df["latitude"] > 0, "North", "South")
wide_df = pd.DataFrame(
    {
        letter: np.random.normal(size=100)
        for letter in string.ascii_lowercase + string.ascii_uppercase
    }
)

Tip

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

Buttons#

The DataTables buttons let you copy the table data, or export it as CSV or Excel files.

To display the buttons, you need to pass a buttons argument to the show function:

show(df, buttons=["copyHtml5", "csvHtml5", "excelHtml5"])
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

You can also specify a layout modifier that will decide the location of the buttons (the default is layout={"topStart": "buttons"}). And if you want to keep the pagination control too, you can add "pageLength" to the list of buttons.

As always, it is possible to set default values for these parameters by setting these on itables.options. For instance, set

opt.buttons = ["copyHtml5", "csvHtml5", "excelHtml5"]

to get the buttons for all tables.

By default, the exported file name is the name of the HTML page. To change it, set a title option on the buttons, like here:

show(
    df,
    buttons=[
        "pageLength",
        {"extend": "csvHtml5", "title": "Countries"},
        {"extend": "excelHtml5", "title": "Countries"},
    ],
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Warning

The PDF button is not included in ITables’ DataTable bundle. This is because the required PDF libraries have a large footprint on the bundle size. Still, you can add it to your custom bundle, see the next chapter.

SearchPanes#

SearchPanes is an extension that lets you select rows based on unique values. In the example below we have activated the cascade filtering through the searchPanes.cascadePanes argument. Note that, in Jupyter, the searchPanes.layout argument is required (otherwise the search panes are too wide).

show(
    df,
    layout={"top1": "searchPanes"},
    searchPanes={"layout": "columns-3", "cascadePanes": True},
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Warning

When searching, please keep in mind that ITables will downsample your table if it is larger than maxBytes, so you might not see the full dataset - pay attention to the downsampling message at the bottom left of the table.

SearchBuilder#

SearchBuilder let you build complex search queries. You just need to add it to the layout by passing e.g. layout={"top1": "searchBuilder"}.

It is possible to set a predefined search, as we do in the below:

show(
    df,
    layout={"top1": "searchBuilder"},
    searchBuilder={
        "preDefined": {
            "criteria": [
                {"data": "climate_zone", "condition": "=", "value": ["Sub-tropical"]}
            ]
        }
    },
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

FixedColumns#

FixedColumn is an extension that let you fix some columns as you scroll horizontally.

show(
    wide_df,
    fixedColumns={"start": 1, "end": 2},
    scrollX=True,
)
a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

KeyTable#

With the KeyTable extension you can navigate in a table using the arrow keys:

show(df, keys=True)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)

Tip

You can activate this option for all your tables with

import itables.options as opt

opt.keys = True

Warning

The KeyTable extension works in Jupyter Book (try it here in the documentation) but not in JupyterLab.

RowGroup#

Use the RowGroup extension to group the data according to the content of one colum. Optionally, you can hide the content of that column to avoid duplicating the information.

show(
    df.sort_values("region"),
    rowGroup={"dataSrc": 1},
    columnDefs=[{"targets": 1, "visible": False}],
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.0.1-dev from the init_notebook_mode cell... (need help?)
Contents