IBA.pytorch

to_saliency_map(capacity, shape=None)

Converts the layer capacity (in nats) to a saliency map (in bits) of the given shape .

Parameters

• capacity (np.ndarray) – Capacity in nats.

• shape (tuple) – (height, width) of the image.

insert_into_sequential(sequential, layer, idx)

Returns a nn.Sequential with layer inserted in sequential at position idx.

tensor_to_np_img(img_t)

Convert a torch tensor of shape (c, h, w) to a numpy array of shape (h, w, c) and reverse the torchvision prepocessing.

imagenet_transform(resize=256, crop_size=224)

Returns the default torchvision imagenet transform.

get_imagenet_folder(path, image_size=224, transform='default')

Returns a torchvision.datasets.ImageFolder with the default torchvision preprocessing.

class TorchWelfordEstimator

Bases: torch.nn.modules.module.Module

Estimates the mean and standard derivation. For the algorithm see https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance.

Example

Given a batch of images imgs with shape (10, 3, 64, 64), the mean and std could be estimated as follows:

# exemplary data source: 5 batches of size 10, filled with random data
batch_generator = (torch.randn(10, 3, 64, 64) for _ in range(5))

estim = WelfordEstimator(3, 64, 64)
for batch in batch_generator:
    estim(batch)

# returns the estimated mean
estim.mean()

# returns the estimated std
estim.std()

# returns the number of samples, here 10
estim.n_samples()

# returns a mask with active neurons
estim.active_neurons()

forward(x)

Update estimates without altering x

n_samples()

Returns the number of seen samples.

mean()

Returns the estimate of the mean.

std()

returns the estimate of the standard derivation.

active_neurons(threshold=0.01)

Returns a mask of all active neurons. A neuron is considered active if n_nonzero / n_samples  > threshold

class IBA(layer=None, sigma=1.0, beta=10, min_std=0.01, optimization_steps=10, lr=1, batch_size=10, initial_alpha=5.0, active_neurons_threshold=0.01, feature_mean=None, feature_std=None, estimator=None, progbar=False, input_or_output='output', relu=False)

Bases: torch.nn.modules.module.Module

IBA finds relevant features of your model by applying noise to intermediate features.

Example:

model = Net()
# Create the Per-Sample Bottleneck:
iba = IBA(model.conv4)

# Estimate the mean and variance.
iba.estimate(model, datagen)

img, target = next(iter(datagen(batch_size=1)))

# Closure that returns the loss for one batch
model_loss_closure = lambda x: F.nll_loss(F.log_softmax(model(x), target)

# Explain class target for the given image
saliency_map = iba.analyze(img.to(dev), model_loss_closure)
plot_saliency_map(img.to(dev))

Parameters

• layer – The layer after which to inject the bottleneck

• sigma – The standard deviation of the gaussian kernel to smooth the mask, or None for no smoothing

• beta – Weighting of model loss and mean information loss.

• min_std – Minimum std of the features

• lr – Optimizer learning rate. default: 1. As we are optimizing over very few iterations, a relatively high learning rate can be used compared to the training of the model itself.

• batch_size – Number of samples to use per iteration

• input_or_output – Select either "output" or "input".

• initial_alpha – Initial value for the parameter.

detach()

Remove the bottleneck to restore the original model

forward(x)

You don’t need to call this method manually.

The IBA acts as a model layer, passing the information in x along to the next layer either as-is or by restricting the flow of infomration. We use it also to estimate the distribution of x passing through the layer.

interrupt_execution()

Interrupts the execution of the model, once PerSampleBottleneck is called. Useful for estimation when the model has only be executed until the Per-Sample Bottleneck.

Example

Executes the model only until the bottleneck layer:

with bltn.interrupt_execution():
    out = model(x)
    # out will not be defined
    print("this will not be printed")

enable_estimation()

Context manager to enable estimation of the mean and standard derivation. We recommend to use the self.estimate method.

reset_estimate()

Resets the estimator. Useful if the distribution changes. Which can happen if you trained the model more.

estimate(model, dataloader, device=None, n_samples=10000, progbar=None, reset=True)

Estimate mean and variance using the welford estimator. Usually, using 10.000 i.i.d. samples gives decent estimates.

Parameters

• model – the model containing the bottleneck layer

• dataloader – yielding batch’s where the first sample batch[0] is the image batch.

• device – images will be transfered to the device. If None, it uses the device of the first model parameter.

• n_samples (int) – run the estimate on that many samples

• progbar (bool) – show a progress bar.

• reset (bool) – reset the current estimate of the mean and std

restrict_flow()

Context mananger to enable information supression.

Example

To make a prediction, with the information flow being supressed.:

with iba.restrict_flow():
    # now noise is added
    model(x)

analyze(input_t, model_loss_fn, mode='saliency', beta=None, optimization_steps=None, min_std=None, lr=None, batch_size=None, active_neurons_threshold=0.01)

Generates a heatmap for a given sample. Make sure you estimated mean and variance of the input distribution.

Parameters

• input_t – input image of shape (1, C, H W)

• model_loss_fn – closure evaluating the model

• mode – how to post-process the resulting map: ‘saliency’ (default) or ‘capacity’

• beta – if not None, overrides the bottleneck beta value

• optimization_steps – if not None, overrides the bottleneck optimization_steps value

• min_std – if not None, overrides the bottleneck min_std value

• lr – if not None, overrides the bottleneck lr value

• batch_size – if not None, overrides the bottleneck batch_size value

• active_neurons_threshold – used threshold to determine if a neuron is active

Returns

The heatmap of the same shape as the input_t.

capacity()

Returns a tensor with the capacity from the last input, averaged over the redundant batch dimension. Shape is (self.channels, self.height, self.width)