Mixed tabular inputs

A TABULAR branch keeps continuous measurements and categorical values as different inputs. Continuous columns are normalized with statistics fitted on training entities. Each categorical column is converted to integer indices and passed through its own learned embedding table.

Input format

Pass entity features as a pandas DataFrame with one unique id column and the columns declared by the branch schema:

import numpy as np
import pandas as pd

instance_features = pd.DataFrame(
    {
        "id": np.arange(6),
        "age": [22.0, 35.0, None, 51.0, 47.0, 29.0],
        "dose": [1.2, 0.8, 1.5, 1.1, 0.7, 1.0],
        "site": ["Ghent", "Paris", "Ghent", "London", "Paris", None],
    }
)

The schema fixes column order and categorical vocabularies before model construction:

tabular_schema = {
    "numeric_columns": ["age", "dose"],
    "categorical_columns": {
        "site": {
            "categories": ["Ghent", "Paris", "London"],
            "embedding_dim": 3,
        }
    },
    "numeric_normalization": "standard",
    "numeric_missing": "mean",
    "categorical_missing": "unknown",
    "categorical_unknown": "unknown",
    "feature_gating": True,
}

Category index zero is reserved for missing or unknown values when the corresponding policy is "unknown". Set either policy to "error" when such values should stop data loading instead.

Configuration

Select TABULAR independently for either branch. It can be paired with an MLP, EMBEDDING, CONV, CUSTOM, or another TABULAR branch:

from DeepMTP import DeepMTPConfig

config = DeepMTPConfig(
    validation_setting="B",
    problem_mode="classification",
    general_architecture_version="dot_product",
    compute_mode="cpu",
    metrics=["accuracy"],
    metrics_average=["macro"],
    instance_branch_architecture="TABULAR",
    instance_branch_tabular_schema=tabular_schema,
    instance_branch_nodes_per_layer=[16],
    target_branch_architecture="EMBEDDING",
    target_branch_input_dim=number_of_targets,
    embedding_size=8,
)

For a dot-product model, both branch encoders output embedding_size features. For MLP and Kronecker fusion, the last branch width comes from instance_branch_nodes_per_layer or target_branch_nodes_per_layer.

Preprocessing and checkpoints

DataLoaderFactory.for_training fits imputation and normalization only on the training entity frame. The same state is reused for validation and test data. DeepMTP records this state in instance_tabular_preprocessing_state or target_tabular_preprocessing_state and includes it in saved configurations and checkpoints.

Restored models therefore apply the original training statistics during prediction. Calling prediction on a new, untrained TABULAR model is rejected because fitting preprocessing on prediction data would leak information.

Numeric options are:

numeric_normalization

"standard" for zero mean and unit population standard deviation, "minmax" for training-range scaling, or "none".

numeric_missing

"mean" for training-mean imputation, "zero" for raw zero imputation, or "error".

Constant numeric columns use a scale of one, avoiding division by zero.

Precomputed embeddings

Vectors produced by another model do not need a separate branch type. Pass them as the existing features vectors and use an MLP branch. This keeps precomputed embeddings on the efficient dense path while TABULAR is reserved for schema-shaped numeric and categorical columns.