ytm.tm.BinaryTM

class ytm.tm.BinaryTM(n_clauses: int, T: float | tuple[float, float], s: float, dim: int | tuple[int, ...], **opt: Unpack[T_Config])

Bases: Classifier

TM for binary classification: one output, each sample is 0 or 1.

Defaults differ from TMConfig: coalesced=False and allow_polarity_change=False.

Parameters:

n_clausesint

Number of clauses.

Tfloat or tuple of (float, float)

Vote threshold.

sfloat

Specificity, at least 1.0.

dimint or tuple of int

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

**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

Class sum above which predict outputs 1, for multi-label and binary models. Default 0.0.

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, label_sampling: bool = False)

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).

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, clip_class_sums: bool = False, force_repack: bool = False)

Predict each sample: 1 where the class sum is above decision_threshold, else 0.

Parameters:

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

Inputs, each feature within [feat_mins, feat_maxs].

clip_class_sumsbool, default=False

Clip the returned class sums to [T_min, T_max].

force_repackbool, default=False

Repack every clause first, not only the changed ones.

Returns:

predsndarray of shape (N,), uint32

Predicted output, 0 or 1.

class_sumsndarray of shape (N, 1)

Weighted vote sum.

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

Calculate class sums 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

Repack every clause first, not only the changed ones.

clip_class_sumsbool, default=False

Clip the class sums to [T_min, T_max].

Returns:

ndarray of shape (N, n_classes), float32

Class sums.

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

Convert the class sums to probabilities.

(clip(class_sums, T_min, T_max) - T_min) / (T_max - T_min)

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.