TINTOlib 1.1.0

Converting tabular data into images

TINTOlib: Python Library to convert Tabular Data into Synthetic Images

---

📊 Benchmarks & Results

• Explore detailed benchmark results, model comparisons, and performance tables for TINTOlib on various datasets.
• 👉 See the latest benchmarks: TINTOlib Benchmarks (GitHub Pages)

---

🎉 New Free Course on Udemy! (Spanish) 🎉

We’ve just launched a 100% free course on Udemy about using TINTOlib and developing Hybrid Neural Networks.

Learn how to turn tabular data into synthetic images and apply CNNs, ViTs, and hybrid architectures like a pro.

---

🎬 TINTOlib — Overview Video (English)

https://github.com/user-attachments/assets/96e63eb4-2e06-4eb9-9f72-e1f530ffad37

---

📺 VideoTutorial Course (English/Spanish)

🎥 Prefer not to register on Udemy or looking for the English version of the course? No worries — you can follow the full course directly on GitHub!

This hands-on tutorial includes bilingual videos (English/Spanish) and practical notebooks to help you learn how to use TINTOlib with deep learning models like CNNs, ViTs, and hybrid architectures.

---

🧠 Overview

TINTOlib is a state-of-the-art Python library that transforms tidy data (also known as tabular data) into synthetic images, enabling the application of advanced deep learning techniques, including Vision Transformers (ViTs) and Convolutional Neural Networks (CNNs), to traditionally structured data. This transformation bridges the gap between tabular data and powerful vision-based machine learning models, unlocking new possibilities for tackling regression, classification, and other complex tasks.

---

📚 Features

• Input formats: CSV or Pandas DataFrame
• Designed for tidy data (target column last)
• Output: grayscale images from reduction and transformation methods
• Compatible with Linux, Windows, macOS
• Requires Python 3.8+

---

🧪 Methods

TINTOlib includes a variety of methods for generating synthetic images. Below is a summary of the supported methods and their hyperparameters:

Methods	Class	Hyperparameters
TINTO	TINTO()	problem transformer verbose pixels algorithm blur submatrix amplification distance steps option times train_m zoom format cmap random_seed
IGTD	IGTD()	problem transformer verbose scale fea_dist_method image_dist_method error max_step val_step switch_t min_gain zoom format cmap random_seed
REFINED	REFINED()	problem transformer verbose hcIterations n_processors zoom format cmap random_seed
BarGraph	BarGraph()	problem transformer verbose pixel_width gap zoom
DistanceMatrix	DistanceMatrix()	problem transformer verbose zoom
Combination	Combination()	problem transformer verbose zoom
SuperTML	SuperTML()	problem transformer verbose pixels feature_importance font_size random_seed
FeatureWrap	FeatureWrap()	problem transformer verbose size bins zoom
BIE	BIE()	problem transformer verbose precision zoom
Fotomics	Fotomic()	image_dim problem transformer verbose outliers min_percentile max_percentile outliers_treatment assignment_method relocate algorithm_opt group_method zoom format cmap random_seed
DeepInsight	DeepInsight()	image_dim problem transformer verbose assignment_method relocate algorithm_opt group_method zoom format cmap random_seed

---

⚠️ Platform-Specific Requirements for Certain Transformation Methods

Some transformation methods in TINTOlib have specific system requirements or limitations when used on platforms such as Google Colab, Windows, Linux, or macOS.

REFINED

This method relies on mpi4py, which enables parallel computation using MPI (Message Passing Interface). However, mpi4py requires administrative permissions to utilize multiple processors, making it incompatible with platforms like Google Colab.

• Linux: Ensure that the MPI environment is set up before installing mpi4py. Run the following commands:

    sudo apt-get install python3
    sudo apt install python3-pip
    sudo apt install python3-mpi4py
  

  Once MPI is installed:

    pip install mpi4py
  

• MacOS / Windows: Direct installation is usually supported:

    pip install mpi4py
  

SuperTML

The SuperTML method generates text-based synthetic images and requires the MS Sans Serif font.

• On Windows, this font is typically available by default.
• On Linux and macOS, it must be installed manually to avoid rendering issues.

Font Installation

• Linux: Install Microsoft Core Fonts:

    sudo apt install ttf-mscorefonts-installer
  

