deepreplay package

Submodules

deepreplay.callbacks module

class deepreplay.callbacks.ReplayData(inputs, targets, filename, group_name, model=None)[source]

Bases: keras.callbacks.Callback

Creates an instance of a Keras Callback to collect information about the training process, mostly the weights, and store them in a group of a HDF5 file, together with inputs and targets passed as arguments.

It also saves the Keras model itself, as an independent HDF5 file, named after the group_name with ‘_model’ appended to it.

Parameters:
  • inputs (ndarray) – An array with the inputs to be used during the training of the model. These inputs are going to be later used to generate statistics and plots.
  • targets (ndarray) – An array with the targets to be used during the training of the model. These targets are going to be later used to generate statistics and plots.
  • filename (String) – HDF5 filename to be used to store the collected information. It can be an existing file, as the data will be appended to it.
  • group_name (String) – Group inside the HDF5 file where the information is to be saved. If the informed group name already exists, it will throw an exception.
  • model (Keras Model, optional) – If provided, it will set the model directly to the callback instance and execute on_train_begin method to initialize all variables and create the corresponding group in the HDF5 file. This is intended to be used for analyzing the initial conditions of the model without ever calling its fit function, where the callback is usually called.
get_lr()[source]
on_epoch_begin(epoch, logs={})[source]
on_epoch_end(epoch, logs={})[source]
on_train_begin(logs={})[source]
on_train_end(logs={})[source]

deepreplay.plot module

class deepreplay.plot.Basic(ax)[source]

Bases: object

Basic plot class, NOT to be instantiated directly.

animate(epoch_start=0, epoch_end=-1)[source]

Animates plotted data from epoch_start to epoch_end.

Parameters:
  • epoch_start (int, optional) – Epoch to start the animation from.
  • epoch_end (int, optional) – Epoch to end the animation.
Returns:

anim – Animation function for the data.

Return type:

FuncAnimation

axes
load_data(**kwargs)[source]
plot(epoch)[source]

Plots data at a given epoch.

Parameters:epoch (int) – Epoch to use for the plotting.
Returns:fig – Figure containing the plot.
Return type:figure
set_title(title)[source]

Prepends a custom title to the plot.

Parameters:title (String) – Custom title to prepend.
Returns:
Return type:None
title
class deepreplay.plot.FeatureSpace(ax, scale_fixed=True)[source]

Bases: deepreplay.plot.Basic

Creates an instance of a FeatureSpace object to make plots and animations.

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • scaled_fixed (boolean, optional) – If True, axis scales are fixed to the maximum from beginning. Default is True.
load_data(feature_space_data)[source]

Loads feature space data as computed in Replay class.

Parameters:feature_space_data (FeatureSpaceData) – Namedtuple containing information about original grid lines, data points and predictions.
Returns:self – Returns the FeatureSpace instance itself.
Return type:FeatureSpace
class deepreplay.plot.FeatureSpaceData(line, bent_line, prediction, target)

Bases: tuple

bent_line

Alias for field number 1

line

Alias for field number 0

prediction

Alias for field number 2

target

Alias for field number 3

class deepreplay.plot.FeatureSpaceLines(grid, input, contour)

Bases: tuple

contour

Alias for field number 2

grid

Alias for field number 0

input

Alias for field number 1

class deepreplay.plot.LayerViolins(ax, title)[source]

Bases: deepreplay.plot.Basic

load_data(layer_violins_data)[source]
class deepreplay.plot.LayerViolinsData(names, values, layers, selected_layers)

Bases: tuple

layers

Alias for field number 2

names

Alias for field number 0

selected_layers

Alias for field number 3

values

Alias for field number 1

class deepreplay.plot.LossAndMetric(ax)[source]

Bases: deepreplay.plot.Basic

Creates an instance of a LossAndMetric object to make plots and animations.

Parameters:ax (AxesSubplot) – Subplot of a Matplotlib figure.
load_data(loss_and_metric_data)[source]

Loads loss and metric data as computed in Replay class.

Parameters:loss_and_metric_data (LossAndMetricData) – Namedtuple containing information about loss and a given metric.
Returns:self – Returns the LossAndMetric instance itself.
Return type:LossAndMetric
class deepreplay.plot.LossAndMetricData(loss, metric, metric_name)

Bases: tuple

loss

Alias for field number 0

metric

Alias for field number 1

metric_name

Alias for field number 2

class deepreplay.plot.LossHistogram(ax)[source]

