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.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
mpirunwith 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 installTINTOlib[refined]in your Python environment. -
Windows: Install an MPI runtime supported by
mpi4py, such as Microsoft MPI, and ensurempiexecis available onPATH. 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.txtfile that installs TINTOlib and its core dependencies in editable mode for local development. - mpi4py is installed by the
refinedextra 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
-
The
fitmethod trains the model on the tabular data and prepares it for image generation.model.fit(data)
-
The
transformmethod generates and saves synthetic images in a specified folder. It requires the model to be fitted first.model.transform(data, folder)
-
The
fit_transformmethod 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
transformmethod. If the model isn't fitted, aRuntimeErrorwill 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")
🚀 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.
- Release notes: Changelog.
📖 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
- Manuel Castillo-Cara
- Raúl García-Castro
- David González Fernández
- Jiayun Liu
- Javier López
- Salvador Martínez-Moreno
🏛️ Contributors
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.