PyTorch Frame

https://pytorch-frame.readthedocs.io/en/latest/
Admin
PyTorch Frame is a library built upon PyTorch to easily write and train tabular deep learning models...
Tokens:48,196
Snippets:400
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install PyTorch Frame via PyPI

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/installation.rst.txt

Use this command for a standard installation of PyTorch Frame. For additional features, use the `[full]` option.

```bash
pip install pytorch-frame
```

```bash
pip install pytorch-frame[full]
```

--------------------------------

### Install PyTorch Frame for Development

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/installation.rst.txt

Clone the repository and install in editable mode for development. Include `[dev]` for development dependencies and `[full]` for optional dependencies.

```bash
git clone https://github.com/pyg-team/pytorch-frame.git
cd pytorch-frame
pip install -e .[dev]
```

```bash
pip install -e .[dev,full]
```

--------------------------------

### Install PEFT for Model Finetuning

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Install the PEFT (Parameter-Efficient Fine-Tuning) library using pip, which is used for finetuning models with strategies like LoRA.

```bash
pip install peft
```

--------------------------------

### Install Sentence Transformers

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Install the required package for text embedding models.

```bash
pip install -U sentence-transformers
```

--------------------------------

### Install Transformers Package

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Installs the Hugging Face Transformers library, which is used for fine-tuning text models.

```bash
pip install transformers
```

--------------------------------

### Install PyTorch Frame from Master Branch

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/installation.rst.txt

Install the latest version directly from the GitHub master branch using pip.

```bash
pip install git+https://github.com/pyg-team/pytorch-frame.git
```

--------------------------------

### Load Hugging Face Dataset with torch-frame

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.HuggingFaceDatasetDict.html

Load the spotify-tracks-dataset from Hugging Face Hub into a torch-frame.Dataset. This example demonstrates specifying columns, a target column, and configuring text embedders. Materialize the dataset and inspect its TensorFrame structure.

```python
from torch_frame.datasets import HuggingFaceDatasetDict
from torch_frame.config.text_embedder import TextEmbedderConfig
from torch_frame.testing.text_embedder import HashTextEmbedder
dataset = HuggingFaceDatasetDict(
    path="maharshipandya/spotify-tracks-dataset",
    columns=["artists", "album_name", "track_name",
             "popularity", "duration_ms", "explicit",
             "danceability", "energy", "key", "loudness",
             "mode", "speechiness", "acousticness",
             "instrumentalness", "liveness", "valence",
             "tempo", "time_signature", "track_genre"
    ],
    target_col="track_genre",
    col_to_text_embedder_cfg=TextEmbedderConfig(
        text_embedder=HashTextEmbedder(10)),
)
dataset.materialize()
dataset.tensor_frame

```

--------------------------------

### StypeWiseFeatureEncoder Usage Example

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/modular_design.rst.txt

Demonstrates how to initialize StypeWiseFeatureEncoder with different stype-specific encoders for categorical, numerical, and embedding features. Ensure 'channels', 'col_stats', and 'col_names_dict' are defined prior to use.

```python
from torch_frame import stype
from torch_frame.nn import (
    StypeWiseFeatureEncoder,
    EmbeddingEncoder,
    LinearEmbeddingEncoder,
    LinearEncoder,
)

stype_encoder_dict = {
    stype.categorical: EmbeddingEncoder(),
    stype.numerical: LinearEncoder(),
    stype.embedding: LinearEmbeddingEncoder(),
}

encoder = StypeWiseFeatureEncoder(
    out_channels=channels,
    col_stats=col_stats,
    col_names_dict=col_names_dict,
    stype_encoder_dict=stype_encoder_dict,
)
```

--------------------------------

### GET /torch_frame.data/download_url

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.download_url.html

Downloads the content of a specified URL to a local root folder.

```APIDOC
## download_url

### Description
Downloads the content of a URL to the specified folder root.

### Parameters
#### Arguments
- **url** (str) - Required - The URL to download.
- **root** (str) - Required - The root folder where the file will be saved.
- **filename** (str) - Optional - If set, will rename the downloaded file. (default: None)
- **log** (bool) - Optional - If False, will not print anything to the console. (default: True)

### Response
- **Returns** (str) - The path to the downloaded file.
```

--------------------------------

### Initialize a Benchmark Dataset

Source: https://pytorch-frame.readthedocs.io/en/latest/get_started/introduction.html

Demonstrates loading the Titanic dataset, materializing it, and inspecting its features.

```python
>>> from torch_frame.datasets import Titanic
>>> dataset = Titanic(root='/tmp/titanic')
>>> len(dataset)
891
>>> dataset.feat_cols
['Pclass', 'Sex', 'Age', 'SibSp', 'Parch', 'Fare', 'Embarked']
>>> dataset.materialize()
Titanic()
>>> dataset.df.head(5)
                Survived  Pclass                                            Name    Sex   Age   SibSp  Parch            Ticket     Fare Cabin Embarked
PassengerId
1                   0       3                            Braund, Mr. Owen Harris    male  22.0      1      0         A/5 21171   7.2500   NaN        S
2                   1       1  Cumings, Mrs. John Bradley (Florence Briggs Th...  female  38.0      1      0          PC 17599  71.2833   C85        C
3                   1       3                             Heikkinen, Miss. Laina  female  26.0      0      0  STON/O2. 3101282   7.9250   NaN        S
4                   1       1       Futrelle, Mrs. Jacques Heath (Lily May Peel)  female  35.0      1      0            113803  53.1000  C123        S
5                   0       3                           Allen, Mr. William Henry    male  35.0      0      0            373450   8.0500   NaN        S
```