Bases: deepreplay.plot.Basic

Creates an instance of a LossHistogram object to make plots and animations.

Parameters:ax (AxesSubplot) – Subplot of a Matplotlib figure.
load_data(loss_hist_data)[source]

Loads loss histogram data as computed in Replay class.

Parameters:loss_hist_data (LossHistogramData) – Namedtuple containing information about example’s losses.
Returns:self – Returns the LossHistogram instance itself.
Return type:LossHistogram
class deepreplay.plot.LossHistogramData(loss)

Bases: tuple

loss

Alias for field number 0

class deepreplay.plot.ProbHistogramData(prob, target)

Bases: tuple

prob

Alias for field number 0

target

Alias for field number 1

class deepreplay.plot.ProbabilityHistogram(ax1, ax2)[source]

Bases: deepreplay.plot.Basic

Creates an instance of a ProbabilityHistogram object to make plots and animations.

Parameters:
  • ax1 (AxesSubplot) – Subplot of a Matplotlib figure, for the negative cases.
  • ax2 (AxesSubplot) – Subplot of a Matplotlib figure, for the positive cases.
axes
load_data(prob_histogram_data)[source]

Loads probability histogram data as computed in Replay class.

Parameters:prob_histogram_data (ProbHistogramData) – Namedtuple containing information about classification probabilities and targets.
Returns:self – Returns the ProbabilityHistogram instance itself.
Return type:ProbabilityHistogram
deepreplay.plot.build_2d_grid(xlim, ylim, n_lines=11, n_points=1000)[source]
Returns a 2D grid of boundaries given by xlim and ylim,
composed of n_lines evenly spaced lines of n_points each.
Parameters:
  • xlim (tuple of 2 ints) – Boundaries for the X axis of the grid.
  • ylim (tuple of 2 ints) – Boundaries for the Y axis of the grid.
  • n_lines (int, optional) – Number of grid lines. Default is 11. If n_lines equals n_points, the grid can be used as coordinates for the surface of a contourplot.
  • n_points (int, optional) – Number of points in each grid line. Default is 1,000.
Returns:

lines – For the cases where n_lines is less than n_points, it returns an array of shape (2 * n_lines, n_points, 2) containing both vertical and horizontal lines of the grid. If n_lines equals n_points, it returns an array of shape (n_points, n_points, 2), containing all evenly spaced points inside the grid boundaries.

Return type:

ndarray

deepreplay.plot.compose_animations(objects, epoch_start=0, epoch_end=-1, title='')[source]

Compose a single animation from several objects associated with subplots of a single figure.

Parameters:
  • objects (list of plot objects) – Plot objects returned using one of the ‘build’ methods of the Replay class. All the corresponding subplots associated with the objects must belong to the same figure.
  • epoch_start (int, optional) – Epoch to start the animation from.
  • epoch_end (int, optional) – Epoch to end the animation.
  • title (String, optional) – Text to be used in the title, preceding the epoch information.
Returns:

anim – Composed animation function for all objects / subplots.

Return type:

FuncAnimation

deepreplay.plot.compose_plots(objects, epoch, title='')[source]

Compose a single plot from several objects associated with subplots of a single figure.

Parameters:
  • objects (list of plot objects) – Plot objects returned using one of the ‘build’ methods of the Replay class. All the corresponding subplots associated with the objects must belong to the same figure.
  • epoch (int) – Epoch to use for the plotting.
  • title (String, optional) – Text to be used in the title, preceding the epoch information.
Returns:

fig – Figure which contains all subplots.

Return type:

figure

deepreplay.replay module

class deepreplay.replay.Replay(replay_filename, group_name, model_filename='')[source]

Bases: object

Creates an instance of Replay, to process information collected by the callback and generate data to feed the supported visualizations.

Parameters:
  • replay_filename (String) – HDF5 filename used by the callback to store the training information.
  • group_name (String) – Group inside the HDF5 file where the information was saved.
  • model_filename (String, optional) – HDF5 filename of the saved Keras model. Default is the group_name with ‘_model’ appended to it.
feature_space

FeatureSpace object to be used for plotting and animating; namedtuple containing information about original grid lines, data points and predictions.

Type:(FeatureSpace, FeatureSpaceData)
loss_histogram

LossHistogram object to be used for plotting and animating; namedtuple containing information about example’s losses.

Type:(LossHistogram, LossHistogramData)
loss_and_metric

