TINTOlib

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #go #android #machine-learning #rust #docker #windows #vue #ios #openai

(★ 16)

Pip package for converting tabular data into synthetic images

TINTOlib Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TINTOlib: Python Library to convert Tabular Data into Synthetic Images

[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-View%20Documentation-brightgreen?logo=github)](https://oeg-upm.github.io/TINTOlib/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/oeg-upm/TINTOlib-Documentation/blob/main/LICENSE)
[![Python Version](https://shields.io/badge/python-3.9+-blue)](https://pypi.python.org/pypi/)
[![Documentation Status](https://readthedocs.org/projects/morph-kgc/badge/?version=latest)](https://tintolib.readthedocs.io/en/latest/)
[![Open In Colab-CNN](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/oeg-upm/TINTOlib-Crash_Course/blob/main/Notebooks/Challenge/Regression_CNN.ipynb)
[![Open In Colab-CNN+MLP](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/oeg-upm/TINTOlib-Crash_Course/blob/main/Notebooks/Challenge/Regression_CNN%2BMLP.ipynb)
[![Open In Colab-ViT](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/oeg-upm/TINTOlib-Crash_Course/blob/main/Notebooks/Challenge/Regression_ViT.ipynb)
[![Open In Colab-ViT+MLP](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/oeg-upm/TINTOlib-Crash_Course/blob/main/Notebooks/Challenge/Regression_ViT%2BMLP.ipynb)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/oeg-upm/TINTOlib)
[![PyPI Downloads](https://static.pepy.tech/badge/tintolib)](https://pepy.tech/projects/tintolib)

---

## 📊 Benchmarks & Results

- Explore detailed benchmark results, model comparisons, and performance tables for TINTOlib on various datasets.
- 👉 **See the latest benchmarks:** [TINTOlib Benchmarks (GitHub Pages)](https://oeg-upm.github.io/TINTOlib/)

---

## 🎉 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.

<!--
**Citing TINTO**: If you used TINTO in your work, please cite the **[SoftwareX](https://doi.org/10.1016/j.softx.2023.101391)**:

```bib
@article{softwarex_TINTO,
    title = {TINTO: Converting Tidy Data into Image for Classification with 2-Dimensional Convolutional Neural Networks},
    journal = {SoftwareX},
    author = {Manuel Castillo-Cara and Reewos Talla-Chumpitaz and Raúl García-Castro and Luis Orozco-Barbosa},
    volume={22},
    pages={101391},
    year = {2023},
    issn = {2352-7110},
    doi = {https://doi.org/10.1016/j.softx.2023.101391}
}
```

And use-case developed in **[INFFUS Paper](https://doi.org/10.1016/j.inffus.2022.10.011)**

```bib
@article{inffus_TINTO,
    title = {A novel deep learning approach using blurring image techniques for Bluetooth-based indoor localisation},
    journal = {Information Fusion},
    author = {Reewos Talla-Chumpitaz and Manuel Castillo-Cara and Luis Orozco-Barbosa and Raúl García-Castro},
    volume = {91},
    pages = {173-186},
    year = {2023},
    issn = {1566-2535},
    doi = {https://doi.org/10.1016/j.inffus.2022.10.011}
}
```
-->
---

## 📚 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.9+**

---

## 🧪 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](https://github.com/oeg-upm/TINTO)                         |      `TINTO()`       |                    `problem` `transformer` `verbose` `pixels` `algorithm` `blur` `submatrix` `amplification` `distance` `steps` `option` `times` `train_m` `zoom` `format` `cmap` `random_seed`                     |
|                         [IGTD](https://github.com/zhuyitan/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](https://github.com/omidbazgirTTU/REFINED)                    |     `REFINED()`      |                                                        `problem` `transformer` `verbose` `hcIterations` `n_processors` `zoom` `format` `cmap` `random_seed`                                                         |
|    [BarGraph](https://github.com/anuraganands/Non-image-data-classification-with-CNN/)    |     `BarGraph()`     |                                                                            `problem` `transformer` `verbose` `pixel_width` `gap` `zoom`                                                                             |
| [DistanceMatrix](https://github.com/anuraganands/Non-image-data-classification-with-CNN/) |  `DistanceMatrix()`  |                                                                                      `problem` `transformer` `verbose` `zoom`                                                                                       |
|  [Combination](https://github.com/anuraganands/Non-image-data-classification-with-CNN/)   |   `Combination()`    |                                                                                      `problem` `transformer` `verbose` `zoom`                                                                                       |
|             [SuperTML](https://github.com/GilesStrong/SuperTML_HiggsML_Test)              |     `SuperTML()`     |                                                              `problem` `transformer` `verbose` `pixels` `feature_importance` `font_size` `random_seed`                                                              |
|       [FeatureWrap](https://link.springer.com/chapter/10.1007/978-3-319-70139-4_87)       |   `FeatureWrap()`    |                                                                               `problem` `transformer` `verbose` `size` `bins` `zoom`                                                                                |
|                   [BIE](https://ieeexplore.ieee.org/document/10278393)                    |       `BIE()`        |                                                                                `problem` `transformer` `verbose` `precision` `zoom`                                                                                 |
|          [Fotomics](https://www.biorxiv.org/content/10.1101/2022.07.08.499309v2)          |     `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](https://www.nature.com/articles/s41598-019-47765-6)             |   `DeepInsight()`    |                                  `image_dim` `problem` `transformer` `verbose`  `assignment_method` `relocate` `algorithm_opt` `group_method` `zoom` `format` `cmap` `random_seed`                                  |
|             Clusters                                                                      |   `Clusters()`       |                                  `problem` `transformer` `verbose` `algorithm` `n_clusters` `random_seed` `n_init` `max_iter` `algorithmMethod` `covariance_type` `ensamMethod` `bandwidth` `kernel` `metric` `RBFKmeans` `zoom`                                  |

---

<a id="platform-specific-notes"></a>
## ⚠️ 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:

```bash
      sudo apt-get install python3
      sudo apt install python3-pip
      sudo apt install python3-mpi4py
    ```
  Once MPI is installed:

```bash
      pip install "TINTOlib[refined]"
    ```
- **MacOS / Windows:** Direct installation is usually supported:

```bash
      pip install "TINTOlib[refined]"
    ```

### 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:
  
    ```bash
      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](https://pypi.org/project/TINTOlib/)**:
    ```bash
      pip install TINTOlib
    ```

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

Optional methods can be installed using dependency extras:

```bash
pip install "TINTOlib[greedy]"  # Greedy feature-to-pixel assignment
pip install "TINTOlib[refined]" # REFINED and mpi4py
pip install "TINTOlib[all]"     # All optional methods
```

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

- The repository includes a `requirements.txt` file that installs TINTOlib and its core dependencies in editable mode for local development.
- **mpi4py** is installed by the `refined` extra and is only required for **REFINED**; an MPI runtime must also be installed as described in the [platform-specific notes](#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**:

```python
      from TINTOlib.tinto import TINTO
    ```

- To import a specific model use: 
    ```python
      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](#models)** or the **[TINTO Documentation](https://tintolib.readthedocs.io/en/latest/)**.

```python
      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.
    ```python
      model.fit(data)
    ```

2. The `transform` method generates and saves synthetic images in a specified folder. It requires the model to be fitted first.
    ```python
      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.

```python
    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](https://github.com/oeg-upm/TINTOlib-Crash_Course)** 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.
<!--It includes:

- **Slides and Jupyter notebooks** demonstrating how to:
  - Transform tabular data into images using **TINTOlib**.
  - Apply state-of-the-art vision models like **Vision Transformers (ViTs)** and **Convolutional Neural Networks (CNNs)** to classification and regression problems.

- Integration of **Hybrid Neural Networks (HyNNs)**, where:
  - **One branch** (MLP) processes the original tabular data.
  - **Another branch** (CNN or ViT) processes synthetic images.

This architecture leverages the strengths of both tabular and image-based data representations, enabling improved performance on complex machine learning tasks. The repository is ideal for those looking to integrate image-based deep learning techniques into tabular data workflows.
-->

For example, the following table shows a classic example of the [IRIS CSV dataset](https://archive.ics.uci.edu/ml/datasets/iris) 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:

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

<div>
<p align = "center">
<kbd><img src="https://raw.githubusercontent.com/DCY1117/TEMP-Images/refs/heads/main/TINTOlib-images/blurring.png" alt="TINTO blurring" width="250"></kbd>
</p>
</div>

---

## 🚀 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**  
  ![Tabular-to-Image CNN](https://raw.githubusercontent.com/oeg-upm/TINTOlib/main/imgs/Tabular-to-image-CNN.jpg)

- **Synthetic images using Hybrid Neural Network with ViT (HyViT)**  
  ![Tabular-to-Image HyNNViT](https://raw.githubusercontent.com/oeg-upm/TINTOlib/main/imgs/HybridViT.png)

---

## 💬 More information

- For more detailed information, refer to the **[TINTOlib ReadTheDocs](https://tintolib.readthedocs.io/en/latest/)**.  
- GitHub repository: **[TINTOlib Documentation](https://github.com/oeg-upm/TINTOlib-Documentation)**.
- PyPI: **[PyPI](https://pypi.org/project/TINTOlib/)**.

---

## 📖 Citation

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

- [SoftwareX journal](https://doi.org/10.1016/j.softx.2025.102444):

```bibtex
  @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](https://doi.org/10.1016/j.inffus.2025.104088):

```
@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](https://github.com/oeg-upm/TINTOlib-Documentation/blob/main/LICENSE)**.

---

## 👥 Authors
- **[Manuel Castillo-Cara](https://github.com/manwestc)**
- **[Raúl García-Castro](https://github.com/rgcmme)**
- **[David González Fernández](https://github.com/DavidGonzalezFernandez)**
- **[Jiayun Liu](https://github.com/DCY1117)**
- **[Javier López](https://github.com/javilecrin)**
---

## 🏛️ Contributors

TINTOlib

TINTOlib Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

TINTOlib

TINTOlib Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README