--------------------------------

### Instantiate ExampleTransformer Model

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/introduction.rst.txt

Instantiates the ExampleTransformer model with specified channels, output channels, number of layers, and attention heads. Requires dataset's number of classes for out_channels.

```python
import torch
import torch.nn.functional as F

device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = ExampleTransformer(
    channels=32,
    out_channels=dataset.num_classes,
    num_layers=2,

```

--------------------------------

### Initialize Dataset with Text Tokenizer Configuration

Source: https://pytorch-frame.readthedocs.io/en/latest/handling_advanced_stypes/handle_text.html

Pass the text tokenizer configuration to the dataset constructor to enable text tokenization.

```python
>>> import torch_frame
>>> from torch_frame.datasets import MultimodalTextBenchmark
>>> dataset = MultimodalTextBenchmark(
...     root='/tmp/multimodal_text_benchmark/wine_reviews',
...     name='wine_reviews',
...     text_stype=torch_frame.text_tokenized,
...     col_to_text_tokenizer_cfg=col_to_text_tokenizer_cfg,
... )
>>> dataset.col_to_stype['description']
<stype.text_tokenized: 'text_tokenized'>
```

--------------------------------

### Initialize Dataset with Text Tokenizer Configuration

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Initialize a PyTorch Frame dataset, such as MultimodalTextBenchmark, by providing the text_stype and the column-to-text-tokenizer configuration.

```python
import torch_frame
from torch_frame.datasets import MultimodalTextBenchmark
dataset = MultimodalTextBenchmark(
    root='/tmp/multimodal_text_benchmark/wine_reviews',
    name='wine_reviews',
    text_stype=torch_frame.text_tokenized,
    col_to_text_tokenizer_cfg=col_to_text_tokenizer_cfg,
)
```

--------------------------------

### CatBoost Implementation

Source: https://pytorch-frame.readthedocs.io/en/latest/modules/gbdt.html

A CatBoost model implementation within PyTorch Frame, supporting hyper-parameter tuning with Optuna.

```APIDOC
## CatBoost

### Description
A CatBoost model implementation with hyper-parameter tuning using Optuna.

### Method
N/A (Implementation Detail)

### Endpoint
N/A (Implementation Detail)

### Parameters
N/A (Implementation Detail)

### Request Example
N/A (Implementation Detail)

### Response
N/A (Implementation Detail)
```

--------------------------------

### GET /num_datasets_available

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.DataFrameBenchmark.html

Returns the count of available datasets for a specific task type and scale.

```APIDOC
## GET /num_datasets_available

### Description
Returns the total number of datasets available for a given task type and scale.

### Parameters
#### Query Parameters
- **task_type** (TaskType) - Required - The type of task.
- **scale** (str) - Required - The scale of the dataset.

### Response
#### Success Response (200)
- **int** - The count of available datasets.
```

--------------------------------

### GET /datasets_available

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.DataFrameTextBenchmark.html

Retrieves a list of datasets available for a specific task type and scale.

```APIDOC
## GET /datasets_available

### Description
Returns a list of available datasets for a given task type and scale.

### Parameters
#### Query Parameters
- **task_type** (TaskType) - Required - The task type.
- **scale** (str) - Required - The scale of the dataset.

### Response
#### Success Response (200)
- **list[tuple[str, dict[str, Any]]]** - A list of available datasets.
```

--------------------------------

### LightGBM Class Initialization

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.gbdt.LightGBM.html

Initializes the LightGBM model with support for task-specific configuration and hyper-parameter tuning.

```APIDOC
## LightGBM Class

### Description
LightGBM implementation with hyper-parameter tuning using Optuna. This implementation extends GBDT and aims to find optimal hyperparameters by optimizing the given objective function.

### Parameters
- **task_type** (TaskType) - Required - The type of task (e.g., regression or classification).
- **num_classes** (Optional[int]) - Optional - Number of classes for classification tasks.
- **metric** (Optional[Metric]) - Optional - Metric used for evaluation.
```

--------------------------------

### Initialize and Call SelfAttentionConv in Python

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/modular_design.rst.txt

Demonstrates the straightforward initialization and usage of the custom SelfAttentionConv layer with a specified channel size.

```python
conv = SelfAttentionConv(32)
x = conv(x)
```

--------------------------------

### List Available Datasets

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.DataFrameBenchmark.html

Use this class method to get a list of datasets available for a specific task type and scale. It returns a tuple containing the dataset name and its associated dictionary.

```python
TabularBenchmark.datasets_available('regression', 'small')
```

--------------------------------

### Create a Custom Dataset

Source: https://pytorch-frame.readthedocs.io/en/latest/get_started/introduction.html

Shows how to initialize a torch_frame.data.Dataset object from a pandas DataFrame by mapping columns to semantic types.

```python
import torch_frame
from torch_frame.data import Dataset

# Specify the stype of each column with a dictionary.
col_to_stype = {
    "cat1": torch_frame.categorical,
    "cat2": torch_frame.categorical,
    "num1": torch_frame.numerical,
    "num2": torch_frame.numerical,
    "y": torch_frame.categorical,
}

# Set "y" as the target column.
dataset = Dataset(df, col_to_stype=col_to_stype, target_col="y")
```

--------------------------------

### Materialize Dataset and Access TensorFrame

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/introduction.rst.txt

Demonstrates how to materialize a dataset with optional caching and access the resulting feature dictionaries and tensors.

