Skip to main content

TINTOlib: Python Library to convert Tabular Data into Synthetic Images

GitHub Pages License Python Version Documentation Status Open In Colab-CNN Open In Colab-CNN+MLP Open In Colab-ViT Open In Colab-ViT+MLP Ask DeepWiki PyPI Downloads


TINTO Logo

📊 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.

Access the Course on Udemy


🎬 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.

Access the Course on GitHub


🧠 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.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 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 correlated
Fotomics Fotomics() 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
Clusters Clusters() problem normalize verbose algorithm n_clusters random_seed n_init max_iter algorithmMethod covariance_type ensamMethod bandwidth kernel metric RBFMethod

BIE/cBIE in TINTOlib 1.4.0 (default behavior change relative to 1.3.4): The default BIE() / BIE(correlated=True) uses the Pearson/greedy feature-ordering algorithm from Javier López's PR #30 for supervised classification and regression; it learns the ordering only in fit (with positional X/y alignment) and reuses it in transform as a transformation of observations without generating new observations or claiming default predictive-performance improvement. Select BIE(correlated=False) to obtain the original binary image encoding and preserve the feature order (no correlation calculation); this is also the behavior of problem="unsupervised" regardless of correlated. The user controls preprocessing of X and y, including any external numeric encoding of classification targets; no internal label encoder is introduced. Multiclass numeric encodings can change the learned spatial layout. Only in correlated supervised mode, undefined/non-finite Pearson correlations (e.g., constant training features or target) raise a descriptive ValueError; no values are imputed or substituted. No new feature-schema validation is introduced: callers remain responsible for consistent feature columns across fit and transform; pre-existing pandas/scikit-learn errors may still occur for incompatible inputs. The default MinMaxScaler remains isolated per instance, and unsupervised X-only exports remain supported as in 1.3.4. See cBIE.

from TINTOlib.bie import BIE
bie_correlated = BIE()  # Equivalent to BIE(correlated=True)
bie_classic = BIE(correlated=False)  # Original BIE feature order

⚠️ 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 and an MPI runtime for parallel computation. Since TINTOlib 1.3.4 (retained in 1.4.0), the refined and all extras constrain NumPy to <2.4 for Python below 3.14 and >=2.5,<2.6 for Python 3.14 or later; these metadata constraints are not a universal compatibility guarantee. Running MPI does not inherently require administrator permissions; permissions depend on how the runtime is installed. See the mpi4py installation guide for supported environments.

  • Linux: REFINED currently launches mpirun with Open MPI options. On Debian/Ubuntu, install Open MPI:

      sudo apt install openmpi-bin libopenmpi-dev
    

    Once MPI is installed:

      pip install "TINTOlib[refined]"
    
  • macOS: Install Open MPI (for example, brew install open-mpi), then install TINTOlib[refined] in your Python environment.

  • Windows: Install an MPI runtime supported by mpi4py, such as Microsoft MPI, and ensure mpiexec is available on PATH. Then install the Python extra:

      pip install "TINTOlib[refined]"
    

On Google Colab or other hosted notebooks, REFINED requires a compatible MPI runtime and permission to launch subprocesses. Availability depends on the notebook environment.

SuperTML

The SuperTML method generates text-based synthetic images and loads the Arial font using ImageFont.truetype("arial.ttf", ...). Ensure that arial.ttf is discoverable by Pillow.

  • On Windows, Arial is typically installed with the operating system.
  • On Linux and macOS, check that Arial is installed and that Pillow can locate the file under the name arial.ttf.

Font Installation

  • Linux: Install Microsoft Core Fonts:

      sudo apt install ttf-mscorefonts-installer
    

You can check font availability in any environment, including Google Colab, with:

from PIL import ImageFont
ImageFont.truetype("arial.ttf", 10)

If this raises OSError, install Arial where permitted or place a legally obtained arial.ttf file in the working directory.

📄 Getting Started

  • You can install TINTOlib using Pypi:
      pip install TINTOlib
    

Installing TINTOlib installs its core Python dependencies automatically. Optional methods require the extras and system resources described below.

Optional methods can be installed using dependency extras:

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

Tested Python 3.14 environments (TINTOlib 1.3.4 historical baseline and 1.4.0 source-tree validation)

The package declares requires-python = ">=3.9" and TINTOlib 1.4.0 lists Python 3.9-3.14 in its classifiers. Python 3.14 is intended to be supported without an OS-specific restriction in package metadata; optional runtime requirements (notably MPI for REFINED) remain platform-dependent. The following is tested environment evidence, not a guarantee that every version, platform, method option, or workflow behaves identically:

The maintainer also reports successful use with Python 3.14 on a server on 19 November 2026. The server operating system, dependency versions, method coverage, and execution receipts have not been independently inspected for this report; do not present this statement as a cross-platform test-matrix certification.

