TABLET: A Large-Scale Dataset for Robust Visual Table Understanding

This repository provides the code and data for the ICLR 2026 paper:

TABLET: A Large-Scale Dataset for Robust Visual Table Understanding
Iñigo Alonso, Imanol Miranda, Eneko Agirre, Mirella Lapata

TABLET Dataset

You don't need to clone this repository to use the TABLET dataset. You can access all dataset versions on 🤗 HuggingFace:

• TABLET-Small: Download
• TABLET-Medium: Download
• TABLET-Large: Download
• TABLET-dev: Download
• TABLET-test: Download

Getting Started

1. Clone the repository and install dependencies

   git clone https://github.com/AlonsoApp/TABLET.git
   cd TABLET
   pip install -r requirements.txt
   export PYTHONPATH="$PWD/src"

2. Download data folder
   Download its contents and extract them into ./data/.

3. Download auxiliary files
   Download these files and place them under ./out/. Doing so will speed up execution, as regenerating them can take several days and may yield slightly different results (because it requires web crawling and resources may not be available anymore). The most important file is table_manifest.jsonl, which lists all tables in the dataset, their sources, and associated Wikipedia identifiers. A version of this manifest including the visual complexity score for each table can also be downloaded here.

4. Download table resources (optional)
   If you want to dive deeper into the functions in this repository it would be very handy if you download all table files. Once downloaded, you can place the tables folder under ./resources/ at the root of this project or put it on a separate location (e.g. a high capacity drive). The project resource_dao.py will try finding the tables in TABLET/resources/tables/ but if you decide string the tables somewhere else you need to specify this path in the env variable TABLET_RESOURCES.

export TABLET_RESOURCES="/media/hdd/resources/" # Your custom path to resources

5. Set selenium path (only if you want to render tables)
   To render tables, install Selenium and set an environment variable GECKODRIVER_PATH pointing at your Geckodriver installation:

# 
export GECKODRIVER_PATH="/snap/bin/geckodriver" # If native Ubuntu installation could be found here
# or 
export GECKODRIVER_PATH="~/.conda/envs/TABLET/bin/geckodriver" # If using a conda env could be found here

Helper functions

This repository could be helpful beyond replicating the results of the paper because it provides a set of helper functions that can be helpful when modifiying or extending the dataset. With these functions you can render table HTMLs into images with the intra-images, style, and other visual features of the original table visualization; retrieve the source examples assotiated to each TABLET example from the original dataset; and transform metadata indexes (found in the released examples of TABLET) into values. You can find these functions at the root directory in the api.py module.

This repository provides several helper functions that are useful beyond reproducing the paper's results. For example, when modifying or extending the TABLET dataset.

With these functions you can:

• Render table HTMLs into images preserving the original style and intra-images.
• Retrieve the source examples associated to each TABLET example from the original dataset
• Convert metadata indices (found in the released examples of TABLET) into values.

These functions are available in the root module api.py.

def load_dataset(dataset_name: str, split: Optional[str], variant: Optional[str]=None) -> List:
	"""
	:param dataset_name: ToTTo | TableInstruct | TURL | HiTab | StatCan | NSF | FeTaQA | TabFact | DocStruct4M | WikiTableQuestions | PubTabNet | Demeter | HybridQA | MMTab | TAT-QA | TABMWP | InfoTabs | WikiBIO
	:param split: train | dev | test
	:param variant: variant of dataset, for TABLET datasets this is the task and for others see demeter_utils.TASK_TO_SEED_VARIANT for the equivalences
	"""

def load_selenium_driver() -> WebDriver:
	"""
	Easily loads a Selenium driver that can be reused for multi table rendering. Note that you need to specify the executable_path in an env variable "GECKODRIVER_PATH" (typically '/snap/bin/geckodriver' or '~/.conda/envs/TABLET/bin/geckodriver')
	"""

def render_table(html_table_path:str=None, html_table_str:str=None, save_file_path:str=None, driver:WebDriver = None, wikipedia_style:bool=True) -> bytes:
	"""
	Renders an HTML table by providing a path to the file or the HTML itself as a string.
	:param html_table_path: path to HTML file
	:param html_table_str: HTML in string format
	:param save_file_path: if not None, the image will be saved as a png file in this path
	:param driver: if not None, selenium will use this driver to render the HTML. It also avoids reinstantiating a new Selenium client at each rendering and reuse the one given. If None it will use the Selenium executable (see Service(executable_path=os.environ.get("GECKODRIVER_PATH")) in Selenium documentation) specified at the environment variable "GECKODRIVER_PATH" (typically "/snap/bin/geckodriver" or "~/.conda/envs/TABLET/bin/geckodriver"). You can also use the load_selenium_driver() function to easily get the default driver once the env variable is specified.
	:param wikipedia_style: renders the table with the original wikipedia style and intra-images
	"""

def get_original_example(example, src_dataset_name:str=None, idx_dataset:dict=None) -> Tuple[Dict, Dict]:
	"""
	Given a TABLET example, returns the original associated example from the source dataset.
	WARNING: this is extremely slow if the source dataset is not provided, this function
	will return a full loaded version of this source dataset at each iteration for convenience so it can be reused in a
	for loop
	:param example: TABLET example
	:param src_dataset_name: if a TABLET example has multiple sources, this allows disambiguation
	:param idx_dataset: indexed source dataset (it is returned on the first query (slow) and allows faster queries when
	provided in future executions of the function)
	:return: example from original dataset, idx_dataset for future (and faster) queries
	"""