```python
>>> from torch_frame import stype
>>> # materialize the dataset
>>> dataset.materialize()
>>> # materialize the dataset with caching enabled
>>> dataset.materialize(path='/tmp/titanic/data.pt')
>>> # next materialization will load the cache
>>> dataset.materialize(path='/tmp/titanic/data.pt')
>>> tensor_frame = dataset.tensor_frame
>>> tensor_frame.feat_dict.keys()
dict_keys([<stype.categorical: 'categorical'>, <stype.numerical: 'numerical'>])
>>> tensor_frame.feat_dict[stype.numerical]
tensor([[22.0000,  1.0000,  0.0000,  7.2500],
        [38.0000,  1.0000,  0.0000, 71.2833],
        [26.0000,  0.0000,  0.0000,  7.9250],
        ...,
        [    nan,  1.0000,  2.0000, 23.4500],
        [26.0000,  0.0000,  0.0000, 30.0000],
        [32.0000,  0.0000,  0.0000,  7.7500]])
>>> tensor_frame.feat_dict[stype.categorical]
tensor([[0, 0, 0],
        [1, 1, 1],
        [0, 1, 0],
        ...,
        [0, 1, 0],
        [1, 0, 1],
        [0, 0, 2]])
>>> tensor_frame.col_names_dict
{<stype.categorical: 'categorical'>: ['Pclass', 'Sex', 'Embarked'], <stype.numerical: 'numerical'>: ['Age', 'SibSp', 'Parch', 'Fare']}
>>> tensor_frame.y
tensor([0, 1, 1,  ..., 0, 1, 0])
```

--------------------------------

### LightGBM Implementation

Source: https://pytorch-frame.readthedocs.io/en/latest/modules/gbdt.html

A LightGBM model implementation within PyTorch Frame, designed for hyper-parameter tuning using Optuna.

```APIDOC
## LightGBM

### Description
LightGBM implementation with hyper-parameter tuning using Optuna.

### Method
N/A (Implementation Detail)

### Endpoint
N/A (Implementation Detail)

### Parameters
N/A (Implementation Detail)

### Request Example
N/A (Implementation Detail)

### Response
N/A (Implementation Detail)
```

--------------------------------

### Train ExampleTransformer Model

Source: https://pytorch-frame.readthedocs.io/en/latest/get_started/introduction.html

Trains the ExampleTransformer model for 50 epochs using Adam optimizer and cross-entropy loss. Moves the model and data to the appropriate device (GPU or CPU).

```python
import torch
import torch.nn.functional as F

device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = ExampleTransformer(
    channels=32,
    out_channels=dataset.num_classes,
    num_layers=2,
    num_heads=8,
    col_stats=train_dataset.col_stats,
    col_names_dict=train_dataset.tensor_frame.col_names_dict,
).to(device)

optimizer = torch.optim.Adam(model.parameters())

for epoch in range(50):
    for tf in train_loader:
        tf = tf.to(device)
        pred = model(tf)
        loss = F.cross_entropy(pred, tf.y)
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
```

--------------------------------

### Class: TabularBenchmark

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.TabularBenchmark.html

Initializes the TabularBenchmark dataset collection.

```APIDOC
## Class: TabularBenchmark

### Description
A collection of Tabular benchmark datasets introduced in “Why do tree-based models still outperform deep learning on tabular data?”.

### Parameters
#### Constructor Parameters
- **root** (str) - Required - The root directory where the dataset should be stored.
- **name** (str) - Required - The name of the specific benchmark dataset to load.
```

--------------------------------

### Initialize and manipulate a TensorFrame

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.TensorFrame.html

Demonstrates creating a TensorFrame with numerical and categorical features, performing row-wise filtering, and moving the object to a GPU.

```python
import torch_frame

tf = torch_frame.TensorFrame(
    feat_dict = {
        # Two numerical columns:
        torch_frame.numerical: torch.randn(10, 2),
        # Three categorical columns:
        torch_frame.categorical: torch.randint(0, 5, (10, 3)),
    },
    col_names_dict = {
        torch_frame.numerical: ['num_1', 'num_2'],
        torch_frame.categorical: ['cat_1', 'cat_2', 'cat_3'],

    },
)

print(len(tf))
>>> 10

# Row-wise filtering:
tf = tf[torch.tensor([0, 2, 4, 6, 8])]
print(len(tf))
>>> 5

# Transfer tensor frame to the GPU:
tf = tf.to('cuda')
```

--------------------------------

### TensorFrame Class Initialization and Usage

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.TensorFrame.html

Demonstrates how to initialize a TensorFrame with numerical and categorical features, access its length, perform row-wise filtering, and transfer it to a GPU.

```APIDOC
## TensorFrame Class

### Description
A tensor frame holds a PyTorch tensor for each table column. Table columns are organized into their semantic types `stype` (e.g., categorical, numerical) and mapped to a compact tensor representation. `TensorFrame` handles missing values via `float('NaN')` for floating-point tensors, and `-1` otherwise. `col_names_dict` maps each column in `feat_dict` to their original column name. Additionally, `TensorFrame` can store any target values in `y`.

### Parameters
- **_feat_dict** (dict[torch_frame._stype.stype, torch.Tensor | torch_frame.data.multi_nested_tensor.MultiNestedTensor | torch_frame.data.multi_embedding_tensor.MultiEmbeddingTensor | dict[str, torch_frame.data.multi_nested_tensor.MultiNestedTensor]]) - Description of the feature dictionary mapping semantic types to tensors.
- **_col_names_dict** (dict[torch_frame._stype.stype, list[str]]) - Maps each column in `feat_dict` to their original column name.
- **_y** (Optional[Tensor]) - Optional target values.
- **_num_rows** (Optional[int]) - Optional number of rows.

### Request Example
```python
import torch
import torch_frame

