{ "cells": [ { "cell_type": "markdown", "id": "9f2add0f", "metadata": {}, "source": [ "![ITables Logo](../itables/logo/text.svg)\n", "\n", "![CI](https://github.com/mwouts/itables/actions/workflows/continuous-integration.yml/badge.svg?branch=main)\n", "[![codecov.io](https://codecov.io/github/mwouts/itables/coverage.svg?branch=main)](https://codecov.io/github/mwouts/itables?branch=main)\n", "[![Pypi](https://img.shields.io/pypi/v/itables.svg)](https://pypi.python.org/pypi/itables)\n", "[![Conda Version](https://img.shields.io/conda/vn/conda-forge/itables.svg)](https://anaconda.org/conda-forge/itables)\n", "[![pyversions](https://img.shields.io/pypi/pyversions/itables.svg)](https://pypi.python.org/pypi/itables)\n", "[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n", "Star\n", "\n", "\n", "This packages changes how Pandas and Polars DataFrames are rendered in Jupyter Notebooks.\n", "With `itables` you can display your tables as interactive [DataTables](https://datatables.net/)\n", "that you can sort, paginate, scroll or filter.\n", "\n", "ITables is just about how tables are displayed. You can turn it on and off in just two lines,\n", "with no other impact on your data workflow.\n", "\n", "The `itables` package depends only on `numpy`, `pandas` and `IPython`\n", "which you must already have if you work with Pandas in Jupyter (add `polars`, `pyarrow` if you\n", "work with Polars DataFrames).\n", "\n", "# Quick Start\n", "\n", "## Installation\n", "\n", "Install the `itables` package with either\n", "\n", "```shell\n", "pip install itables\n", "```\n", "\n", "or\n", "```shell\n", "conda install itables -c conda-forge\n", "```\n", "\n", "## Activate ITables\n", "\n", "Activate the interactive mode for all series and dataframes with" ] }, { "cell_type": "code", "execution_count": 1, "id": "d2ec6d13", "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\n", "\n", "init_notebook_mode(all_interactive=True)" ] }, { "cell_type": "markdown", "id": "e3118dff", "metadata": {}, "source": [ "After this, any Pandas or Polars DataFrame, or Series,\n", "is displayed as an interactive [DataTables](https://datatables.net/),\n", "which lets you explore, filter or sort your data." ] }, { "cell_type": "code", "execution_count": 2, "id": "c3bbc630", "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": [ " region country capital longitude \\\n", "code \n", "AW Latin America & Caribbean Aruba Oranjestad -70.0167 \n", "AF South Asia Afghanistan Kabul 69.1761 \n", "AO Sub-Saharan Africa Angola Luanda 13.2420 \n", "AL Europe & Central Asia Albania Tirane 19.8172 \n", "AD Europe & Central Asia Andorra Andorra la Vella 1.5218 \n", "... ... ... ... ... \n", "XK Europe & Central Asia Kosovo Pristina 20.9260 \n", "YE Middle East & North Africa Yemen, Rep. Sana'a 44.2075 \n", "ZA Sub-Saharan Africa South Africa Pretoria 28.1871 \n", "ZM Sub-Saharan Africa Zambia Lusaka 28.2937 \n", "ZW Sub-Saharan Africa Zimbabwe Harare 31.0672 \n", "\n", " latitude \n", "code \n", "AW 12.51670 \n", "AF 34.52280 \n", "AO -8.81155 \n", "AL 41.33170 \n", "AD 42.50750 \n", "... ... \n", "XK 42.56500 \n", "YE 15.35200 \n", "ZA -25.74600 \n", "ZM -15.39820 \n", "ZW -17.83120 \n", "\n", "[208 rows x 5 columns]" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from itables.sample_dfs import get_countries\n", "\n", "df = get_countries(html=False)\n", "df" ] }, { "cell_type": "markdown", "id": "959f76b6", "metadata": {}, "source": [ "## Offline mode versus connected mode\n", "\n", "ITables use two Javascript libraries:\n", "[jQuery](https://jquery.com/) and [DataTables](https://datatables.net/).\n", "\n", "By default `itables` works offline. No internet connection is required\n", "as the two libraries are embedded into the notebook itself\n", "when you execute `init_notebook_mode`.\n", "\n", "In some contexts (Jupyter Book, Jupyter Colab, etc...) you might\n", "prefer to load the libraries dynamically from the internet.\n", "To do so, add the argument `connected=True` when you\n", "execute `init_notebook_mode`. This will also make your notebook lighter by\n", "about [700kB](https://github.com/mwouts/itables/blob/main/tests/test_connected_notebook_is_small.py).\n", "\n", "## Using ITables for specific tables only\n", "\n", "If you prefer to render only certain series or dataframes using `itables`,\n", "then call `init_notebook_mode(all_interactive=False)` then `show`:" ] }, { "cell_type": "code", "execution_count": 3, "id": "f0405edc", "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": [ "from itables import show\n", "\n", "show(df, lengthMenu=[2, 5, 10, 25, 50, 100, 250])" ] }, { "cell_type": "markdown", "id": "d9a0f8b2", "metadata": {}, "source": [ "## Try ITables on Binder\n", "\n", "You can run our examples notebooks directly on [![Lab](https://img.shields.io/badge/Binder-JupyterLab-blue.svg)](https://mybinder.org/v2/gh/mwouts/itables/main?urlpath=lab/tree/docs/quick_start.md), without having to install anything on your side." ] } ], "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, 56, 60, 66, 71, 93, 97 ] }, "nbformat": 4, "nbformat_minor": 5 }