def get_metadata(example) -> Dict:
	"""
	Transform metadata indexes (found in the released examples of TABLET) into values
	:param example: TABLET dataset example
	:return:
	"""

The repository includes many other utility functions used during development. Check:

• datasource.utils for general data management helpers
• datasource.demeter.resource_dao for table access and management.
• datasource.demeter.dataset_agg.py and image_generation.py for examples of how to use many of these functions.

Note: The internal project name was Demeter. Any reference to "Demeter" in the code refers to the TABLET dataset.

Reproducing Results

1. Download model predictions and extract them into ./out/predictions.
2. Run the evaluation script to reproduce the results in the paper (comment any function in __main__ to avoid especific evaluations):

python datasource/demeter/evaluator.py

Term equivalences:

• MMTab_wiki = TABLET-B org
• MMTab_mixed = TABLET-B mix
• MMTab_wiki-aligned = TABLET-B synth
• Balanced-mix-lite = TABLET-Small (original + synthetic tables)
• Balanced-original = TABLET-Medium (original table visualizations only)
• Balanced-mix = TABLET-Medium (original + synthetic tables)
• Unbalanced-mix = TABLET-Large (original + synthetic tables)

These names appear both at the beginning of evaluation files (dataset used for evaluation) and at the end of model names (dataset used for SFT training).

License

TABLET's original contributions — the table image renderings, unified annotation format, task instructions, and accompanying metadata and scripts produced by the TABLET authors — are released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license, except where the license of a source dataset requires otherwise (see below).

TABLET is a meta-dataset aggregating 14 existing table understanding datasets. Each TABLET subset remains subject to the license and terms of use of its original source. By downloading or using TABLET, you agree to comply with the license of every source dataset you use, in addition to the terms above. Where a source license conflicts with CC BY 4.0, the source license prevails for that subset.

Source dataset licenses

Subset	Source license	Notes
TURL	Apache 2.0	Tables originate from Wikipedia (CC BY-SA 3.0).
ToTTo	CC BY-SA 3.0	ShareAlike: this subset is redistributed under CC BY-SA 3.0.
TabFact	MIT	Tables originate from Wikipedia (CC BY-SA 3.0).
WikiTableQuestions	CC BY-SA 4.0	ShareAlike: this subset is redistributed under CC BY-SA 4.0.
HybridQA	MIT	Tables and passages originate from Wikipedia (CC BY-SA 3.0).
HiTab	C-UDA v1.0	Microsoft Computational Use of Data Agreement: data may be used and redistributed for computational purposes only, and any redistribution of this subset must include the C-UDA agreement.
PubTabNet	CDLA-Permissive 1.0 (annotations)	Table images are from the PubMed Central Open Access Subset and remain subject to the PMC Open Access Subset terms of use; individual article licenses vary.
TabMWP	CC BY-NC-SA 4.0	Non-commercial use only. ShareAlike: this subset is redistributed under CC BY-NC-SA 4.0.
TAT-QA	CC BY 4.0	—
InfoTabs	Apache 2.0	Tables originate from Wikipedia infoboxes (CC BY-SA 3.0). See the dataset's datasheet for non-academic usage.
WikiBIO	CC BY-SA 3.0	ShareAlike: this subset is redistributed under CC BY-SA 3.0.
FeTaQA	CC BY-SA 4.0	ShareAlike: this subset is redistributed under CC BY-SA 4.0.
MMTab	MIT	MMTab is itself constructed from 14 public table datasets; the licenses of its underlying sources also apply. Code repository is Apache 2.0.
DocStruct4M	Apache 2.0	Built from publicly available text-rich image datasets; the licenses of its underlying sources also apply.

Usage restrictions to be aware of

• Non-commercial subset. The TabMWP subset is licensed CC BY-NC-SA 4.0 and may not be used for commercial purposes. If you require a fully commercial-compatible corpus, exclude this subset.
• ShareAlike subsets. The subsets derived from ToTTo, WikiTableQuestions, FeTaQA, and WikiBIO carry ShareAlike terms: adaptations of these subsets must be distributed under the same (or a compatible) license, not plain CC BY.
• HiTab. Use and redistribution of the HiTab subset is governed by the C-UDA v1.0; results of computational analysis (e.g., trained models) are not restricted, but the data itself may only be redistributed together with the C-UDA terms.
• PubTabNet images. Images remain subject to the PMC Open Access Subset terms; check individual article licenses if you redistribute them outside a research context.
• Attribution. Whatever subsets you use, please attribute the original datasets and cite the corresponding papers (see the Citation section) in addition to citing TABLET.

License information above was collected from each project's official repository or dataset card. It is provided in good faith and does not constitute legal advice; if in doubt, consult the original license texts linked in the table.

Citation

If you find TABLET useful in your research, please consider citing it by the following BibTeX entry.

@misc{alonso2025tabletlargescaledatasetrobust,
      title={TABLET: A Large-Scale Dataset for Robust Visual Table Understanding}, 
      author={Iñigo Alonso and Imanol Miranda and Eneko Agirre and Mirella Lapata},
      year={2025},
      eprint={2509.21205},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2509.21205}, 
}