DOCSEARCHbyAlgolia
Submit Docs

PyTorch Frame

repository·main·Indexed 21 days ago

https://github.com/pyg-team/pytorch-frame

A modular deep learning library for PyTorch designed for heterogeneous tabular data. It supports diverse column types including numerical, categorical, text, and images, and provides a structured pipeline consisting of Materialization, FeatureEncoder, TableConv, and Decoder. The library includes implementations of models such as TabNet, FTTransformer, ResNet, ExcelFormer, and TabTransformer, along with benchmarking tools for comparing deep learning models against GBDTs like XGBoost, CatBoost, and LightGBM.

Tokens
15.8K
Snippets
37
Records
52
Agent score
73%

What's inside pytorch-frame

  1. Overview of torch_frame.data module

    main

    The torch_frame.data module provides the core data abstractions required for handling tabular data in PyTorch Frame. It is organized into four main functional areas:

    1. Data Objects: Core classes for representing tabular datasets and their features.
    2. Stats: Classes for computing and storing statistical information about datasets (e.g., for normalization or encoding).
    3. Data Loaders: Specialized loaders designed to feed tabular data into deep learning models efficiently.
    4. Helper Functions: Utility functions to assist with data processing and transformation tasks.

  2. Benchmark performance of deep tabular models

    main

    PyTorch Frame benchmarks recent deep tabular learning models against Gradient Boosted Decision Trees (GBDTs) like XGBoost, CatBoost, and LightGBM. The benchmarks cover various dataset sizes and task types (regression and classification).

    For detailed results on classification and larger datasets, refer to the benchmark documentation.

  3. Explore available datasets in torch_frame.datasets

    main

    The torch_frame.datasets module provides access to various datasets categorized into three main groups for deep tabular modeling:

    1. Real-World Datasets: Datasets derived from actual real-world scenarios.
    2. Synthetic Datasets: Artificially generated datasets used for testing and benchmarking.
    3. Other Datasets: Additional datasets that do not fall into the primary categories.

    You can access these datasets by inspecting the torch_frame.datasets.real_world_datasets, torch_frame.datasets.synthetic_datasets, and torch_frame.datasets.other_datasets collections.

  4. Compare pytorch-frame and pytorch-tabular performance

    main

    The pytorch_tabular_benchmark tool is used to compare the performance of pytorch-frame against pytorch-tabular.

    While pytorch-tabular is designed for accessibility and quick experimentation with standard tabular tasks (including training loop modifications and explainability), pytorch-frame is designed for flexibility in building novel tabular learning approaches. pytorch-frame supports a wider array of data types, more sophisticated encoding schemas, and streamlined integration with LLMs.

    Benchmark results typically compare iterations per second (iters/sec) for specific models like TabNet and FTTransformer.

    | Package         | Model         | Num iters/sec |
| :-------------- | :------------ | :------------ |
| PyTorch Tabular | TabNet        | 41.7          |
| PyTorch Frame   | TabNet        | 45.0          |
| PyTorch Tabular | FTTransformer | 40.1          |
| PyTorch Frame   | FTTransformer | 43.7          |

  5. Explore the torch_frame.nn module hierarchy

    main

    The torch_frame.nn module provides the neural network building blocks for deep tabular learning. It is organized into several specialized submodules:

    • torch_frame.nn.encoder: Contains encoder classes for transforming tabular data into latent representations.
    • torch_frame.nn.encoding: Provides encoding mechanisms for handling different data types.
    • torch_frame.nn.conv: Contains convolutional layers or operations specialized for tabular structures.
    • torch_frame.nn.decoder: Provides decoder classes for reconstructing data or mapping latent representations to specific outputs.
    • torch_frame.nn.models: Contains high-level, end-to-end deep tabular models that compose the other components.

  6. Difference between text_embedded and text_tokenized stypes

    main

    PyTorch Frame provides two primary ways to handle text columns:

    1. stype.text_embedded: Text is pre-encoded into fixed embeddings during the dataset materialization stage. This is faster during training but the text model itself is not trained.
    2. stype.text_tokenized: Only minimal processing (tokenization) occurs during materialization. The raw text is transformed into sequences of integers (e.g., input_ids and attention_mask). This allows for end-to-end fine-tuning of the text model (like BERT or DistilBERT) during the training stage.

  7. Apply data transformations with torch_frame.transforms

    main

    PyTorch Frame provides a suite of transforms that can operate across different stypes (feature types) or within the same stype. Transforms are designed to work with both TensorFrame objects and column statistics (col_stats).

    To use a transform, you typically follow a fit and transform workflow:

    1. Initialize the transform (e.g., CatToNumTransform()).
    2. Fit the transform using a training TensorFrame and the dataset's col_stats to learn the necessary parameters.
    3. Transform a TensorFrame (such as a test split) using the fitted transform. This will update the feature types and column names accordingly.
    from torch_frame.datasets import Yandex