tf = torch_frame.TensorFrame(
    feat_dict = {
        # Two numerical columns:
        torch_frame.numerical: torch.randn(10, 2),
        # Three categorical columns:
        torch_frame.categorical: torch.randint(0, 5, (10, 3)),
    },
    col_names_dict = {
        torch_frame.numerical: ['num_1', 'num_2'],
        torch_frame.categorical: ['cat_1', 'cat_2', 'cat_3'],

    },
)

print(len(tf))
>>> 10

# Row-wise filtering:
tf = tf[torch.tensor([0, 2, 4, 6, 8])]
print(len(tf))
>>> 5

# Transfer tensor frame to the GPU:
tf = tf.to('cuda')
```
```

--------------------------------

### Initialize Dataset with Text Embeddings

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Pass the text embedder configuration to the dataset object.

```python
>>> import torch_frame
>>> from torch_frame.datasets import MultimodalTextBenchmark
>>> dataset = MultimodalTextBenchmark(
...     root='/tmp/multimodal_text_benchmark/wine_reviews',
...     name='wine_reviews',
```

--------------------------------

### Initialize DataLoader with Dataset

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.DataLoader.html

Instantiate a DataLoader with a torch_frame Dataset, specifying batch size and shuffle options. Additional arguments are passed to torch.utils.data.DataLoader.

```python
import torch_frame

dataset = ...

loader = torch_frame.data.DataLoader(
    dataset,
    batch_size=512,
    shuffle=True,
)

```

--------------------------------

### Initialize Yandex Dataset and DataLoaders

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/introduction.rst.txt

Initializes the Yandex dataset, materializes it, shuffles, splits into train/test sets, and creates DataLoaders for each. Ensure the root directory is correctly specified.

```python
from torch_frame.datasets import Yandex
from torch_frame.data import DataLoader

dataset = Yandex(root='/tmp/adult', name='adult')
dataset.materialize()
dataset.shuffle()
train_dataset, test_dataset = dataset[:0.8], dataset[0.8:]
train_loader = DataLoader(train_dataset.tensor_frame, batch_size=128, shuffle=True)
test_loader = DataLoader(test_dataset.tensor_frame, batch_size=128)
```

--------------------------------

### Initialize and Use SelfAttentionConv Layer

Source: https://pytorch-frame.readthedocs.io/en/latest/get_started/modular_design.html

Demonstrates how to initialize a `SelfAttentionConv` layer with a specified number of channels and apply it to an input tensor `x`.

```python
conv = SelfAttentionConv(32)
x = conv(x)

```

--------------------------------

### DataFrameTextBenchmark Constructor

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.DataFrameTextBenchmark.html

Initializes a new collection of datasets for tabular learning with text columns.

```APIDOC
## DataFrameTextBenchmark Constructor

### Description
Initializes the DataFrameTextBenchmark collection based on task type and scale.

### Parameters
#### Path Parameters
- **root** (str) - Required - Root directory.
- **task_type** (TaskType) - Required - The task type (BINARY_CLASSIFICATION, MULTICLASS_CLASSIFICATION, or REGRESSION).
- **scale** (str) - Required - The scale of the dataset (small, medium, or large).
- **idx** (int) - Required - The index of the dataset within the category.

#### Optional Parameters
- **text_stype** (stype) - Optional - Text stype to use (default: stype.text_embedded).
- **col_to_text_embedder_cfg** (dict or TextEmbedderConfig) - Optional - Configuration for text embedders.
- **col_to_text_tokenizer_cfg** (dict or TextTokenizerConfig) - Optional - Configuration for text tokenizers.
- **split_random_state** (int) - Optional - Random state for splitting (default: 42).
```

--------------------------------

### Initialize Dataset with Text Embeddings Configuration

Source: https://pytorch-frame.readthedocs.io/en/latest/handling_advanced_stypes/handle_text.html

Configure the Dataset object to use text embedders for specified columns. Ensure the root directory and dataset name are correctly provided.

```python
import torch_frame
from torch_frame.datasets import MultimodalTextBenchmark
dataset = MultimodalTextBenchmark(
    root='/tmp/multimodal_text_benchmark/wine_reviews',
    name='wine_reviews',
    col_to_text_embedder_cfg=col_to_text_embedder_cfg,
)
```

--------------------------------

### Configure Multiple Text Tokenizers for Different Columns

Source: https://pytorch-frame.readthedocs.io/en/latest/handling_advanced_stypes/handle_text.html

Prepare a dictionary of TextTokenizerConfig objects to handle tokenization for multiple text columns, allowing different tokenizers and batch sizes for each column.

```python
# Prepare text_tokenizer0 and text_tokenizer1 for text_col0 and text_col1, respectively.
col_to_text_tokenizer_cfg = {
    "text_col0":
    TextTokenizerConfig(text_tokenizer=text_tokenizer0, batch_size=10_000),
    "text_col1":
    TextTokenizerConfig(text_tokenizer=text_tokenizer1, batch_size=20_000),
}
```

--------------------------------

### Initialize Titanic Dataset

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/introduction.rst.txt

Use this to initialize and inspect the pre-loaded Titanic dataset. It automatically downloads and processes raw files.

```python
from torch_frame.datasets import Titanic
dataset = Titanic(root='/tmp/titanic')
len(dataset)

```

```python
dataset.feat_cols

```

```python
dataset.materialize()

```

```python
dataset.df.head(5)

```

--------------------------------

### XGBoost Implementation

Source: https://pytorch-frame.readthedocs.io/en/latest/modules/gbdt.html

An XGBoost model implementation within PyTorch Frame, featuring hyper-parameter tuning capabilities using Optuna.