On Google Colab, installing additional fonts is not permitted due to administrative restrictions.

📄 Getting Started

• You can install TINTOlib using Pypi:

    pip install TINTOlib
  

TINTOlib already includes all necessary dependencies, so there’s no need to install them individually.

However, if you prefer manual installation or want to explore the full environment:

• The repository includes a requirements.txt file listing the core dependencies required to use TINTOlib. You can directly run the TINTOlib-example.ipynb notebook located in the examples/ folder using the dependencies listed in requirements.txt.
• mpi4py is only required if you use the REFINED method; see the platform-specific notes.
• Other notebooks, which include training deep learning models on the generated images, require additional libraries. To run them, install the extended dependencies from requirements-example.txt:

---

🧩 Importing a Specific Model

• To use a specific image transformation model, import it directly. For example, to use TINTO:

    from TINTOlib.tinto import TINTO
  

• To import a specific model use:

    from TINTOlib.tinto import TINTO
  

• Create the model. If you don't set any hyperparameter, the model will use the default values, refer to the Models Section or the TINTO Documentation.

    model = TINTO(problem="supervised", blur=True)
  

---

🔧 Generating Synthetic Images

To generate synthetic images, use the following workflow with the fit, transform, and fit_transform methods:

Parameters:

• data: A path to a CSV file or a Pandas DataFrame (target column must be the last column).
• folder: Path to the folder where the synthetic images will be saved.

Sintaxis

1. The fit method trains the model on the tabular data and prepares it for image generation.

     model.fit(data)
   

2. The transform method generates and saves synthetic images in a specified folder. It requires the model to be fitted first.

     model.transform(data, folder)
   

3. The fit_transform method combines the training and image generation steps. It fits the model to the data and generates synthetic images in one step.

  model.fit_transform(data, folder)

Notes:

• The model must be fitted before using the transform method. If the model isn't fitted, a RuntimeError will be raised.

Iris dataset Example

To get started with TINTOlib, a dedicated Crash Course Repository is available. It includes videoturials, slides and Jupyter Notebooks that demonstrate how to apply state-of-the-art vision models like Vision Transformers (ViTs), Convolutional Neural Networks (CNNs) and Hybrid Neural Networks to problems.

For example, the following table shows a classic example of the IRIS CSV dataset as it should look like for the run:

sepal length	sepal width	petal length	petal width	target
4.9	3.0	1.4	0.2	1
7.0	3.2	4.7	1.4	2
6.3	3.3	6.0	2.5	3

• The following example shows how to execute TINTOlib using the TINTO method and then display the synthetic image generated for the first row:

    model = TINTO(problem="supervised", pixels=30, algorithm="t-SNE", steps=5, blur=True)
    model.fit_transform("iris.csv", "synthetic_images")
  

---

🚀 Vision-based Neural Network Architectures

Using synthetic images, experiment with either vision models like CNNs or ViTs, and explore hybrid models. Below are the architectures that will be presented, and the ones you will modify and use during the session:

• Synthetic images using CNN
  

• Synthetic images using Hybrid Neural Network with ViT (HyViT)
  

---

💬 More information

• For more detailed information, refer to the TINTOlib ReadTheDocs.
• GitHub repository: TINTOlib Documentation.
• PyPI: PyPI.

---

📖 Citation

If you use TINTOlib in your research, please cite our papers:

• SoftwareX journal:

  @article{LIU2025102444,
    title = {TINTOlib: A Python library for transforming tabular data into synthetic images for deep neural networks},
    journal = {SoftwareX},
    volume = {32},
    pages = {102444},
    year = {2025},
    issn = {2352-7110},
    doi = {https://doi.org/10.1016/j.softx.2025.102444}
  }

• Information Fusion journal:

@article{LIU2026104088,
    title = {A comprehensive benchmark of spatial encoding methods for tabular data with deep neural networks},
    journal = {Information Fusion},
    volume = {130},
    pages = {104088},
    year = {2026},
    doi = {10.1016/j.inffus.2025.104088}
  }

---

🛡️ License

TINTOlib is available under the Apache License 2.0.

---

👥 Authors

• Manuel Castillo-Cara
• Raúl García-Castro
• David González Fernández
• Jiayun Liu
• Javier López

---

🏛️ Contributors