{ "cells": [ { "cell_type": "markdown", "id": "ad69b307", "metadata": {}, "source": [ "# The DataTables Arguments\n", "\n", "ITables is a wrapper for the Javascript [DataTables](https://datatables.net/) library, which has a great [documentation](https://datatables.net/), a huge collection of [examples](https://datatables.net/examples/index), and a useful [forum](https://datatables.net/forums/).\n", "\n", "Below we give a series of examples of how the DataTables examples can be ported to Python with `itables`.\n", "\n", "As always, we initialize the `itables` library with" ] }, { "cell_type": "code", "execution_count": 1, "id": "bba27797", "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(all_interactive=True)" ] }, { "cell_type": "markdown", "id": "ff678bde", "metadata": {}, "source": [ "Then we create two sample dataframes:" ] }, { "cell_type": "code", "execution_count": 2, "id": "c0670fa1", "metadata": {}, "outputs": [], "source": [ "import pandas as pd\n", "\n", "from itables.sample_dfs import get_countries\n", "\n", "df_small = pd.DataFrame({\"a\": [2, 1]})\n", "df = get_countries(html=False)" ] }, { "cell_type": "code", "execution_count": 3, "id": "e5ec9798", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "import itables.options as opt\n", "\n", "opt.lengthMenu = [5, 10, 20, 50, 100, 200, 500]" ] }, { "cell_type": "markdown", "id": "3da53013", "metadata": {}, "source": [ "```{tip}\n", "The rocket icon at the top of the page will let you run this notebook in Binder!\n", "```\n", "\n", "## Caption\n", "\n", "You can set additional `tags` on the table like e.g. a [caption](https://datatables.net/blog/2014-11-07):" ] }, { "cell_type": "code", "execution_count": 4, "id": "b4c9d8b7", "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", "
Countries from the World Bank Database
regioncountrycapitallongitudelatitude
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, \"Countries from the World Bank Database\")" ] }, { "cell_type": "markdown", "id": "bc2e206b", "metadata": {}, "source": [ "The caption appears at the bottom of the table by default (except\n", "in Jupyter Book). This is governed by `caption-side:bottom`\n", "in the [`style` option](style).\n", "\n", "You can also override the location of the caption in the caption tag itself:" ] }, { "cell_type": "code", "execution_count": 5, "id": "7693717e", "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", "
Countries from the World Bank Database
regioncountrycapitallongitudelatitude
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", " tags='Countries from the World Bank Database',\n", ")" ] }, { "cell_type": "markdown", "id": "1989c2d0", "metadata": {}, "source": [ "(layout)=\n", "## Table layout\n", "\n", "By default, datatables that don't fit in one page come with a search box, a pagination control, a table summary, etc.\n", "You can select which elements are actually displayed using\n", "DataTables' [`layout` option](https://datatables.net/reference/option/layout) with e.g.:" ] }, { "cell_type": "code", "execution_count": 6, "id": "52921b22", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
a
\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_small, layout={\"topStart\": \"search\", \"topEnd\": None})" ] }, { "cell_type": "markdown", "id": "bc6685e7", "metadata": {}, "source": [ "The available positions are `topStart, topEnd, bottomStart, bottomEnd`. You can also use `top2Start`, etc... (see more\n", "in the [DataTables documentation](https://datatables.net/reference/option/layout)).\n", "\n", "Like for the other arguments of `show`, you can change the default value of the dom option with e.g.:\n", "\n", "```\n", "import itables.options as opt\n", "\n", "opt.layout = {\n", " \"topStart\": \"pageLength\",\n", " \"topEnd\": \"search\",\n", " \"bottomStart\": \"info\",\n", " \"bottomEnd\": \"paging\"\n", "} # (default value)\n", "```\n", "\n", "```{tip}\n", "The `layout` option was introduced with `itables==2.0` and `DataTables==2.0`\n", "and deprecates the former [`dom` option](https://datatables.net/reference/option/dom).\n", "If you wish to continue using the `dom` option, set `opt.warn_on_dom = False`.\n", "```\n", "\n", "## Search\n", "\n", "The [search option](https://datatables.net/reference/option/search) let you control the initial value for the search field, and whether the query should be treated as a regular expression or not:" ] }, { "cell_type": "code", "execution_count": 7, "id": "52a34c2d", "metadata": {}, "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", "
regioncountrycapitallongitudelatitude
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, search={\"regex\": True, \"caseInsensitive\": True, \"search\": \"s.ain\"})" ] }, { "cell_type": "markdown", "id": "1f2f97ec", "metadata": {}, "source": [ "## Pagination\n", "\n", "### How many rows per page\n", "\n", "Select [how many entries](https://datatables.net/examples/advanced_init/length_menu.html) should appear at once in the table with either the `lengthMenu` argument of the `show` function, or with the global option `itables.options.lengthMenu`:" ] }, { "cell_type": "code", "execution_count": 8, "id": "26182fd5", "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", "
regioncountrycapitallongitudelatitude
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, lengthMenu=[2, 5, 10, 20, 50])" ] }, { "cell_type": "markdown", "id": "f76d18a2", "metadata": {}, "source": [ "### Show the table in full\n", "\n", "Use [`paging=False`](https://datatables.net/reference/option/paging) to show the table in full:" ] }, { "cell_type": "code", "execution_count": 9, "id": "aa82a425", "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", "
regioncountrycapitallongitudelatitude
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.head(8), paging=False)" ] }, { "cell_type": "markdown", "id": "f7e48d31", "metadata": {}, "source": [ "### Scroll\n", "\n", "You can replace the pagination with a [vertical scroll](https://datatables.net/examples/basic_init/scroll_y.html):" ] }, { "cell_type": "code", "execution_count": 10, "id": "45845271", "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", "
regioncountrycapitallongitudelatitude
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, scrollY=\"200px\", scrollCollapse=True, paging=False)" ] }, { "cell_type": "markdown", "id": "bf3cef38", "metadata": {}, "source": [ "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`.\n", "\n", "## Footer\n", "\n", "Use `footer = True` if you wish to display a table footer." ] }, { "cell_type": "code", "execution_count": 11, "id": "89e889af", "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", "
regioncountrycapitallongitudelatitude
code
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
code
regioncountrycapitallongitudelatitude
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show(df, footer=True)" ] }, { "cell_type": "markdown", "id": "d146999b", "metadata": {}, "source": [ "## Column filters\n", "\n", "Use `column_filters = \"header\"` or `\"footer\"` if you wish to display individual column filters\n", "(remove the global search box with a [`layout`](layout) modifier if desired)." ] }, { "cell_type": "code", "execution_count": 12, "id": "f455f833", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
stringnumeric
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
stringnumeric
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "alpha_numeric_df = pd.DataFrame(\n", " [[\"one\", 1.5], [\"two\", 2.3]], columns=[\"string\", \"numeric\"]\n", ")\n", "\n", "show(alpha_numeric_df, column_filters=\"footer\", layout={\"topEnd\": None})" ] }, { "cell_type": "markdown", "id": "78b60861", "metadata": {}, "source": [ "As always you can set activate column filters by default with e.g." ] }, { "cell_type": "code", "execution_count": 13, "id": "73873d5f", "metadata": {}, "outputs": [], "source": [ "opt.column_filters = \"footer\"" ] }, { "cell_type": "markdown", "id": "c9d257ea", "metadata": {}, "source": [ "Column filters also work on dataframes with multiindex columns:" ] }, { "cell_type": "code", "execution_count": 14, "id": "23abd5aa", "metadata": {}, "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", "
AB
1212
\n", "\n", "
\n", "Loading ITables v2.0.1 from the init_notebook_mode cell...\n", "(need help?)
NoneNone('A', 1)('A', 2)('B', 1)('B', 2)
\n", "\n" ], "text/plain": [ " A B \n", " 1 2 1 2\n", "C 3 0 1 2 3\n", " 4 4 5 6 7\n", "D 3 8 9 10 11\n", " 4 12 13 14 15" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from itables.sample_dfs import get_dict_of_test_dfs\n", "\n", "get_dict_of_test_dfs()[\"multiindex\"]" ] }, { "cell_type": "code", "execution_count": 15, "id": "7f74adcb", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "opt.column_filters = False" ] }, { "cell_type": "markdown", "id": "9966bda0", "metadata": {}, "source": [ "## Row order\n", "\n", "Since `itables>=1.3.0`, the interactive datatable shows the rows in the same order as the original dataframe:" ] }, { "cell_type": "code", "execution_count": 16, "id": "8a1cb64d", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
Sorted Index
xy
i
\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" }, { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
Reverse Sorted Index
xy
i
\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" }, { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
Sorted Multiindex
xy
ij
\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" }, { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
Unsorted Index
xy
i
\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": [ "from itables.sample_dfs import get_dict_of_test_dfs\n", "\n", "for name, test_df in get_dict_of_test_dfs().items():\n", " if \"sorted\" in name:\n", " show(test_df, tags=f\"{name}\".replace(\"_\", \" \").title())" ] }, { "cell_type": "markdown", "id": "133a646d", "metadata": {}, "source": [ "You can also set an explicit [`order`](https://datatables.net/reference/option/order) argument:" ] }, { "cell_type": "code", "execution_count": 17, "id": "73f9a543", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
a
i
\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": [ "sorted_df = pd.DataFrame({\"i\": [1, 2], \"a\": [2, 1]}).set_index([\"i\"])\n", "show(sorted_df, order=[[1, \"asc\"]])" ] }, { "cell_type": "markdown", "id": "f9f3f16f", "metadata": {}, "source": [ "## Showing the index\n", "\n", "By default, the index of a Series/DataFrame is shown only when it is not trivial, i.e. when\n", "it has a name, or when it differs from a range index. If you prefer, you can change the value of\n", "`showIndex` to either `True` or `False` to always or never show the index (the default value being `\"auto\"`).\n", "\n", "You can change this behavior globally with e.g.\n", "```python\n", "import itables.options as opt\n", "\n", "opt.showIndex = True\n", "```\n", "\n", "or locally by passing an argument `showIndex` to the `show` function:" ] }, { "cell_type": "code", "execution_count": 18, "id": "fcdb81a6", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", " \n", " \n", " \n", " \n", " \n", "\n", "\n", "\n", "\n", "
letter
\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": [ "df_with_range_index = pd.DataFrame({\"letter\": list(\"abcd\")})\n", "show(df_with_range_index, showIndex=True)" ] } ], "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, 23, 27, 31, 40, 46, 56, 60, 68, 75, 84, 86, 114, 116, 124, 128, 134, 138, 144, 148, 156, 160, 167, 173, 177, 179, 183, 189, 193, 199, 205, 209, 212, 229 ] }, "nbformat": 4, "nbformat_minor": 5 }