Environment Evidence available Scope
CPython 3.14.9, macOS ARM64, core dependencies R13-S9, 16 November 2026: 12/12 small tabular-to-PNG fit_transform cases and 144/144 readable PNG files TINTO, IGTD, BIE, BarGraph, DistanceMatrix, Combination, FeatureWrap, SuperTML-EF/VF, CLUSTERS-kmeans, DeepInsight-PCA and Fotomics; not every hyperparameter or CLUSTERS backend
CPython 3.14.9, macOS ARM64, refined / all extras G4-S3B/S3C, 16 November 2026: clean extra installations and successful synthetic REFINED fit/transform, with MPI invoked Functional evidence for tested REFINED configurations; MPI worker count was not independently established from the receipts
CPython 3.14.10, macOS ARM64, core dependencies (1.4.0 source tree) G2-FUNCTIONAL-31410-R2, 20 November 2026: 14/14 synthetic BIE/cBIE integration tests PASS (0 fail, 0 error, 0 skip) Supervised cBIE default, classic correlated=False, unsupervised X-only, positional index invariance, persistence, and error contracts; source-tree only, not packaged wheel/sdist, MPI, or cross-platform certification

The tested base profile used NumPy 2.5.5, pandas 2.3.3, SciPy 1.18.1, scikit-learn 1.9.1, Matplotlib 3.11.2, Pillow 12.3.0, bitstring 4.4.0, scikit-image 0.26.0 and tqdm 4.70.1. The tested REFINED extra also included mpi4py 4.1.2. These versions are verified, not proven optimal by a dependency-version comparison.

For these two environments, the source repository provides complete version-pin snapshots (direct and transitive Python dependencies) in:

From a checkout of the 1.3.4 source on a compatible macOS ARM64 system, these files can be used as pip constraints (they do not by themselves install TINTOlib):

python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -e . -c requirements-tested-py314-macos-arm64-base.txt
# OR, in a separate fresh environment after installing an MPI runtime:
python -m pip install -e ".[refined]" -c requirements-tested-py314-macos-arm64-refined.txt
python -m pip check

Choose one installation profile per fresh virtual environment. The commands above are installation guidance for a future checkout, not a newly executed reproducibility test. Exact Python-package versions reduce resolution variability but do not pin wheel hashes, operating-system libraries or MPI binaries. The two snapshots are version-controlled for source-checkout users; the current pyproject.toml source-distribution whitelist does not include them in the sdist or wheel. Ordinary users may install the released package with pip install "TINTOlib[refined]" and should consult the package metadata for supported version ranges.

REFINED / MPI: REFINED needs mpi4py and a separate working MPI runtime, such as Open MPI on macOS (brew install open-mpi, mpirun --version). Python dependency files cannot install or configure that system runtime. The G4-S3C evidence confirms successful REFINED execution in the tested environments but does not establish a universal MPI version requirement. On Windows/Linux and hosted notebook services, verify the runtime and compatibility separately.

SuperTML / fonts: The tested macOS ARM64 system had Arial available to Pillow at /System/Library/Fonts/Supplemental/Arial.ttf. SuperTML requests arial.ttf by name. Use a legally installed, discoverable font; do not redistribute font binaries with the package or test receipts.

For Python below 3.14, the refined and all extras (introduced in 1.3.4 and retained in 1.4.0) constrain NumPy to <2.4; for Python 3.14 or later, their NumPy constraint is >=2.5,<2.6. These are dependency-resolution conditions, not a claim of runtime testing across every Python version or operating system. The release remains subject to its separate publication checklist.

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.
  • Other notebooks, which include training deep learning models on the generated images, require additional libraries. From the repository root, install the extended dependencies with pip install -r 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 Methods Section or the TINTO Documentation.

      model = TINTO(problem="classification", 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="classification", pixels=30, algorithm="t-SNE", steps=5, blur=True)
      model.fit_transform("iris.csv", "synthetic_images")
    

TINTO blurring


🚀 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

  • Synthetic images using Hybrid Neural Network with ViT (HyViT)
    Tabular-to-Image HyNNViT


💬 More information


📖 Citation

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

  @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}
  }
@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


🏛️ Contributors

Ontology Engineering Group Universidad Politécnica de Madrid Universidad Nacional de Educación a Distancia Universidad de Castilla-La Mancha

Metadata

Release files for TINTOlib 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for TINTOlib 1.4.0
File Size Uploaded Provenance Actions
tintolib-1.4.0.tar.gz 98.3 kB With provenance Details for tintolib-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for TINTOlib 1.4.0
File Interpreter ABI Platform Actions
tintolib-1.4.0-py3-none-any.whl Python 3 none any Details for tintolib-1.4.0-py3-none-any.whl

Total release size: 185.8 kB

Release files / tintolib-1.4.0.tar.gz

Download URL tintolib-1.4.0.tar.gz
Size 98.3 kB
Tags Source
SHA-256 checksum
How to use checksums
5fe1ae050c4de134bfb27af56fe214eb8bb3678c6b4e71d32ebbf7ea03eb452a
BLAKE2b-256 checksum
How to use checksums
7a027b4ada395bf3f42f66e7ca6d6d83d28f376434da0da07d0770b06cbd0079
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / tintolib-1.4.0-py3-none-any.whl

Download URL tintolib-1.4.0-py3-none-any.whl
Size 87.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d7cf6c5fcce3ce637b50560fa47f44ea3100dfa0283a016274b25f0ceed9b84d
BLAKE2b-256 checksum
How to use checksums
b6d8152c25b78e920ea26f7cab44d6eb38f491bc569908958f2856d2ef1cc8d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for TINTOlib 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tintolib-1.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page