from torch_frame.transforms import CatToNumTransform
from torch_frame import stype

# 1. Setup dataset
dataset = Yandex(root='/tmp/adult', name='adult')
dataset.materialize()
train_dataset = dataset.get_split('train')
test_dataset = dataset.get_split('test')

# 2. Initialize and fit transform
transform = CatToNumTransform()
transform.fit(train_dataset.tensor_frame, dataset.col_stats)

# 3. Apply transform to test data
transformed_test_frame = transform(test_dataset.tensor_frame)

  8. How PyTorch Frame models work: Architecture Overview

    main

    PyTorch Frame uses a modular design to process heterogeneous tabular data. The architecture consists of four main stages:

    1. Materialization: Converts raw pandas DataFrame objects into a TensorFrame, which is the specialized format used for PyTorch-based training.
    2. FeatureEncoder: Transforms the TensorFrame into hidden column embeddings with the shape [batch_size, num_cols, channels].
    3. TableConv: Models the interactions between different columns using the hidden embeddings.
    4. Decoder: Aggregates the column embeddings to generate a final prediction or embedding per row.

    This modularity allows users to swap out specific components (like different encoders or convolution layers) to experiment with new architectures.

  9. How text columns are handled in PyTorch Frame

    main

    PyTorch Frame supports two primary strategies for handling text columns, which are selected by specifying the appropriate semantic type (stype) in the col_to_stype argument of the Dataset object:

    1. Pre-encoding (Frozen Embeddings): Use stype.text_embedded. Text is converted into embeddings during the dataset materialization stage. The model parameters for the text encoder are frozen during training. This is faster for training but may be less accurate.
    2. Fine-tuning (Tokenized Text): Use stype.text_tokenized. Text is tokenized during materialization, but the actual embeddings are generated during the training stage. This allows for fine-tuning the text model parameters, providing higher accuracy at the cost of more intensive training.

    Choose text_embedded for speed and text_tokenized for maximum predictive performance.

  11. How deep tabular models are designed in PyTorch Frame

    main

    PyTorch Frame follows a modular design for deep tabular models consisting of three primary components that process data in a specific pipeline:

    1. FeatureEncoder: Converts a TensorFrame (where columns are organized by semantic types/stype) into a 3-dimensional torch.Tensor of shape [batch_size, num_cols, channels].
    2. TableConv: Takes the encoded tensor and iteratively updates column embeddings to model complex interactions between different columns.
    3. Decoder: Transforms the updated column embeddings into a final output tensor of shape [batch_size, out_channels], representing the row embeddings.

    Data Flow Summary: DataFrame $\rightarrow$ TensorFrame $\rightarrow$ FeatureEncoder $\rightarrow$ TableConv $\rightarrow$ Decoder $\rightarrow$ Output

  12. Analyze Benchmark Latency and Profiling Outputs

    main

    The benchmark provides three types of output depending on the flags used:

    1. Latency: Always outputted. Shows the single run execution time (e.g., Latency: 0.034277s).
    2. Torch Profiling: Enabled via --torch-profile. Produces a table of PyTorch operations (e.g., aten::cat, aten::add) sorted by execution time, including Self CPU %, CPU total %, and number of calls.
    3. Line Profiling: Enabled via --line-profile. Shows the time distribution across specific lines of code within a target function (defined by --line-profile-level). It displays hits, time, per-hit time, and percentage of total time spent on each line.