Quickstart

In this quickstart you load a public dataset, predict its labels with Kumo Tabular, and check the accuracy.

Before You Begin

• Python 3.11 or later
• About 1 GB of disk space for PyTorch and model weights
• Network access for the first run
• No GPU and no Hugging Face account are required

1. Install SDM

pip install structured-data-models scikit-learn

scikit-learn provides the example dataset. For GPU setup and other options, see Installation.

2. Run a Classification

import torch
from sklearn.datasets import load_breast_cancer
import sdm
from sdm.evaluation import to_class_indices
device = "cuda" if torch.cuda.is_available() else "cpu"
# 1. Load a table and declare column semantic types
df = load_breast_cancer(as_frame=True).frame
table = sdm.TableTensor.from_pandas(
    df=df,
    stypes=sdm.infer_stypes(df, overrides={"target": "categorical"}),
    device=device,
)
context, query = table[:300], table[300:]
# 2. Load pretrained Kumo Tabular (weights download on first use)
model = sdm.models.KumoTabular(task="classification", size="small", device=device)
# 3. Predict query rows from labeled context rows, with no training
probs = model(
    x_context=context.drop_columns("target"),
    y_context=context["target"],
    x_query=query.drop_columns("target"),
    num_estimators=8,
    generator=torch.Generator(device=device).manual_seed(0),
)
print(probs.to_pandas().head(3))
# 4. Score the predictions
scores, labels = to_class_indices(probs, query["target"])
accuracy = (scores.argmax(dim=-1) == labels).float().mean()
print(f"Accuracy: {accuracy:.3f}")

1. TableTensor.from_pandas converts the data frame. infer_stypes assigns a semantic type to each column; the override marks target as categorical, which makes this a classification task.
2. KumoTabular downloads pretrained weights. size="small" keeps the download and CPU time small; the default is "large".
3. The forward pass reads 300 labeled context rows and predicts the 269 query rows. num_estimators=8 averages eight randomized views of the table. The seeded generator makes the result reproducible.
4. to_class_indices aligns probability columns with the true labels by class name.

3. Check the Output

          0         1
0  0.999958  0.000042
1  0.000192  0.999808
2  0.999905  0.000095
Accuracy: 0.974

The result is a TableTensor with one probability column per class, named by class value. Select classes by name, for example probs["1"], not by position: without a seeded generator, column order and probabilities can change between runs.

Try a Regression Task

When the target is numerical, Kumo Tabular performs regression and returns 999 quantiles named q001 to q999.

from sklearn.datasets import load_diabetes
df = load_diabetes(as_frame=True).frame
table = sdm.TableTensor.from_pandas(df, stypes=sdm.infer_stypes(df), device=device)
context, query = table[:300], table[300:]
model = sdm.models.KumoTabular(task="regression", size="small", device=device)
quantiles = model(
    x_context=context.drop_columns("target"),
    y_context=context["target"],
    x_query=query.drop_columns("target"),
    generator=torch.Generator(device=device).manual_seed(0),
)
median = quantiles["q500"].numerical.squeeze(-1)  # 999 columns: q001 to q999
mae = (median - query["target"].numerical.squeeze(-1)).abs().mean()
print(quantiles.size(), f"MAE: {mae:.2f}")

torch.Size([142, 999]) MAE: 41.23

Reuse Context for Many Queries

If you score many batches against the same labeled rows, call fit once and predict per batch. SDM caches the context side of the model, so each batch only computes the query side. This example continues from the classification script:

model.fit(
    x=context.drop_columns("target"),
    y=context["target"],
    num_estimators=8,
)
for batch in query.drop_columns("target").split(64):
    probs = model.predict(batch)
model.clear()  # release cached context state

The 269 query rows run in batches of 64, so the last batch of probabilities has shape torch.Size([13, 2]).

Run on a GPU

The quickstart script selects a CUDA device when PyTorch can see one, and creates its random generator on the same device. First set up a CUDA-enabled PyTorch build as described in Set Up a GPU. On a GPU, you can drop size="small" to use the default large model. The random generator draws a different sequence on a GPU, so probabilities can differ slightly from the CPU output shown above.

Download the Example Notebook

Classify breast masses from four clinical features using the UCI Mammographic Mass dataset on Kumo Tabular (small).

The notebook installs its dependencies, downloads the dataset and pretrained weights, and runs without a GPU.

To run the example in Snowflake, download the Snowflake notebook. First configure Snowflake external access so the notebook can download model weights:

For import, download, device, and input errors, refer to Troubleshooting.