LossAndMetric object to be used for plotting and animating; namedtuple containing information about loss and a given metric.

Type:(LossAndMetric, LossAndMetricData)
probability_histogram

ProbabilityHistogram object to be used for plotting and animating; namedtuple containing information about classification probabilities and targets.

Type:(ProbabilityHistogram, ProbHistogramData)
weights_violins

LayerViolins object to be used for plotting and animating; namedtuple containing information about weights values per layer.

Type:(LayerViolins, LayerViolinsData)
activations_violins

LayerViolins object to be used for plotting and animating; namedtuple containing information about activation values per layer.

Type:(LayerViolins, LayerViolinsData)
zvalues_violins

LayerViolins object to be used for plotting and animating; namedtuple containing information about Z-values per layer.

Type:(LayerViolins, LayerViolinsData)
gradients_violins

LayerViolins object to be used for plotting and animating; namedtuple containing information about gradient values per layer.

Type:(LayerViolins, LayerViolinsData)
weights_std

Standard deviation of the weights per layer.

Type:ndarray
gradients_std

Standard deivation of the gradients per layer.

Type:ndarray
training_loss

An array of shape (n_epochs, ) with training loss as reported by Keras at the end of each epoch.

Type:ndarray
learning_rate

An array of shape (n_epochs, ) with learning rate as reported by Keras at the beginning of each epoch.

Type:ndarray
activations_violins
build_decision_boundary(ax, contour_points=1000, xlim=(-1, 1), ylim=(-1, 1), display_grid=True, epoch_start=0, epoch_end=-1)[source]

Builds a FeatureSpace object to be used for plotting and animating the raw inputs and the decision boundary. The underlying data, that is, grid lines, inputs and contour lines, as well as the corresponding predictions for the contour lines, can be later accessed as the second element of the decision_boundary property.

Only inputs with 2 dimensions are supported!

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • contour_points (int, optional) – Number of points in each axis of the contour. Default is 1,000.
  • xlim (tuple of ints, optional) – Boundaries for the X axis of the grid.
  • ylim (tuple of ints, optional) – Boundaries for the Y axis of the grid.
  • display_grid (boolean, optional) – If True, display grid lines (for 2-dimensional inputs). Default is True.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

decision_boundary_plot – An instance of a FeatureSpace object to make plots and animations.

Return type:

FeatureSpace

build_feature_space(ax, layer_name, contour_points=1000, xlim=(-1, 1), ylim=(-1, 1), scale_fixed=True, display_grid=True, epoch_start=0, epoch_end=-1)[source]

Builds a FeatureSpace object to be used for plotting and animating. The underlying data, that is, grid lines, inputs and contour lines, before and after the transformations, as well as the corresponding predictions for the contour lines, can be later accessed as the second element of the feature_space property.

Only layers with 2 hidden units are supported!

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • layer_name (String) – Layer to be used for building the space.
  • contour_points (int, optional) – Number of points in each axis of the contour. Default is 1,000.
  • xlim (tuple of ints, optional) – Boundaries for the X axis of the grid.
  • ylim (tuple of ints, optional) – Boundaries for the Y axis of the grid.
  • scaled_fixed (boolean, optional) – If True, axis scales are fixed to the maximum from beginning. Default is True.
  • display_grid (boolean, optional) – If True, display grid lines (for 2-dimensional inputs). Default is True.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

feature_space_plot – An instance of a FeatureSpace object to make plots and animations.

Return type:

FeatureSpace

build_gradients(ax, layer_names=None, exclude_outputs=True, epoch_start=0, epoch_end=-1)[source]

Builds a LayerViolins object to be used for plotting and animating.

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • layer_names (list of Strings, optional) – If informed, plots only the listed layers.
  • exclude_outputs (boolean, optional) – If True, excludes distribution of output layer. Default is True. If layer_names is informed, exclude_outputs is ignored.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

gradients_plot – An instance of a LayerViolins object to make plots and animations.

Return type:

LayerViolins

build_loss_and_metric(ax, metric_name, epoch_start=0, epoch_end=-1)[source]

Builds a LossAndMetric object to be used for plotting and animating. The underlying data, that is, the loss and metric per epoch, can be later accessed as the second element of the loss_and_metric property.

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • metric_name (String) – Metric to return values for.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

loss_and_metric_plot – An instance of a LossAndMetric object to make plots and animations.

Return type:

LossAndMetric

build_loss_histogram(ax, epoch_start=0, epoch_end=-1)[source]