```APIDOC
## XGBoost

### Description
An XGBoost model implementation with hyper-parameter tuning using Optuna.

### Method
N/A (Implementation Detail)

### Endpoint
N/A (Implementation Detail)

### Parameters
N/A (Implementation Detail)

### Request Example
N/A (Implementation Detail)

### Response
N/A (Implementation Detail)
```

--------------------------------

### Class: TabTransformerConv

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.nn.conv.TabTransformerConv.html

Initializes the TabTransformer layer as described in the TabTransformer paper.

```APIDOC
## TabTransformerConv

### Description
The TabTransformer Layer introduced in the “TabTransformer: Tabular Data Modeling Using Contextual Embeddings” paper.

### Parameters
- **channels** (int) - Required - Input/output channel dimensionality
- **num_heads** (int) - Required - Number of attention heads
- **attn_dropout** (float) - Optional - attention module dropout (default: 0.0)
- **ffn_dropout** (float) - Optional - attention module dropout (default: 0.0)
```

--------------------------------

### Initialize and index MultiEmbeddingTensor

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.MultiEmbeddingTensor.html

Demonstrates creating a MultiEmbeddingTensor from a list of tensors and performing various indexing operations.

```python
>>> tensor_list = [
...    torch.tensor([[0.0, 0.1, 0.2], [0.3, 0.4, 0.5]]),  # emb col 0
...    torch.tensor([[0.6, 0.7], [0.8, 0.9]]),            # emb col 1
...    torch.tensor([[1.], [1.1]]),                       # emb col 2
... ]
>>> met = MultiEmbeddingTensor.from_tensor_list(tensor_list)
>>> met
MultiEmbeddingTensor(num_rows=2, num_cols=3, device='cpu')
>>> met.values
tensor([[0.0000, 0.1000, 0.2000, 0.6000, 0.7000, 1.0000],
        [0.3000, 0.4000, 0.5000, 0.8000, 0.9000, 1.1000]])
>>> met.offset
tensor([0, 3, 5, 6])
>>> met[0, 0]
tensor([0.0000, 0.1000, 0.2000])
>>> met[1, 1]
tensor([0.8000, 0.9000])
>>> met[0] # Row integer indexing
MultiEmbeddingTensor(num_rows=1, num_cols=3, device='cpu')
>>> met[:, 0] # Column integer indexing
MultiEmbeddingTensor(num_rows=2, num_cols=1, device='cpu')
>>> met[:, 0].values # Embedding of column 0
tensor([[0.0000, 0.1000, 0.2000],
        [0.3000, 0.4000, 0.5000]])
>>> met[:1] # Row slicing
MultiEmbeddingTensor(num_rows=1, num_cols=3, device='cpu')
>>> met[[0, 1, 0, 0]] # Row list indexing
MultiEmbeddingTensor(num_rows=4, num_cols=3, device='cpu')
```

--------------------------------

### Class: Movielens1M

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.Movielens1M.html

Initializes the MovieLens 1M dataset, which includes 6,040 users and 3,952 items with over 1 million ratings.

```APIDOC
## Class: Movielens1M

### Description
The MovieLens 1M rating dataset, assembled by GroupLens Research, consisting of movies (3,883 nodes) and users (6,040 nodes) with approximately 1 million ratings.

### Parameters
- **root** (str) - Required - The root directory where the dataset is stored.
- **col_to_text_embedder_cfg** (Optional[Union[dict[str, TextEmbedderConfig], TextEmbedderConfig]]) - Optional - Configuration for text embedding.

### Dataset Statistics
- **#Users**: 6040
- **#Items**: 3952
- **#User Field**: 5
- **#Item Field**: 3
- **#Samples**: 1000209
```

--------------------------------

### HuggingFaceDatasetDict Constructor

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.HuggingFaceDatasetDict.html

Initializes a new HuggingFaceDatasetDict instance to load a dataset from the Hugging Face Hub.

```APIDOC
## Class: HuggingFaceDatasetDict

### Description
Loads a Hugging Face `datasets.DatasetDict` dataset into a `torch_frame.data.Dataset` object with pre-defined split information.

### Parameters
- **path** (str) - Required - Path or name of the dataset on the Hugging Face Hub.
- **name** (str) - Optional - Defining the name of the dataset configuration.
- **columns** (list[str]) - Optional - List of columns to be included.
- **col_to_stype** (dict[str, stype]) - Optional - Mapping of columns to their semantic types.
- **target_col** (str) - Optional - The name of the target column.

### Usage Example
```python
from torch_frame.datasets import HuggingFaceDatasetDict

dataset = HuggingFaceDatasetDict(
    path="maharshipandya/spotify-tracks-dataset",
    columns=["artists", "album_name", "track_name", "popularity"],
    target_col="track_genre"
)
dataset.materialize()
```
```

--------------------------------

### Define Text-to-Embedding Model with LoRA Finetuning

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Create a PyTorch module that uses a pre-trained model (e.g., DistilBERT) and applies LoRA finetuning. The forward method handles MultiNestedTensor input for text data, converting it to dense tensors for the model.

```python
import torch
from torch import Tensor
from transformers import AutoModel
from torch_frame.data import MultiNestedTensor
from peft import LoraConfig, TaskType, get_peft_model

class TextToEmbeddingFinetune(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.model = AutoModel.from_pretrained('distilbert-base-uncased')
        # Set LoRA config
        peft_config = LoraConfig(
            task_type=TaskType.FEATURE_EXTRACTION,
            r=32,
            lora_alpha=32,
            inference_mode=False,
            lora_dropout=0.1,
            bias="none",
            target_modules=["ffn.lin1"],
        )
        # Update the model with LoRA config
        self.model = get_peft_model(self.model, peft_config)

    def forward(self, feat: dict[str, MultiNestedTensor]) -> Tensor:
```

