structured-data-models 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sdm/__init__.py +58 -0
- sdm/_constants.py +6 -0
- sdm/_inference.py +42 -0
- sdm/_kernels/__init__.py +10 -0
- sdm/_kernels/rmsnorm_cast.py +92 -0
- sdm/_kernels/segment_multi_reduce.py +141 -0
- sdm/_kernels/triton/__init__.py +7 -0
- sdm/_kernels/triton/rmsnorm_cast.py +136 -0
- sdm/_kernels/triton/segment_multi_reduce.py +173 -0
- sdm/_memory.py +34 -0
- sdm/_warnings.py +29 -0
- sdm/cache.py +163 -0
- sdm/ensemble.py +501 -0
- sdm/evaluation/__init__.py +11 -0
- sdm/evaluation/classification.py +205 -0
- sdm/explain/__init__.py +12 -0
- sdm/explain/base.py +123 -0
- sdm/explain/gradient.py +112 -0
- sdm/models/__init__.py +20 -0
- sdm/models/_huggingface.py +58 -0
- sdm/models/base.py +966 -0
- sdm/models/callback.py +106 -0
- sdm/models/ecoc.py +197 -0
- sdm/models/kumo/__init__.py +13 -0
- sdm/models/kumo/relational/NOTICE +5 -0
- sdm/models/kumo/relational/__init__.py +11 -0
- sdm/models/kumo/relational/graph.py +101 -0
- sdm/models/kumo/relational/invariant_gnn.py +122 -0
- sdm/models/kumo/relational/model.py +602 -0
- sdm/models/kumo/relational/recipe.py +18 -0
- sdm/models/kumo/relational/task.py +113 -0
- sdm/models/kumo/tabular/__init__.py +17 -0
- sdm/models/kumo/tabular/batching.py +139 -0
- sdm/models/kumo/tabular/block.py +100 -0
- sdm/models/kumo/tabular/cell_embedding.py +85 -0
- sdm/models/kumo/tabular/icl.py +136 -0
- sdm/models/kumo/tabular/model.py +299 -0
- sdm/models/kumo/tabular/recipe.py +71 -0
- sdm/models/kumo/tabular/row_embedding.py +214 -0
- sdm/models/tabfm/LICENSE +209 -0
- sdm/models/tabfm/__init__.py +11 -0
- sdm/models/tabfm/block.py +94 -0
- sdm/models/tabfm/cell_embedding.py +219 -0
- sdm/models/tabfm/ckpt.py +242 -0
- sdm/models/tabfm/icl.py +107 -0
- sdm/models/tabfm/model.py +261 -0
- sdm/models/tabfm/recipe.py +46 -0
- sdm/models/tabfm/row_embedding.py +241 -0
- sdm/models/tabiclv2/LICENSE +33 -0
- sdm/models/tabiclv2/__init__.py +11 -0
- sdm/models/tabiclv2/block.py +81 -0
- sdm/models/tabiclv2/ckpt.py +134 -0
- sdm/models/tabiclv2/icl.py +420 -0
- sdm/models/tabiclv2/model.py +293 -0
- sdm/models/tabiclv2/recipe.py +46 -0
- sdm/models/tabiclv2/row_embedding.py +254 -0
- sdm/nn/__init__.py +28 -0
- sdm/nn/_buffer.py +91 -0
- sdm/nn/attention.py +825 -0
- sdm/nn/glu.py +78 -0
- sdm/nn/linear.py +46 -0
- sdm/nn/rms_norm.py +59 -0
- sdm/nn/rope.py +107 -0
- sdm/nn/scaling.py +240 -0
- sdm/nn/set_transformer.py +162 -0
- sdm/nn/softplus.py +65 -0
- sdm/processing/__init__.py +96 -0
- sdm/processing/base.py +254 -0
- sdm/processing/categorical/__init__.py +16 -0
- sdm/processing/categorical/_categorical.py +60 -0
- sdm/processing/categorical/align.py +540 -0
- sdm/processing/categorical/count.py +121 -0
- sdm/processing/categorical/impute.py +107 -0
- sdm/processing/categorical/shuffle.py +204 -0
- sdm/processing/common/__init__.py +32 -0
- sdm/processing/common/callable.py +29 -0
- sdm/processing/common/choice.py +185 -0
- sdm/processing/common/drop.py +28 -0
- sdm/processing/common/ensemble.py +187 -0
- sdm/processing/common/identity.py +18 -0
- sdm/processing/common/select.py +107 -0
- sdm/processing/common/sequential.py +158 -0
- sdm/processing/common/shuffle.py +195 -0
- sdm/processing/common/stype.py +199 -0
- sdm/processing/common/table.py +120 -0
- sdm/processing/common/task.py +135 -0
- sdm/processing/common/to_numerical.py +60 -0
- sdm/processing/datetime/__init__.py +8 -0
- sdm/processing/datetime/calendar.py +196 -0
- sdm/processing/ensemble.py +203 -0
- sdm/processing/execution.py +418 -0
- sdm/processing/numerical/__init__.py +38 -0
- sdm/processing/numerical/_stats.py +29 -0
- sdm/processing/numerical/cast.py +33 -0
- sdm/processing/numerical/clip.py +48 -0
- sdm/processing/numerical/clip_soft.py +54 -0
- sdm/processing/numerical/constant.py +235 -0
- sdm/processing/numerical/flip_sign.py +78 -0
- sdm/processing/numerical/impute.py +52 -0
- sdm/processing/numerical/pca.py +62 -0
- sdm/processing/numerical/power.py +325 -0
- sdm/processing/numerical/quantile.py +306 -0
- sdm/processing/numerical/quantile_clip.py +63 -0
- sdm/processing/numerical/random_projection.py +86 -0
- sdm/processing/numerical/rank_gaussian.py +168 -0
- sdm/processing/numerical/robust_scale.py +88 -0
- sdm/processing/numerical/sigma_clip.py +123 -0
- sdm/processing/numerical/standardize.py +71 -0
- sdm/processing/output/__init__.py +14 -0
- sdm/processing/output/reduce.py +86 -0
- sdm/processing/output/softmax.py +48 -0
- sdm/processing/output/sort.py +16 -0
- sdm/processing/recipe.py +154 -0
- sdm/processing/text/__init__.py +12 -0
- sdm/processing/text/sentence_transformer.py +451 -0
- sdm/processing/text/tfidf.py +478 -0
- sdm/relational/__init__.py +16 -0
- sdm/relational/backend/__init__.py +12 -0
- sdm/relational/backend/_cugraph.py +546 -0
- sdm/relational/backend/_pyg_lib.py +175 -0
- sdm/relational/data.py +393 -0
- sdm/relational/join.py +173 -0
- sdm/relational/sampler.py +259 -0
- sdm/relational/task.py +465 -0
- sdm/stype.py +396 -0
- sdm/task.py +53 -0
- sdm/tensor/__init__.py +20 -0
- sdm/tensor/categorical.py +953 -0
- sdm/tensor/columnar.py +1127 -0
- sdm/tensor/io/__init__.py +22 -0
- sdm/tensor/io/arrow.py +120 -0
- sdm/tensor/io/cudf.py +47 -0
- sdm/tensor/mixin.py +124 -0
- sdm/tensor/nullable.py +963 -0
- sdm/tensor/string.py +526 -0
- sdm/tensor/table.py +2035 -0
- sdm/tensor/var_len.py +1486 -0
- sdm/testing/__init__.py +14 -0
- sdm/testing/decorators.py +61 -0
- sdm/testing/memory.py +92 -0
- structured_data_models-0.2.0.dist-info/METADATA +142 -0
- structured_data_models-0.2.0.dist-info/RECORD +152 -0
- structured_data_models-0.2.0.dist-info/WHEEL +5 -0
- structured_data_models-0.2.0.dist-info/licenses/LICENSE +204 -0
- structured_data_models-0.2.0.dist-info/licenses/THIRD_PARTY_LICENSES.md +40 -0
- structured_data_models-0.2.0.dist-info/licenses/sdm/models/kumo/relational/NOTICE +5 -0
- structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabfm/LICENSE +209 -0
- structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabiclv2/LICENSE +33 -0
- structured_data_models-0.2.0.dist-info/licenses/third_party/contributor-covenant/LICENSE +20 -0
- structured_data_models-0.2.0.dist-info/licenses/third_party/pytorch/LICENSE +84 -0
- structured_data_models-0.2.0.dist-info/licenses/third_party/tabpfn-extensions/LICENSE +202 -0
- structured_data_models-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
from typing import cast
|
|
5
|
+
|
|
6
|
+
import torch
|
|
7
|
+
from torch import Tensor
|
|
8
|
+
|
|
9
|
+
from sdm import CategoricalTensor, StringTensor, Stype, TableTensor
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def to_class_indices(
|
|
13
|
+
pred: TableTensor,
|
|
14
|
+
target: TableTensor | CategoricalTensor,
|
|
15
|
+
*,
|
|
16
|
+
missing_score: float | None = None,
|
|
17
|
+
) -> tuple[Tensor, Tensor]:
|
|
18
|
+
r"""Convert classification predictions and targets to class-index form.
|
|
19
|
+
|
|
20
|
+
Args:
|
|
21
|
+
pred: Prediction table whose numerical columns contain class scores.
|
|
22
|
+
Column names define the class order.
|
|
23
|
+
target: Single-column categorical target.
|
|
24
|
+
missing_score: Score assigned to target classes that are absent from
|
|
25
|
+
the prediction columns. If ``None``, will raise an error when a
|
|
26
|
+
``target`` value refers to an absent class in ``pred``.
|
|
27
|
+
|
|
28
|
+
>>> import torch
|
|
29
|
+
>>> import sdm
|
|
30
|
+
>>> from sdm.evaluation import to_class_indices
|
|
31
|
+
>>> pred = sdm.TableTensor.from_tensor(
|
|
32
|
+
... torch.tensor([[0.8, 0.1, 0.1], [0.1, 0.2, 0.7]]),
|
|
33
|
+
... columns=["cat", "dog", "bird"],
|
|
34
|
+
... )
|
|
35
|
+
>>> target = sdm.CategoricalTensor(
|
|
36
|
+
... code=torch.tensor([[0], [2]]),
|
|
37
|
+
... categories=(sdm.StringTensor.from_list(["cat", "dog", "bird"]),),
|
|
38
|
+
... )
|
|
39
|
+
>>> class_scores, class_indices = to_class_indices(pred, target)
|
|
40
|
+
>>> class_scores
|
|
41
|
+
tensor([[0.8000, 0.1000, 0.1000],
|
|
42
|
+
[0.1000, 0.2000, 0.7000]])
|
|
43
|
+
>>> class_indices
|
|
44
|
+
tensor([0, 2])
|
|
45
|
+
>>> pred = sdm.TableTensor.from_tensor(
|
|
46
|
+
... torch.tensor([[0.1, 0.8, 0.1], [0.7, 0.1, 0.2]]),
|
|
47
|
+
... columns=["bird", "cat", "dog"],
|
|
48
|
+
... )
|
|
49
|
+
>>> class_scores, class_indices = to_class_indices(pred, target)
|
|
50
|
+
>>> class_scores
|
|
51
|
+
tensor([[0.8000, 0.1000, 0.1000],
|
|
52
|
+
[0.1000, 0.2000, 0.7000]])
|
|
53
|
+
>>> class_indices
|
|
54
|
+
tensor([0, 2])
|
|
55
|
+
"""
|
|
56
|
+
if isinstance(target, TableTensor):
|
|
57
|
+
if target.size(-1) != 1:
|
|
58
|
+
raise ValueError(
|
|
59
|
+
f"Expected a single categorical target column "
|
|
60
|
+
f"(got {target.size(-1)} columns)"
|
|
61
|
+
)
|
|
62
|
+
target = target.categorical
|
|
63
|
+
|
|
64
|
+
if target.size(-1) != 1:
|
|
65
|
+
raise ValueError(
|
|
66
|
+
f"Expected a single categorical target column "
|
|
67
|
+
f"(got {target.size(-1)} columns)"
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
if target.isnan().any():
|
|
71
|
+
raise ValueError("Expected target to not contain missing values")
|
|
72
|
+
|
|
73
|
+
if pred.size()[:-1] != target.size()[:-1]:
|
|
74
|
+
raise ValueError(
|
|
75
|
+
f"Expected prediction and target row dimensions to match "
|
|
76
|
+
f"(got {tuple(pred.size()[:-1])} and "
|
|
77
|
+
f"{tuple(target.size())[:-1]})"
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
columns = pred.columns[Stype.numerical]
|
|
81
|
+
pred: Tensor = pred.numerical
|
|
82
|
+
|
|
83
|
+
category = target.categories[0]
|
|
84
|
+
code = target.code.squeeze(-1).to(torch.int64)
|
|
85
|
+
|
|
86
|
+
if isinstance(category, StringTensor):
|
|
87
|
+
classes = StringTensor.from_list(
|
|
88
|
+
[_parse_column(column, category) for column in columns],
|
|
89
|
+
device=category.device,
|
|
90
|
+
)
|
|
91
|
+
else:
|
|
92
|
+
classes = torch.tensor(
|
|
93
|
+
[_parse_column(column, category) for column in columns],
|
|
94
|
+
dtype=category.dtype,
|
|
95
|
+
device=category.device,
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
match = category.unsqueeze(-1) == classes.unsqueeze(0) # [C_t, C_p]
|
|
99
|
+
if missing_score is None and not match.any(dim=-1)[code].all():
|
|
100
|
+
raise ValueError("Target contains classes missing from prediction")
|
|
101
|
+
|
|
102
|
+
matched_target, matched_pred = match.nonzero(as_tuple=True)
|
|
103
|
+
aligned = pred.new_full(
|
|
104
|
+
(*pred.size()[:-1], category.size(0)),
|
|
105
|
+
fill_value=missing_score or 0,
|
|
106
|
+
)
|
|
107
|
+
aligned[..., matched_target] = pred[..., matched_pred]
|
|
108
|
+
return aligned, code
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def to_binary_class(
|
|
112
|
+
pred: TableTensor,
|
|
113
|
+
target: TableTensor | CategoricalTensor,
|
|
114
|
+
positive_class: bool | int | float | str,
|
|
115
|
+
) -> tuple[Tensor, Tensor]:
|
|
116
|
+
r"""Convert binary predictions and targets to positive-class form.
|
|
117
|
+
|
|
118
|
+
Args:
|
|
119
|
+
pred: Prediction table whose numerical columns contain class scores.
|
|
120
|
+
Column names define the class order.
|
|
121
|
+
target: Single-column categorical target.
|
|
122
|
+
positive_class: Class value treated as the positive class.
|
|
123
|
+
|
|
124
|
+
>>> import torch
|
|
125
|
+
>>> import sdm
|
|
126
|
+
>>> from sdm.evaluation import to_binary_class
|
|
127
|
+
>>> pred = sdm.TableTensor.from_tensor(
|
|
128
|
+
... torch.tensor([[0.8, 0.2], [0.1, 0.9], [0.4, 0.6]]),
|
|
129
|
+
... columns=["false", "true"],
|
|
130
|
+
... )
|
|
131
|
+
>>> target = sdm.CategoricalTensor(
|
|
132
|
+
... code=torch.tensor([[0], [1], [1]]),
|
|
133
|
+
... categories=(sdm.StringTensor.from_list(["false", "true"]),),
|
|
134
|
+
... )
|
|
135
|
+
>>> positive_scores, binary_target = to_binary_class(
|
|
136
|
+
... pred,
|
|
137
|
+
... target,
|
|
138
|
+
... positive_class="true",
|
|
139
|
+
... )
|
|
140
|
+
>>> positive_scores
|
|
141
|
+
tensor([0.2000, 0.9000, 0.6000])
|
|
142
|
+
>>> binary_target
|
|
143
|
+
tensor([False, True, True])
|
|
144
|
+
>>> pred = sdm.TableTensor.from_tensor(
|
|
145
|
+
... torch.tensor([[0.2, 0.8], [0.9, 0.1], [0.6, 0.4]]),
|
|
146
|
+
... columns=["true", "false"],
|
|
147
|
+
... )
|
|
148
|
+
>>> positive_scores, binary_target = to_binary_class(
|
|
149
|
+
... pred,
|
|
150
|
+
... target,
|
|
151
|
+
... positive_class="true",
|
|
152
|
+
... )
|
|
153
|
+
>>> positive_scores
|
|
154
|
+
tensor([0.2000, 0.9000, 0.6000])
|
|
155
|
+
>>> binary_target
|
|
156
|
+
tensor([False, True, True])
|
|
157
|
+
"""
|
|
158
|
+
if isinstance(target, TableTensor):
|
|
159
|
+
if target.size(-1) != 1:
|
|
160
|
+
raise ValueError(
|
|
161
|
+
f"Expected a single categorical target column "
|
|
162
|
+
f"(got {target.size(-1)} columns)"
|
|
163
|
+
)
|
|
164
|
+
target = target.categorical
|
|
165
|
+
|
|
166
|
+
if target.size(-1) != 1:
|
|
167
|
+
raise ValueError(
|
|
168
|
+
f"Expected a single categorical target column "
|
|
169
|
+
f"(got {target.size(-1)} columns)"
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
if pred.size()[:-1] != target.size()[:-1]:
|
|
173
|
+
raise ValueError(
|
|
174
|
+
f"Expected prediction and target row dimensions to match "
|
|
175
|
+
f"(got {tuple(pred.size()[:-1])} and "
|
|
176
|
+
f"{tuple(target.size())[:-1]})"
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
score = pred[str(positive_class)].numerical.squeeze(-1)
|
|
180
|
+
match = cast(Tensor, target.categories[0] == positive_class)
|
|
181
|
+
index = match.nonzero().view(-1)
|
|
182
|
+
if index.numel() != 1:
|
|
183
|
+
raise ValueError(
|
|
184
|
+
f"Expected positive class {positive_class!r} to appear exactly "
|
|
185
|
+
f"once in target categories (found {index.numel()} matches)"
|
|
186
|
+
)
|
|
187
|
+
|
|
188
|
+
return score, target.code.squeeze(-1) == index
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _parse_column(
|
|
192
|
+
column: str,
|
|
193
|
+
category: Tensor,
|
|
194
|
+
) -> bool | int | float | str:
|
|
195
|
+
if isinstance(category, StringTensor):
|
|
196
|
+
return column
|
|
197
|
+
if category.dtype == torch.bool:
|
|
198
|
+
if column == "True":
|
|
199
|
+
return True
|
|
200
|
+
if column == "False":
|
|
201
|
+
return False
|
|
202
|
+
raise ValueError(f"Cannot parse prediction column {column!r} as bool")
|
|
203
|
+
if category.is_floating_point():
|
|
204
|
+
return float(column)
|
|
205
|
+
return int(column)
|
sdm/explain/__init__.py
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Explainability modules for structured data models."""
|
|
5
|
+
|
|
6
|
+
from sdm.explain.base import ICLExplainer
|
|
7
|
+
from sdm.explain.gradient import GradientExplainer
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"ICLExplainer",
|
|
11
|
+
"GradientExplainer",
|
|
12
|
+
]
|
sdm/explain/base.py
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import abc
|
|
5
|
+
from typing import Any, Generic, TypeVar, final, overload
|
|
6
|
+
|
|
7
|
+
import torch
|
|
8
|
+
from torch import Tensor
|
|
9
|
+
|
|
10
|
+
from sdm import Recipe, RelatedTables, TableTensor
|
|
11
|
+
from sdm.models import ICLModel
|
|
12
|
+
|
|
13
|
+
T = TypeVar("T", covariant=True)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class ICLExplainer(abc.ABC, Generic[T]): # noqa: D101
|
|
17
|
+
@overload
|
|
18
|
+
def explain(
|
|
19
|
+
self,
|
|
20
|
+
model: ICLModel,
|
|
21
|
+
x_query: Tensor | TableTensor,
|
|
22
|
+
related_query_tables: RelatedTables[TableTensor] | None = None,
|
|
23
|
+
*,
|
|
24
|
+
x_context: Tensor | TableTensor,
|
|
25
|
+
y_context: Tensor | TableTensor,
|
|
26
|
+
related_context_tables: RelatedTables[TableTensor] | None = None,
|
|
27
|
+
recipe: Recipe | None = None,
|
|
28
|
+
generator: torch.Generator | None = None,
|
|
29
|
+
**kwargs: Any,
|
|
30
|
+
) -> T: ...
|
|
31
|
+
|
|
32
|
+
@overload
|
|
33
|
+
def explain(
|
|
34
|
+
self,
|
|
35
|
+
model: ICLModel,
|
|
36
|
+
x_query: Tensor | TableTensor,
|
|
37
|
+
related_query_tables: RelatedTables[TableTensor] | None = None,
|
|
38
|
+
) -> T: ...
|
|
39
|
+
|
|
40
|
+
@final
|
|
41
|
+
def explain( # noqa: D102
|
|
42
|
+
self,
|
|
43
|
+
model: ICLModel,
|
|
44
|
+
x_query: Tensor | TableTensor,
|
|
45
|
+
related_query_tables: RelatedTables[TableTensor] | None = None,
|
|
46
|
+
*,
|
|
47
|
+
x_context: Tensor | TableTensor | None = None,
|
|
48
|
+
y_context: Tensor | TableTensor | None = None,
|
|
49
|
+
related_context_tables: RelatedTables[TableTensor] | None = None,
|
|
50
|
+
recipe: Recipe | None = None,
|
|
51
|
+
generator: torch.Generator | None = None,
|
|
52
|
+
**kwargs: Any,
|
|
53
|
+
) -> T:
|
|
54
|
+
|
|
55
|
+
if x_context is not None:
|
|
56
|
+
assert y_context is not None
|
|
57
|
+
return self._explain_forward(
|
|
58
|
+
model,
|
|
59
|
+
x_context,
|
|
60
|
+
y_context,
|
|
61
|
+
x_query,
|
|
62
|
+
related_context_tables,
|
|
63
|
+
related_query_tables,
|
|
64
|
+
recipe=recipe,
|
|
65
|
+
generator=generator,
|
|
66
|
+
**kwargs,
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
if model._cache is None:
|
|
70
|
+
raise RuntimeError(
|
|
71
|
+
f"{model.__class__.__name__!r} is not fitted. Pass required "
|
|
72
|
+
f"context to 'explain()' or call "
|
|
73
|
+
f"'{model.__class__.__name__}.fit()' first."
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
return self._explain_predict(
|
|
77
|
+
model,
|
|
78
|
+
x_query,
|
|
79
|
+
related_query_tables,
|
|
80
|
+
generator=generator,
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
def _explain_forward(
|
|
84
|
+
self,
|
|
85
|
+
model: ICLModel,
|
|
86
|
+
x_context: Tensor | TableTensor,
|
|
87
|
+
y_context: Tensor | TableTensor,
|
|
88
|
+
x_query: Tensor | TableTensor,
|
|
89
|
+
related_context_tables: RelatedTables[TableTensor] | None = None,
|
|
90
|
+
related_query_tables: RelatedTables[TableTensor] | None = None,
|
|
91
|
+
*,
|
|
92
|
+
recipe: Recipe | None = None,
|
|
93
|
+
generator: torch.Generator | None = None,
|
|
94
|
+
**kwargs: Any,
|
|
95
|
+
) -> T:
|
|
96
|
+
kwargs.pop("callbacks", None)
|
|
97
|
+
model.fit(
|
|
98
|
+
x=x_context,
|
|
99
|
+
y=y_context,
|
|
100
|
+
related_tables=related_context_tables,
|
|
101
|
+
recipe=recipe,
|
|
102
|
+
generator=generator,
|
|
103
|
+
**kwargs,
|
|
104
|
+
)
|
|
105
|
+
try:
|
|
106
|
+
return self._explain_predict(
|
|
107
|
+
model,
|
|
108
|
+
x_query,
|
|
109
|
+
related_query_tables,
|
|
110
|
+
generator=generator,
|
|
111
|
+
)
|
|
112
|
+
finally:
|
|
113
|
+
model.clear()
|
|
114
|
+
|
|
115
|
+
@abc.abstractmethod
|
|
116
|
+
def _explain_predict(
|
|
117
|
+
self,
|
|
118
|
+
model: ICLModel,
|
|
119
|
+
x_query: Tensor | TableTensor,
|
|
120
|
+
related_query_tables: RelatedTables[TableTensor] | None = None,
|
|
121
|
+
*,
|
|
122
|
+
generator: torch.Generator | None = None,
|
|
123
|
+
) -> T: ...
|
sdm/explain/gradient.py
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
from typing import cast
|
|
7
|
+
|
|
8
|
+
import torch
|
|
9
|
+
from torch import Tensor
|
|
10
|
+
|
|
11
|
+
from sdm import RelatedTables, TableTensor
|
|
12
|
+
from sdm.explain.base import ICLExplainer
|
|
13
|
+
from sdm.models import ICLModel
|
|
14
|
+
from sdm.models.callback import CaptureInputs, EnableInputGradients
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class GradientExplainer(
|
|
18
|
+
ICLExplainer[tuple[TableTensor, RelatedTables[TableTensor] | None]]
|
|
19
|
+
):
|
|
20
|
+
"""Return gradients showing how small input changes affect predictions.
|
|
21
|
+
|
|
22
|
+
Gradients describe model predictions with respect to preprocessed
|
|
23
|
+
numerical query inputs, not the original input data.
|
|
24
|
+
|
|
25
|
+
For each output column, differentiate the sum of predictions over query
|
|
26
|
+
rows and batch dimensions. Requires exactly one estimator.
|
|
27
|
+
|
|
28
|
+
Attribution tables have shape ``[C, ..., R, D]``, where ``C`` is the output
|
|
29
|
+
count, ``R`` the query rows, and ``D`` the preprocessed input columns.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
def _explain_predict(
|
|
33
|
+
self,
|
|
34
|
+
model: ICLModel,
|
|
35
|
+
x_query: Tensor | TableTensor,
|
|
36
|
+
related_query_tables: RelatedTables[TableTensor] | None = None,
|
|
37
|
+
*,
|
|
38
|
+
generator: torch.Generator | None = None,
|
|
39
|
+
) -> tuple[TableTensor, RelatedTables[TableTensor] | None]:
|
|
40
|
+
callbacks = (EnableInputGradients(), CaptureInputs())
|
|
41
|
+
prediction = model.predict(
|
|
42
|
+
x=x_query,
|
|
43
|
+
related_tables=related_query_tables,
|
|
44
|
+
callbacks=callbacks,
|
|
45
|
+
)
|
|
46
|
+
if len(callbacks[1].inputs) != 1:
|
|
47
|
+
raise RuntimeError(
|
|
48
|
+
"GradientExplainer requires exactly one estimator"
|
|
49
|
+
)
|
|
50
|
+
x, related_tables = callbacks[1].inputs[0]
|
|
51
|
+
|
|
52
|
+
scores = prediction.numerical
|
|
53
|
+
|
|
54
|
+
leaves = [x.numerical]
|
|
55
|
+
if related_tables is not None:
|
|
56
|
+
leaves.extend(
|
|
57
|
+
table.numerical for table in related_tables.tables.values()
|
|
58
|
+
)
|
|
59
|
+
# scores: [..., R, C] -> explanations: [C, ..., R, D]
|
|
60
|
+
gradient_x, *gradient_related = zip(
|
|
61
|
+
*[
|
|
62
|
+
torch.autograd.grad(
|
|
63
|
+
scores[..., index].sum(),
|
|
64
|
+
leaves,
|
|
65
|
+
retain_graph=index < scores.size(-1) - 1,
|
|
66
|
+
allow_unused=True,
|
|
67
|
+
)
|
|
68
|
+
for index in range(scores.size(-1))
|
|
69
|
+
]
|
|
70
|
+
)
|
|
71
|
+
x_attributions = cast(
|
|
72
|
+
TableTensor,
|
|
73
|
+
torch.stack(
|
|
74
|
+
[
|
|
75
|
+
x.replace_blocks(
|
|
76
|
+
numerical=(
|
|
77
|
+
torch.zeros_like(x.numerical)
|
|
78
|
+
if gradient is None
|
|
79
|
+
else gradient
|
|
80
|
+
)
|
|
81
|
+
)
|
|
82
|
+
for gradient in gradient_x
|
|
83
|
+
]
|
|
84
|
+
),
|
|
85
|
+
)
|
|
86
|
+
if related_tables is None:
|
|
87
|
+
return x_attributions, None
|
|
88
|
+
|
|
89
|
+
related_attributions = related_tables.replace_tables(
|
|
90
|
+
tables={
|
|
91
|
+
name: cast(
|
|
92
|
+
TableTensor,
|
|
93
|
+
torch.stack(
|
|
94
|
+
[
|
|
95
|
+
table.replace_blocks(
|
|
96
|
+
numerical=(
|
|
97
|
+
torch.zeros_like(table.numerical)
|
|
98
|
+
if gradient is None
|
|
99
|
+
else gradient
|
|
100
|
+
)
|
|
101
|
+
)
|
|
102
|
+
for gradient in gradients
|
|
103
|
+
]
|
|
104
|
+
),
|
|
105
|
+
)
|
|
106
|
+
for (name, table), gradients in zip(
|
|
107
|
+
related_tables.tables.items(),
|
|
108
|
+
gradient_related,
|
|
109
|
+
)
|
|
110
|
+
}
|
|
111
|
+
)
|
|
112
|
+
return x_attributions, related_attributions
|
sdm/models/__init__.py
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Structured Data Models."""
|
|
5
|
+
|
|
6
|
+
from sdm.models.base import ICLModel
|
|
7
|
+
from sdm.models.ecoc import ECOC
|
|
8
|
+
from sdm.models.tabiclv2 import TabICLv2
|
|
9
|
+
from sdm.models.tabfm import TabFM
|
|
10
|
+
from sdm.models.kumo import KumoTabular, KumoRelational
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
__all__ = [
|
|
14
|
+
"ICLModel",
|
|
15
|
+
"ECOC",
|
|
16
|
+
"TabICLv2",
|
|
17
|
+
"TabFM",
|
|
18
|
+
"KumoTabular",
|
|
19
|
+
"KumoRelational",
|
|
20
|
+
]
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
from huggingface_hub import hf_hub_download
|
|
7
|
+
from huggingface_hub.utils import LocalEntryNotFoundError
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def download_checkpoint(
|
|
11
|
+
repo_id: str,
|
|
12
|
+
filename: str,
|
|
13
|
+
*,
|
|
14
|
+
revision: str | None = None,
|
|
15
|
+
cache_dir: str | Path | None = None,
|
|
16
|
+
local_files_only: bool = False,
|
|
17
|
+
license_prompt: str | None = None,
|
|
18
|
+
config_filename: str | None = None,
|
|
19
|
+
) -> str:
|
|
20
|
+
r"""Resolve a checkpoint from the Hugging Face cache or Hub.
|
|
21
|
+
|
|
22
|
+
Authentication is delegated to :mod:`huggingface_hub`, which uses its
|
|
23
|
+
configured login or the ``HF_TOKEN`` environment variable for private
|
|
24
|
+
repositories.
|
|
25
|
+
"""
|
|
26
|
+
try:
|
|
27
|
+
return hf_hub_download(
|
|
28
|
+
repo_id=repo_id,
|
|
29
|
+
filename=filename,
|
|
30
|
+
revision=revision,
|
|
31
|
+
cache_dir=cache_dir,
|
|
32
|
+
local_files_only=True,
|
|
33
|
+
)
|
|
34
|
+
except LocalEntryNotFoundError:
|
|
35
|
+
if local_files_only:
|
|
36
|
+
raise
|
|
37
|
+
if license_prompt is not None:
|
|
38
|
+
print(f"{license_prompt}\n") # noqa: T201
|
|
39
|
+
answer = input("Accept license terms? [y/N] ")
|
|
40
|
+
if answer.lower() not in {"y", "yes"}:
|
|
41
|
+
raise RuntimeError(
|
|
42
|
+
"Checkpoint download requires license acceptance"
|
|
43
|
+
) from None
|
|
44
|
+
if config_filename is not None:
|
|
45
|
+
hf_hub_download(
|
|
46
|
+
repo_id=repo_id,
|
|
47
|
+
filename=config_filename,
|
|
48
|
+
revision=revision,
|
|
49
|
+
cache_dir=cache_dir,
|
|
50
|
+
local_files_only=False,
|
|
51
|
+
)
|
|
52
|
+
return hf_hub_download(
|
|
53
|
+
repo_id=repo_id,
|
|
54
|
+
filename=filename,
|
|
55
|
+
revision=revision,
|
|
56
|
+
cache_dir=cache_dir,
|
|
57
|
+
local_files_only=False,
|
|
58
|
+
)
|