{ "cells": [ { "cell_type": "markdown", "id": "4adb19f7", "metadata": {}, "source": [ "# DataTables Extensions\n", "\n", "DataTables comes with a series of [extensions](https://datatables.net/extensions/), which are supported by ITables since v2.0.\n", "A selection of these extensions are included in ITables.\n", "\n", "As usual, we activate ITables with:" ] }, { "cell_type": "code", "execution_count": 1, "id": "86cc09cd", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "\n", "
\n", "
\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", " \n", " \n", " \n", " \n", "\n", " \n", " \n", " \n", " \n", "\n", " \n", " \n", " \n", " \n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "
\n", "
\n", "This is the init_notebook_mode cell from ITables v2.0.1
\n", "(you should not see this message - is your notebook trusted?)\n", "
\n", "
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from itables import init_notebook_mode, show\n", "\n", "init_notebook_mode()" ] }, { "cell_type": "markdown", "id": "d3a8eae3", "metadata": {}, "source": [ "and then, we create a few example dataframes:" ] }, { "cell_type": "code", "execution_count": 2, "id": "4b684c57", "metadata": { "tags": [ "hide-input" ] }, "outputs": [], "source": [ "import string\n", "\n", "import numpy as np\n", "import pandas as pd\n", "\n", "from itables.sample_dfs import get_countries\n", "\n", "df = get_countries(html=False)\n", "# Add columns for the searchPanes demo\n", "df[\"climate_zone\"] = np.where(\n", " df[\"latitude\"].abs() < 23.43615,\n", " \"Tropical\",\n", " np.where(\n", " df[\"latitude\"].abs() < 35,\n", " \"Sub-tropical\",\n", " # Artic circle is 66.563861 but there is no capital there => using 64\n", " np.where(df[\"latitude\"].abs() < 64, \"Temperate\", \"Frigid\"),\n", " ),\n", ")\n", "df[\"hemisphere\"] = np.where(df[\"latitude\"] > 0, \"North\", \"South\")\n", "wide_df = pd.DataFrame(\n", " {\n", " letter: np.random.normal(size=100)\n", " for letter in string.ascii_lowercase + string.ascii_uppercase\n", " }\n", ")" ] }, { "cell_type": "markdown", "id": "0b7afbce", "metadata": {}, "source": [ "```{tip}\n", "The rocket icon at the top of the page will let you run this notebook in Binder!\n", "```\n", "\n", "## Buttons\n", "\n", "The DataTables [buttons](https://datatables.net/extensions/buttons/) let you copy the table data, or export it as CSV or Excel files.\n", "\n", "To display the buttons, you need to pass a `buttons` argument to the `show` function:" ] }, { "cell_type": "code", "execution_count": 3, "id": "e09f49e9", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
regioncountrycapitallongitudelatitudeclimate_zonehemisphere
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(df, buttons=[\"copyHtml5\", \"csvHtml5\", \"excelHtml5\"])" ] }, { "cell_type": "markdown", "id": "b4719eb2", "metadata": {}, "source": [ "You can also specify a [`layout`](layout) modifier that will decide\n", "the location of the buttons (the default is `layout={\"topStart\": \"buttons\"}`). And if\n", "you want to keep the pagination control too, you can add `\"pageLength\"` to the list of buttons.\n", "\n", "As always, it is possible to set default values for these parameters by setting these on `itables.options`. For instance, set\n", "```python\n", "opt.buttons = [\"copyHtml5\", \"csvHtml5\", \"excelHtml5\"]\n", "```\n", "to get the buttons for all tables.\n", "\n", "\n", "By default, the exported file name is the name of the HTML page. To change it, set a\n", "[`title` option](https://datatables.net/extensions/buttons/examples/html5/filename.html) on the buttons, like\n", "here:" ] }, { "cell_type": "code", "execution_count": 4, "id": "7703b099", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
regioncountrycapitallongitudelatitudeclimate_zonehemisphere
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(\n", " df,\n", " buttons=[\n", " \"pageLength\",\n", " {\"extend\": \"csvHtml5\", \"title\": \"Countries\"},\n", " {\"extend\": \"excelHtml5\", \"title\": \"Countries\"},\n", " ],\n", ")" ] }, { "cell_type": "markdown", "id": "462f07d0", "metadata": {}, "source": [ "```{warning}\n", "The PDF button is not included in ITables' DataTable bundle. This is because the required PDF libraries\n", "have a large footprint on the bundle size. Still, you can add it to your custom bundle, see the next chapter.\n", "```\n", "\n", "## SearchPanes\n", "\n", "[SearchPanes](https://datatables.net/extensions/searchpanes/) is an extension that lets you select rows based on\n", "unique values. In the example below we have activated the cascade filtering through the\n", "[`searchPanes.cascadePanes`](https://datatables.net/extensions/searchpanes/examples/initialisation/cascadePanes.html) argument.\n", "Note that, in Jupyter, the [`searchPanes.layout`](https://datatables.net/extensions/searchpanes/layout)\n", "argument is required (otherwise the search panes are too wide)." ] }, { "cell_type": "code", "execution_count": 5, "id": "6f42f3d1", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
regioncountrycapitallongitudelatitudeclimate_zonehemisphere
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(\n", " df,\n", " layout={\"top1\": \"searchPanes\"},\n", " searchPanes={\"layout\": \"columns-3\", \"cascadePanes\": True},\n", ")" ] }, { "cell_type": "markdown", "id": "3eaf6770", "metadata": {}, "source": [ "```{warning}\n", "When searching, please keep in mind that ITables will [downsample](downsampling.md) your table if it is larger than `maxBytes`,\n", "so you might not see the full dataset - pay attention to the downsampling message at the bottom left of the table.\n", "```\n", "\n", "## SearchBuilder\n", "\n", "[SearchBuilder](https://datatables.net/extensions/searchbuilder/) let you build complex search queries. You just need to add it to the layout\n", "by passing e.g. `layout={\"top1\": \"searchBuilder\"}`.\n", "\n", "It is possible to set a predefined search, as we do in the below:" ] }, { "cell_type": "code", "execution_count": 6, "id": "612d4d4c", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
regioncountrycapitallongitudelatitudeclimate_zonehemisphere
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(\n", " df,\n", " layout={\"top1\": \"searchBuilder\"},\n", " searchBuilder={\n", " \"preDefined\": {\n", " \"criteria\": [\n", " {\"data\": \"climate_zone\", \"condition\": \"=\", \"value\": [\"Sub-tropical\"]}\n", " ]\n", " }\n", " },\n", ")" ] }, { "cell_type": "markdown", "id": "40d6b81a", "metadata": {}, "source": [ "## FixedColumns\n", "\n", "[FixedColumn](https://datatables.net/extensions/fixedcolumns/) is an extension\n", "that let you fix some columns as you scroll horizontally." ] }, { "cell_type": "code", "execution_count": 7, "id": "802c06b8", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(\n", " wide_df,\n", " fixedColumns={\"start\": 1, \"end\": 2},\n", " scrollX=True,\n", ")" ] }, { "cell_type": "markdown", "id": "3fe2bb05", "metadata": {}, "source": [ "## KeyTable\n", "\n", "With the [KeyTable](https://datatables.net/extensions/keytable/) extension you can navigate in a table using the arrow keys:" ] }, { "cell_type": "code", "execution_count": 8, "id": "c7410d02", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
regioncountrycapitallongitudelatitudeclimate_zonehemisphere
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(df, keys=True)" ] }, { "cell_type": "markdown", "id": "da71a6e4", "metadata": {}, "source": [ "```{tip}\n", "You can activate this option for all your tables with\n", "\n", "~~~python\n", "import itables.options as opt\n", "\n", "opt.keys = True\n", "~~~\n", "```\n", "\n", "```{warning}\n", "The KeyTable extension works in Jupyter Book (try it here in the documentation) but not in JupyterLab.\n", "```\n", "\n", "## RowGroup\n", "\n", "Use the [RowGroup](https://datatables.net/extensions/rowgroup/) extension to group\n", "the data according to the content of one colum. Optionally, you can hide the content\n", "of that column to avoid duplicating the information." ] }, { "cell_type": "code", "execution_count": 9, "id": "ddfa914b", "metadata": { "tags": [ "full-width" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
regioncountrycapitallongitudelatitudeclimate_zonehemisphere
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(\n", " df.sort_values(\"region\"),\n", " rowGroup={\"dataSrc\": 1},\n", " columnDefs=[{\"targets\": 1, \"visible\": False}],\n", ")" ] } ], "metadata": { "jupytext": { "formats": "md:myst", "text_representation": { "extension": ".md", "format_name": "myst", "format_version": 0.13, "jupytext_version": "1.14.5" } }, "kernelspec": { "display_name": "itables", "language": "python", "name": "itables" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.9" }, "source_map": [ 13, 22, 26, 30, 59, 71, 75, 92, 103, 118, 126, 140, 154, 161, 169, 175, 179, 201 ] }, "nbformat": 4, "nbformat_minor": 5 }