--------------------------------

### Define ExampleTransformer Model

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/introduction.rst.txt

Defines a PyTorch model that uses StypeWiseFeatureEncoder, TabTransformerConv, and a Linear decoder for tabular data. Requires column statistics and name dictionaries for initialization.

```python
from typing import Any

import torch_frame
from torch_frame import TensorFrame, stype
from torch_frame.data.stats import StatType
from torch_frame.nn.conv import TabTransformerConv
from torch_frame.nn.encoder import (
    EmbeddingEncoder,
    LinearEncoder,
    StypeWiseFeatureEncoder,
)


class ExampleTransformer(torch.nn.Module):
    def __init__(
        self,
        channels: int,
        out_channels: int,
        num_layers: int,
        num_heads: int,
        col_stats: dict[str, dict[StatType, Any]],
        col_names_dict: dict[torch_frame.stype, list[str]],
    ):
        super().__init__()
        self.encoder = StypeWiseFeatureEncoder(
            out_channels=channels,
            col_stats=col_stats,
            col_names_dict=col_names_dict,
            stype_encoder_dict={
                stype.categorical: EmbeddingEncoder(),
                stype.numerical: LinearEncoder()
            },
        )
        self.tab_transformer_convs = torch.nn.ModuleList([
            TabTransformerConv(
                channels=channels,
                num_heads=num_heads,
            ) for _ in range(num_layers)
        ])
        self.decoder = torch.nn.Linear(channels, out_channels)

    def forward(self, tf: TensorFrame) -> torch.Tensor:
        x, _ = self.encoder(tf)
        for tab_transformer_conv in self.tab_transformer_convs:
            x = tab_transformer_conv(x)
        return self.decoder(x.mean(dim=1))
```

--------------------------------

### Initialize and Index MultiNestedTensor

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.MultiNestedTensor.html

Demonstrates creating a MultiNestedTensor from a list of tensors and performing various indexing and conversion operations.

```python
>>> import torch
>>> from torch_frame.data import MultiNestedTensor
>>> tensor_mat = [
...    [torch.tensor([1, 2]), torch.tensor([3])],
...    [torch.tensor([4]), torch.tensor([5, 6, 7])],
...    [torch.tensor([8, 9]), torch.tensor([10])],
... ]
>>> mnt = MultiNestedTensor.from_tensor_mat(tensor_mat)
>>> mnt
MultiNestedTensor(num_rows=3, num_cols=2, device='cpu')
>>> mnt.values
tensor([ 1,  2,  3,  4,  5,  6,  7,  8,  9, 10])
>>> mnt.offset
tensor([ 0,  2,  3,  4,  7,  9, 10])
>>> mnt[0, 0]
torch.tensor([1, 2])
>>> mnt[1, 1]
tensor([5, 6, 7])
>>> mnt[0] # Row integer indexing
MultiNestedTensor(num_rows=1, num_cols=2, device='cpu')
>>> mnt[:, 0] # Column integer indexing
MultiNestedTensor(num_rows=3, num_cols=1, device='cpu')
>>> mnt[:2] # Row integer slicing
MultiNestedTensor(num_rows=2, num_cols=2, device='cpu')
>>> mnt[[2, 1, 2, 0]] # Row list indexing
MultiNestedTensor(num_rows=4, num_cols=2, device='cpu')
>>> mnt.to_dense(fill_value=-1) # Map to a dense matrix with padding
tensor([[[ 1,  2, -1],
         [ 3, -1, -1]],
        [[ 4, -1, -1],
         [ 5,  6,  7]],
        [[ 8,  9, -1],
         [10, -1, -1]]])
```

--------------------------------

### Instantiate ModelConfig

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Creates a configuration object for a text embedding model, specifying the model instance and output channel dimensions.

```python
from torch_frame.config import ModelConfig
model_cfg = ModelConfig(model=TextToEmbeddingFinetune(), out_channels=768)
```

--------------------------------

### StypeWiseFeatureEncoder Class

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.nn.encoder.StypeWiseFeatureEncoder.html

Initializes the StypeWiseFeatureEncoder.

```APIDOC
## StypeWiseFeatureEncoder Class

### Description
Feature encoder that transforms each stype tensor into embeddings and performs the final concatenation.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Configure Text Tokenizers for Dataset Columns

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Define a mapping from column names to TextTokenizerConfig objects, specifying the tokenizer and batch size for each text column.

```python
col_to_text_tokenizer_cfg = {
    "text_col0":
    TextTokenizerConfig(text_tokenizer=text_tokenizer0, batch_size=10_000),
    "text_col1":
    TextTokenizerConfig(text_tokenizer=text_tokenizer1, batch_size=20_000),
}
```

--------------------------------

### Configure Text Embedder

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Instantiate TextEmbedderConfig to define the embedder and batch size for pre-encoding.

```python
from torch_frame.config.text_embedder import TextEmbedderConfig