Builds a LossHistogram object to be used for plotting and animating. The underlying data, that is, the binary cross-entropy loss per epoch and sample, can be later accessed as the second element of the loss_histogram property.

Only binary cross entropy loss is supported!

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

loss_hist_plot – An instance of a LossHistogram object to make plots and animations.

Return type:

LossHistogram

build_outputs(ax, before_activation=False, layer_names=None, include_inputs=True, exclude_outputs=True, epoch_start=0, epoch_end=-1)[source]

Builds a LayerViolins object to be used for plotting and animating.

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • before_activation (Boolean, optional) – If True, returns Z-values, that is, before applying the activation function.
  • layer_names (list of Strings, optional) – If informed, plots only the listed layers.
  • include_inputs (boolean, optional) – If True, includes distribution of inputs. Default is True.
  • exclude_outputs (boolean, optional) – If True, excludes distribution of output layer. Default is True. If layer_names is informed, exclude_outputs is ignored.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

activations_violins_plot/zvalues_violins_plot – An instance of a LayerViolins object to make plots and animations.

Return type:

LayerViolins

build_probability_histogram(ax_negative, ax_positive, epoch_start=0, epoch_end=-1)[source]

Builds a ProbabilityHistogram object to be used for plotting and animating. The underlying data, that is, the predicted probabilities and corresponding targets per epoch and sample, can be later accessed as the second element of the probability_histogram property.

Only binary classification is supported!

Parameters:
  • ax_negative (AxesSubplot) – Subplot of a Matplotlib figure.
  • ax_positive (AxesSubplot) – Subplot of a Matplotlib figure.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

prob_hist_plot – An instance of a ProbabilityHistogram object to make plots and animations.

Return type:

ProbabilityHistogram

build_weights(ax, layer_names=None, exclude_outputs=True, epoch_start=0, epoch_end=-1)[source]

Builds a LayerViolins object to be used for plotting and animating.

Parameters:
  • ax (AxesSubplot) – Subplot of a Matplotlib figure.
  • layer_names (list of Strings, optional) – If informed, plots only the listed layers.
  • exclude_outputs (boolean, optional) – If True, excludes distribution of output layer. Default is True. If layer_names is informed, exclude_outputs is ignored.
  • epoch_start (int, optional) – First epoch to consider.
  • epoch_end (int, optional) – Last epoch to consider.
Returns:

weights_violins_plot – An instance of a LayerViolins object to make plots and animations.

Return type:

LayerViolins

decision_boundary
feature_space
get_training_metric(metric_name)[source]

Returns corresponding metric as reported by Keras at the end of each epoch.

Parameters:metric_name (String) – Metric to return values for.
Returns:metric – An array of shape (n_epochs, ) with the metric as reported by Keras at the end of each epoch. If the metric was not computed, returns an array of zeros with the same shape.
Return type:ndarray
gradients_std
gradients_violins
learning_rate
loss_and_metric
loss_histogram
predict_proba(epoch_start=0, epoch_end=-1)[source]

Generates class probability predictions for the inputs samples by epoch.

Parameters:
  • epoch_start (int, optional) – Initial epoch to return predicted probabilities for.
  • epoch_end (int, optional) – Final epoch to return predicted probabilities for.
Returns:

probas – An array of shape (n_epochs, n_samples, 2) of probabi- lity predictions.

Return type:

ndarray

probability_histogram
training_loss
weights_std
weights_violins
zvalues_violins

deepreplay.utils module

deepreplay.utils.make_batches(size, batch_size)[source]

Function extracted from Keras - check keras.engine.training_utils for the original version.

Returns a list of batch indices (tuples of indices). # Arguments

size: Integer, total size of the data to slice into batches. batch_size: Integer, batch size.
# Returns
A list of tuples of array indices.
deepreplay.utils.slice_arrays(arrays, start=None, stop=None)[source]

Function extracted from Keras - check keras.utils.generic_utils for the original version.

Slices an array or list of arrays. This takes an array-like, or a list of array-likes, and outputs:

  • arrays[start:stop] if arrays is an array-like
  • [x[start:stop] for x in arrays] if arrays is a list

Can also work on list/array of indices: _slice_arrays(x, indices) # Arguments

arrays: Single array or list of arrays. start: can be an integer index (start index)

or a list/array of indices
stop: integer (stop index); should be None if
start was a list.
# Returns
A slice of the array(s).

Module contents