{ "cells": [ { "cell_type": "markdown", "id": "041cd4d0", "metadata": {}, "source": [ "![ITables Logo](../src/itables/logo/text.svg)\n", "\n", "[![CI](https://github.com/mwouts/itables/actions/workflows/continuous-integration.yml/badge.svg?branch=main)](https://github.com/mwouts/itables/actions)\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", "[![Jupyter Widget](https://img.shields.io/badge/Jupyter-Widget-F37626.svg?style=flat&logo=Jupyter)](widget.md)\n", "[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_red.svg)](https://itables.streamlit.app)\n", "\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 in a Notebook\n", "\n", "Activate the interactive mode in notebook-like environment with `init_notebook_mode`:" ] }, { "cell_type": "code", "execution_count": 1, "id": "a9604b30", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "\n", "
\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": "2642c3c1", "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": "baaeb7ba", "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.2.2 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": "0b63f09c", "metadata": {}, "source": [ "If you prefer to render only certain tables using `itables`, or want\n", "to pass [advanced parameters](advanced_parameters.md) along with the\n", "DataFrame, use `show`:" ] }, { "cell_type": "code", "execution_count": 3, "id": "2c55362d", "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.2.2 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": "5bd29348", "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", "## Try ITables on Binder\n", "\n", "You can run the examples above (or any other documentation page) directly on ![Lab](https://img.shields.io/badge/Binder-JupyterLab-blue.svg), without having to install anything on your end - just click on the rocket icon at the top of the page." ] } ], "metadata": { "jupytext": { "formats": "md:myst", "notebook_metadata_filter": "-jupytext.text_representation.jupytext_version", "text_representation": { "extension": ".md", "format_name": "myst", "format_version": 0.13 } }, "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.10" }, "source_map": [ 13, 58, 62, 68, 73, 79, 83 ] }, "nbformat": 4, "nbformat_minor": 5 }