ytm.guided.MultiClassTM

class ytm.guided.MultiClassTM(n_clauses: int, s: float, dim: int | tuple[int, ...], n_classes: int, **opt: Unpack[T_Config])

Bases: Classifier

Guided TM for multi-class classification: each sample has exactly one of n_classes classes.

The default act_loss is SoftmaxCE.

Parameters:

n_clausesint

Clauses per class. See TMConfig.

sfloat

Specificity, at least 1.0.

dimint or tuple of int

Input shape: D, (H, W) or (H, W, C).

n_classesint

Number of classes.

**opt

Other options of TMConfig, and device and block_size of DeviceConfig.

property config: TMConfig

Model settings, see BaseTMConfig. Treat it as read-only: the kernels and derived values are built from it at construction.

property decision_threshold: float | None

Activated output above which predict outputs 1, for multi-label and binary models. Default depends on the activation: 0.5 for sigmoid and softmax, 0.0 for identity.

property device_config: DeviceConfig

Device settings, see DeviceConfig. Use to() to change the device.

fit(X: ndarray, Y: ndarray, shuffle: bool = True, clause_drop_p: float = 0.0, lr: float | None = None, lambda_: float | None = None) → float

Train for one epoch.

Parameters:

Xarray-like of int, shape (N, *dim) or (N, prod(dim))

Inputs, each feature within [feat_mins, feat_maxs].

Yarray-like of int

Targets: class labels of shape (N,) in [0, n_classes), or one-hot or multi-hot of shape (N, n_classes). For BinaryTM, 0 or 1 of shape (N,).

shufflebool, default=True

Visit the samples in a random order.

clause_drop_pfloat, default=0.0

Probability of dropping each clause for this epoch (Drop Clause).

lrfloat, default=None

Learning rate for this epoch. None uses the config’s lr.

lambda_float, default=None

Feedback rate for this epoch. None uses the config’s lambda_.

Returns:

float

Mean loss per sample over the epoch.

get_clauses(force_repack: bool = True) → ClauseInfo

Get the clauses as feature bounds, position bounds and weights.

The result is cached in clauseinfo.

Parameters:

force_repackbool, default=True

Build the clauses again from the current TA states. False returns the cached result when there is one.

Returns:

ClauseInfo

See ClauseInfo.

get_literals() → ndarray

Get the clauses showing include and excludes only. 1 if the literal is included, 0 if excluded.

Returns:

ndarray of shape (n_clause_banks, n_clauses, n_literals), uint8

get_patch_weights() → ndarray

Get patch weights.

Returns:

ndarray of shape (n_clause_banks, n_clauses, n_patches_y, n_patches_x)

get_ta_states() → ndarray

Get TA states.

Returns:

ndarray of shape (n_clause_banks, n_clauses, n_literals)

get_weights() → ndarray

Get weights.

Returns:

ndarray of shape (n_classes, n_clauses), float32

predict(X: ndarray, force_repack: bool = False)

Predict the class of each sample: the class with the highest activated output.

Parameters:

Xarray-like of int, shape (N, *dim) or (N, prod(dim))

Inputs, each feature within [feat_mins, feat_maxs].

force_repackbool, default=False

Repack every clause first, not only the changed ones.

Returns:

predsndarray of shape (N,)

Predicted class.

class_sumsndarray of shape (N, n_classes)

Activated output of each class.

score(X: ndarray, force_repack: bool = False) → ndarray

Calculate class sums or model outputs for the given X.

Parameters:

Xarray-like of int, shape (N, *dim) or (N, prod(dim))

Inputs, each feature within [feat_mins, feat_maxs].

force_repackbool, default=False

Force a clause repack.

Returns:

ndarray of shape (N, n_classes), float32

Output of each class.

set_threads(n: int) → None

Set the number of threads to use with OpenMP. Only applicable for CPU device.

to(device: str, **device_kwargs) → None

Move the model to another device, in place.

Parameters:

devicestr

"cpu[:n_threads]" or "cuda[:gpu_id]".

**device_kwargs

Other DeviceConfig options, e.g. block_size. Options not given go back to their defaults.

to_prob(class_sums: ndarray) → ndarray

No-op, simply returns the activated class sums (class_sums) as is.

transform(X: ndarray, force_repack: bool = False) → ndarray

Clause outputs per sample: 1 where the clause fires (on any patch), else 0.

Parameters:

Xarray-like of int, shape (N, *dim) or (N, prod(dim))

Inputs, each feature within [feat_mins, feat_maxs].

force_repackbool, default=False

Force a clause repack.

Returns:

ndarray of shape (N, n_clause_banks, n_clauses), int8

Clause outputs. n_clause_banks is 1 when coalesced, else n_classes.

transform_patchwise(X: ndarray, force_repack: bool = False) → ndarray

Patchwise clause outputs per sample.

Parameters:

Xarray-like of int, shape (N, *dim) or (N, prod(dim))

Inputs, each feature within [feat_mins, feat_maxs].

force_repackbool, default=False

Force a clause repack.

Returns:

ndarray of shape (N, n_clause_banks, n_clauses, n_patches_y, n_patches_x), int8

Clause outputs. n_clause_banks is 1 when coalesced, else n_classes.

wac(X: ndarray, target_classes: ndarray, polarity: int, force_repack: bool = False) → ndarray

Calculate the WAC score, obtained by taking the weighted sum of activated clauses for each sample in X. This provides the Local Interpretation of the model for a given input.

Note

This functions does not normalize the WAC, it simply returns the raw values. Use norm_asymmetric() on the scores to normalize them.

Parameters:

Xarray-like of int, shape (N, *dim) or (N, prod(dim))

Inputs, each feature within [feat_mins, feat_maxs].

target_classesarray-like of int, shape (N,)

Class whose clause weights are used, per sample.

polarityint

+1 for the clauses with positive weight for the target class, -1 for negative.

force_repackbool, default=False

Force a clause repack.

Returns:

ndarray of shape (N, H, W, C), float32

WAC score per sample and input feature.

wic(class_id: int, polarity: int, pw_th: float = 0.0, force_repack: bool = False) → ndarray

Calculate the WIC score, obtained by taking weighted sum of a set of clauses. This does not depend on X, does not care about clause activations, and thus provides the Global Interpretation of the model.

class_id and polarity define which set of clauses to use.

Note

This functions does not normalize the WIC, it simply returns the raw values. Use norm_asymmetric() on the scores to normalize them.

Parameters:

class_idint

Class whose clause weights are used.

polarityint

+1 for the clauses with positive weight for class_id, -1 for negative.

pw_thfloat, default=0.0

Convolutional models only: skip patches whose patch weight, normalized per clause to [0, 1], is at or below this value.

force_repackbool, default=False

Force a clause repack.

Returns:

ndarray of shape (H, W, C), float32

WIC score per input feature.