quantus.helpers.model.model_interface module

This model implements the basics for the ModelInterface class.

class quantus.helpers.model.model_interface.ModelInterface(model: M, channel_first: bool | None = True, softmax: bool = False, model_predict_kwargs: Dict[str, Any] | None = None)

Bases: ABC, Generic[M]

Base ModelInterface for torch and tensorflow models.

Attributes:

get_ml_framework_name

Identify the framework of the underlying model (PyTorch or TensorFlow).

random_layer_generator_length

Count number of randomisable layers for Model Parameter Randomisation.

Methods

add_mean_shift_to_first_layer(input_shift, shape)	Consider the first layer neuron before non-linearity: z = w^T * x1 + b1.
get_hidden_representations(x[, layer_names, ...])	Compute the model's internal representation of input x.
get_model()	Get the original torch/tf model.
get_random_layer_generator([order, seed])	In every iteration yields a copy of the model with one additional layer's parameters randomized.
get_softmax_arg_model()	Returns model with last layer adjusted accordingly to softmax argument.
predict(x, **kwargs)	Predict on the given input.
shape_input(x, shape[, channel_first, batched])	Reshape input into model expected input.
state_dict()	Get a dictionary of the model's learnable parameters.

__init__(model: M, channel_first: bool | None = True, softmax: bool = False, model_predict_kwargs: Dict[str, Any] | None = None)

Initialisation of ModelInterface class.

Parameters:

model: torch.nn.Module, tf.keras.Model

A model this will be wrapped in the ModelInterface:

channel_first: boolean, optional

Indicates of the image dimensions are channel first, or channel last. Inferred from the input shape if None.

softmax: boolean

Indicates whether to use softmax probabilities or logits in model prediction. This is used for this __call__ only and won’t be saved as attribute. If None, self.softmax is used.

model_predict_kwargs: dict, optional

Keyword arguments to be passed to the model’s predict method.

abstract add_mean_shift_to_first_layer(input_shift: int | float, shape: tuple)

Consider the first layer neuron before non-linearity: z = w^T * x1 + b1. We update the bias b1 to b2:= b1 - w^T * m. The operation is necessary for Input Invariance metric.

Parameters:

input_shift: Union[int, float]

Shift to be applied.

shape: tuple

Model input shape.

Returns:

new_model: torch.nn

The resulting model with a shifted first layer.

abstract get_hidden_representations(x: ndarray, layer_names: List[str] | None = None, layer_indices: List[int] | None = None) → ndarray

Compute the model’s internal representation of input x. In practice, this means, executing a forward pass and then, capturing the output of layers (of interest). As the exact definition of “internal model representation” is left out in the original paper (see: https://arxiv.org/pdf/2203.06877.pdf), we make the implementation flexible. It is up to the user whether all layers are used, or specific ones should be selected. The user can therefore select a layer by providing ‘layer_names’ (exclusive) or ‘layer_indices’.

Parameters:

x: np.ndarray

4D tensor, a batch of input datapoints

layer_names: List[str]

List with names of layers, from which output should be captured.

layer_indices: List[int]

List with indices of layers, from which output should be captured. Intended to use in case, when layer names are not unique, or unknown.

Returns:

L: np.ndarray

2D tensor with shape (batch_size, None)

property get_ml_framework_name: str

Identify the framework of the underlying model (PyTorch or TensorFlow).

Returns:

str

A string indicating the framework (‘PyTorch’, ‘TensorFlow’, or ‘Unknown’).

abstract get_model()

Get the original torch/tf model.

abstract get_random_layer_generator(order: str = 'top_down', seed: int = 42) → Generator[Tuple[str, M], None, None]

In every iteration yields a copy of the model with one additional layer’s parameters randomized. For cascading randomization, set order (str) to ‘top_down’. For independent randomization, set it to ‘independent’. For bottom-up order, set it to ‘bottom_up’.

abstract get_softmax_arg_model()

Returns model with last layer adjusted accordingly to softmax argument. If the original model has softmax activation as the last layer and softmax=false, the layer is removed.

abstract predict(x: array, **kwargs)

Predict on the given input.

Parameters:

x: np.ndarray

A given input that the wrapped model predicts on.

kwargs: optional

Keyword arguments.

abstract property random_layer_generator_length: int

Count number of randomisable layers for Model Parameter Randomisation. This property is needed to avoid len(model.get_random_layer_generator()), because meterializing bigger models num_layers times in memory at ones has shown to cause OOM errors.

Returns:

n:

Number of layers in model, which can be randomised.

abstract shape_input(x: array, shape: Tuple[int, ...], channel_first: bool | None = None, batched: bool = False)

Reshape input into model expected input.

Parameters:

x: np.ndarray

A given input that is shaped.

shape: Tuple[int…]

The shape of the input.

channel_first: boolean, optional

Indicates of the image dimensions are channel first, or channel last. Inferred from the input shape if None.

abstract state_dict()

Get a dictionary of the model’s learnable parameters.