device = (torch.device('cuda' if torch.cuda.is_available() else 'cpu')

col_to_text_embedder_cfg = TextEmbedderConfig(
    text_embedder=TextToEmbedding(device),
    batch_size=8,
)
```

--------------------------------

### Class: LinearBucketEncoder

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.nn.encoder.LinearBucketEncoder.html

Initializes the LinearBucketEncoder for numerical feature encoding.

```APIDOC
## Class: LinearBucketEncoder

### Description
A numerical converter that transforms a tensor into a piecewise linear representation, followed by a linear transformation.

### Parameters
- **out_channels** (Optional[int]) - Optional - Number of output channels.
- **stats_list** (Optional[list[dict[StatType, Any]]]) - Optional - List of statistics for the features.
- **stype** (Optional[stype]) - Optional - The semantic type of the features.
- **post_module** (Optional[Module]) - Optional - A module to apply after the linear transformation.
- **na_strategy** (Optional[NAStrategy]) - Optional - Strategy for handling missing values.
```

--------------------------------

### Map Columns to Model Configurations

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Defines a mapping from column names to their respective model configurations.

```python
col_to_model_cfg = {"description": model_cfg}
```

--------------------------------

### CatBoost Class

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.gbdt.CatBoost.html

The CatBoost class extends GBDT and integrates Optuna for hyperparameter tuning. It is designed to find optimal hyperparameters by optimizing a given objective function.

```APIDOC
## CatBoost Class

### Description
A CatBoost model implementation with hyper-parameter tuning using Optuna. This implementation extends GBDT and aims to find optimal hyperparameters by optimizing the given objective function.

### Class Signature
`_CatBoost(_task_type : TaskType_, _num_classes : Optional[int] = None_, _metric : Optional[Metric] = None_)`

### Parameters
- **_task_type** (TaskType) - Description of the task type.
- **_num_classes** (Optional[int]) - Optional number of classes.
- **_metric** (Optional[Metric]) - Optional metric to use.
```

--------------------------------

### Class: DiamondImages

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.DiamondImages.html

Initializes the DiamondImages dataset for multiclass classification of diamond colors.

```APIDOC
## Class: DiamondImages

### Description
The DiamondImages dataset from Kaggle. The target is to predict the 'colour' of each diamond.

### Constructor
`DiamondImages(root: str, col_to_image_embedder_cfg: torch_frame.config.image_embedder.ImageEmbedderConfig | dict[str, torch_frame.config.image_embedder.ImageEmbedderConfig])`

### Parameters
- **root** (str) - Required - The root directory where the dataset is stored.
- **col_to_image_embedder_cfg** (ImageEmbedderConfig | dict) - Required - Configuration for the image embedder.

### Dataset Statistics
- **Rows**: 48,764
- **Numerical Columns**: 4
- **Categorical Columns**: 7
- **Image Columns**: 1
- **Classes**: 23
- **Task**: multiclass_classification
- **Missing value ratio**: 0.167%
```

--------------------------------

### DataLoader Class

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.DataLoader.html

Instantiate a DataLoader to create mini-batches from a dataset.

```APIDOC
## DataLoader Class

### Description
A data loader which creates mini-batches from a `torch_frame.Dataset` or `torch_frame.TensorFrame` object.

### Parameters

#### Parameters
- **dataset** (Dataset or TensorFrame) - The dataset or tensor frame from which to load the data.
- ***args** (optional) - Additional arguments of `torch.utils.data.DataLoader`.
- ****kwargs** (optional) - Additional keyword arguments of `torch.utils.data.DataLoader`.

### Request Example
```python
import torch_frame

dataset = ...

loader = torch_frame.data.DataLoader(
    dataset,
    batch_size=512,
    shuffle=True,
)
```
```

--------------------------------

### Display DataFrame Head

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_heterogeneous_stypes.rst.txt

Shows the first few rows of the created pandas DataFrame to verify its structure and content.

```python
>>> df.head()
   Numerical Categorical       Time                                  Multicategorical                                          Embedding
0         44      Type 2 2023-01-01              [Category D, Category A, Category B]  [0.2879910043632805, 0.38346222503494787, 0.74...
1         47      Type 2 2023-01-02  [Category C, Category A, Category B, Category D]  [0.0923738894608982, 0.3540466620838102, 0.551...
2         64      Type 2 2023-01-03                          [Category D, Category C]  [0.3209972413734975, 0.22126268518378278, 0.14...
3         67      Type 1 2023-01-04                          [Category C, Category A]  [0.2603409275874047, 0.5370225213757797, 0.447...
4         67      Type 2 2023-01-05                                      [Category A]  [0.46924917399024213, 0.8411401297855995, 0.90...
```

--------------------------------

### Implement MeanDecoder in Python

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/get_started/modular_design.rst.txt

Create a custom Decoder by inheriting from Decoder, implementing mean pooling over column embeddings followed by a linear transformation. Requires torch.

```python
import torch
from torch_frame.nn import Decoder

class MeanDecoder(Decoder):
    def __init__(self, in_channels: int, out_channels: int):
        super().__init__()
        self.lin = torch.nn.Linear(in_channels, out_channels)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        # Mean pooling over the column dimension
        # [batch_size, num_cols, in_channels] -> [batch_size, in_channels]
        out = torch.mean(x, dim=1)
        # [batch_size, out_channels]
        return self.lin(out)
```

--------------------------------

### Evaluate ExampleTransformer Model

Source: https://pytorch-frame.readthedocs.io/en/latest/get_started/introduction.html

Evaluates the trained ExampleTransformer model on the test set. Calculates and prints the accuracy.

```python
model.eval()
correct = 0
for tf in test_loader:
    tf = tf.to(device)
    pred = model(tf)
    pred_class = pred.argmax(dim=-1)
    correct += (tf.y == pred_class).sum()
acc = int(correct) / len(test_dataset)
print(f'Accuracy: {acc:.4f}')
```

--------------------------------

### Create Sample DataFrame with Heterogeneous Data

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_heterogeneous_stypes.rst.txt

Generates a pandas DataFrame with various data types including numerical, categorical, timestamp, multicategorical, and embedding columns. Ensure all necessary libraries (numpy, pandas, random) are imported.

```python
import random

import numpy as np
import pandas as pd

# Numerical column
numerical = np.random.randint(0, 100, size=10)

# Categorical column
simple_categories = ['Type 1', 'Type 2', 'Type 3']
categorical = np.random.choice(simple_categories, size=100)

# Timestamp column
time = pd.date_range(start='2023-01-01', periods=100, freq='D')

# Multicategorical column
categories = ['Category A', 'Category B', 'Category C', 'Category D']
multicategorical = [
    random.sample(categories, k=random.randint(0, len(categories)))
    for _ in range(100)
]

# Embedding column (assuming an embedding size of 5 for simplicity)
embedding_size = 5
embedding = np.random.rand(100, embedding_size)

# Create the DataFrame
df = pd.DataFrame({
    'Numerical': numerical,
    'Categorical': categorical,
    'Time': time,
    'Multicategorical': multicategorical,
    'Embedding': list(embedding)
})
```

--------------------------------

### BankMarketing Dataset Class

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.datasets.BankMarketing.html

Initializes the BankMarketing dataset for binary classification of term deposit subscriptions.

```APIDOC
## BankMarketing Dataset

### Description
The BankMarketing class represents the dataset related to direct marketing campaigns of a Portuguese banking institution. The goal is to predict if a client will subscribe to a bank term deposit.

### Class Constructor
`torch_frame.datasets.BankMarketing(root: str)`

### Parameters
- **root** (str) - Required - The root directory where the dataset is stored.

### Dataset Statistics
- **Rows**: 45,211
- **Numerical Columns**: 7
- **Categorical Columns**: 9
- **Classes**: 2
- **Task**: binary_classification
- **Missing Value Ratio**: 0.0%
```

--------------------------------

### Dataset Class Initialization

Source: https://pytorch-frame.readthedocs.io/en/latest/generated/torch_frame.data.Dataset.html

Initializes a Dataset object, which is a base class for creating tabular datasets. It takes a DataFrame and mappings for semantic types, target columns, split columns, and various configuration options for text and image embedding, as well as time formats.

```APIDOC
## _class _Dataset(_df : DataFrame_, _col_to_stype : dict[str, torch_frame._stype.stype]_, _target_col : Optional[str] = None_, _split_col : Optional[str] = None_, _col_to_sep : Union[str, None, dict[str, str | None]] = None_, _col_to_text_embedder_cfg : Optional[Union[dict[str, torch_frame.config.text_embedder.TextEmbedderConfig], TextEmbedderConfig]] = None_, _col_to_text_tokenizer_cfg : Optional[Union[dict[str, torch_frame.config.text_tokenizer.TextTokenizerConfig], TextTokenizerConfig]] = None_, _col_to_image_embedder_cfg : Optional[Union[dict[str, torch_frame.config.image_embedder.ImageEmbedderConfig], ImageEmbedderConfig]] = None_, _col_to_time_format : Union[str, None, dict[str, str | None]] = None_)

### Description
A base class for creating tabular datasets.

### Parameters
- **df** (DataFrame) - The tabular data frame.
- **col_to_stype** (Dict[str, torch_frame.stype]) - A dictionary that maps each column in the data frame to a semantic type.
- **target_col** (str, optional) - The column used as target. (default: None)
- **split_col** (str, optional) - The column that stores the pre-defined split information. The column should only contain `0`, `1`, or `2`. (default: None).
- **col_to_sep** (Union[str, Dict[str, Optional[str]]]) - A dictionary or a string/`None` specifying the separator/delimiter for the multi-categorical columns. If a string/`None` is specified, then the same separator will be used throughout all the multi-categorical columns. Note that if `None` is specified, it assumes a multi-category is given as a `list` of categories. If a dictionary is given, we use a separator specified for each column. (default: None)
- **col_to_text_embedder_cfg** (TextEmbedderConfig or dict, optional) - A text embedder configuration or a dictionary of configurations specifying `text_embedder` that embeds texts into vectors and `batch_size` that specifies the mini-batch size for `text_embedder`. (default: None)
- **col_to_text_tokenizer_cfg** (TextTokenizerConfig or dict, optional) - A text tokenizer configuration or dictionary of configurations specifying `text_tokenizer` that maps sentences into a list of dictionary of tensors. Each element in the list corresponds to each sentence, keys are input arguments to the model such as `input_ids`, and values are tensors such as tokens. `batch_size` specifies the mini-batch size for `text_tokenizer`. (default: None)
- **col_to_image_embedder_cfg** (Union[dict[str, torch_frame.config.image_embedder.ImageEmbedderConfig], ImageEmbedderConfig], optional) - Configuration for image embedders.
- **col_to_time_format** (Union[str, Dict[str, Optional[str]]], optional) - A dictionary or a string specifying the format for the timestamp columns. See strfttime documentation for more information on formats. If a string is specified, then the same format will be used throughout all the timestamp columns. If a dictionary is given, we use a different format specified for each column. If not specified, pandas’s internal to_datetime function will be used to auto parse time columns. (default: None)
```

--------------------------------

### Configure Multiple Text Embedders

Source: https://pytorch-frame.readthedocs.io/en/latest/_sources/handling_advanced_stypes/handle_text.rst.txt

Use a dictionary to assign different embedder configurations to specific text columns.

```python
# Prepare text_embedder0 and text_embedder1 for text_col0 and text_col1, respectively.
col_to_text_embedder_cfg = {
    "text_col0":
    TextEmbedderConfig(text_embedder=text_embedder0, batch_size=4),
    "text_col1":
    TextEmbedderConfig(text_embedder=text_embedder1, batch_size=8),
}
```
Tokens:
Raw