fovi.visualizer

class fovi.visualizer.Visualizer(trainer, out_base_dir=FIGS_DIR)

Bases: object

A class for visualizing model results and analysis.

This class provides methods to visualize various aspects of a model’s behavior and performance, including receptive fields, sampling grids, fixation patterns, and accuracy metrics. It handles saving visualizations to disk and displaying them interactively.

trainer

The trainer object containing the model and training configuration

model

The underlying model being visualized

out_base_dir

Base directory for saving visualization outputs

out_dir

Full output directory path for this specific model’s visualizations

__init__(trainer, out_base_dir=FIGS_DIR)

Initialize the Visualizer.

Parameters:

• trainer – Trainer object containing the model and configuration.

• out_base_dir (str, optional) – Base directory for output figures. Defaults to FIGS_DIR.

multi_fixation_accuracy(min_fixations=1, max_fixations=20, areas=[0.3, 0.5, 0.7, 0.9], norm_dist_from_center='original', save=True, show=True, max_batches=None, training=False, vmin=None, vmax=None, probe_layer=None, cache_accuracy=True, overwrite_accuracy=False)

Plot accuracy vs number of fixations for different crop areas.

Evaluates model performance as the number of fixations increases, for multiple crop area fractions.

Parameters:

• min_fixations (int, optional) – Minimum fixations to evaluate. Defaults to 1.

• max_fixations (int, optional) – Maximum fixations to evaluate. Defaults to 20.

• areas (list, optional) – List of crop area fractions. Defaults to [0.3, 0.5, 0.7, 0.9].

• norm_dist_from_center (str or float, optional) – Normalized distance constraint. Defaults to ‘original’.

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• max_batches (int, optional) – Maximum batches to process. Defaults to None.

• training (bool, optional) – Use training set instead of validation. Defaults to False.

• vmin (float, optional) – Minimum y-axis value. Defaults to None.

• vmax (float, optional) – Maximum y-axis value. Defaults to None.

• probe_layer (int, optional) – Specific probe layer to evaluate. Defaults to None.

• cache_accuracy (bool, optional) – Cache results to disk. Defaults to True.

• overwrite_accuracy (bool, optional) – Overwrite cached results. Defaults to False.

Returns:

DataFrame with columns (area, n_fixations, acc).

Return type:

pd.DataFrame

visualize_filters(save=True, show=True, **kwargs)

Visualize all filters from the first convolutional layer.

Creates a grid of scatter plots showing the learned filter weights on the KNN coordinate system.

Parameters:

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• **kwargs – Additional arguments passed to scatter plot.

Returns:

(fig, ax, base_fn) matplotlib figure, axes, and filename.

Return type:

tuple

visualize_filter(index=0, s=100, marker='s', axis_off=True, save=False, show=True)

Visualize a single filter from the first convolutional layer.

Parameters:

• index (int, optional) – Filter index to visualize. Defaults to 0.

• s (float, optional) – Marker size for scatter plot. Defaults to 100.

• marker (str, optional) – Marker style. Defaults to ‘s’ (square).

• axis_off (bool, optional) – Whether to hide axes. Defaults to True.

• save (bool, optional) – Whether to save the figure. Defaults to False.

• show (bool, optional) – Whether to display the figure. Defaults to True.

Returns:

(fig, ax) matplotlib figure and axes objects.

Return type:

tuple

visualize_filter_over_space(num_locs=100, filter=0, s=1, s_coords=1, save=True, show=True, coords_alpha=0.1, rf_alpha=0.5, seed=None, units=None, dpi=200)

Visualize how a filter’s weights vary across spatial positions.

Shows the filter applied at multiple locations across the visual field, revealing how the receptive field changes with eccentricity.

Parameters:

• num_locs (int, optional) – Number of locations to sample. Defaults to 100.

• filter (int, optional) – Filter index to visualize. Defaults to 0.

• s (float, optional) – Marker size for RF visualization. Defaults to 1.

• s_coords (float, optional) – Marker size for coordinates. Defaults to 1.

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• coords_alpha (float, optional) – Alpha for coordinate scatter. Defaults to 0.1.

• rf_alpha (float, optional) – Alpha for RF scatter. Defaults to 0.5.

• seed (int, optional) – Random seed for reproducibility. Defaults to None.

• units (list, optional) – Specific unit indices to visualize. Defaults to None.

• dpi (int, optional) – Figure resolution. Defaults to 200.

plot_coordinates(layer=None, save=True, show=True, **kwargs)

Plot the coordinate system at a specific layer.

Shows both Cartesian and cortical plotting coordinates side-by-side.

Parameters:

• layer (int, optional) – Layer index. If None, shows input coordinates. Defaults to None.

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• **kwargs – Additional arguments passed to scatter plot.

plot_spatial_rf_from_multi_layers(plot_layer=0, max_layer=5, r=0.2, theta=-np.pi / 2, s=3, plot_hex=False, hex_grid_size=40, save=True, show=True, vmax_percentile=40)

Plot receptive fields accumulated across multiple layers.

Shows how receptive fields grow from a single layer’s perspective as signals propagate through subsequent layers.

Parameters:

• plot_layer (int, optional) – Base layer for RF computation. Defaults to 0.

• max_layer (int, optional) – Maximum layer to include. Defaults to 5.

• r (float, optional) – Radial eccentricity of target unit. Defaults to 0.2.

• theta (float, optional) – Angular position of target unit. Defaults to -pi/2.

• s (float, optional) – Marker size. Defaults to 3.

• plot_hex (bool, optional) – Use hexbin instead of scatter. Defaults to False.

• hex_grid_size (int, optional) – Grid size for hexbin. Defaults to 40.

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• vmax_percentile (float, optional) – Percentile for color clipping. Defaults to 40.

plot_sampling_grids(save=True, show=True, alpha=0.5, alpha_layer0=0.1, layers=None)

Plot sampling grids at each layer of the network.

Shows how the coordinate system changes through the network, both in Cartesian and cortical coordinates.

Parameters:

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• alpha (float, optional) – Scatter alpha for layers > 0. Defaults to 0.5.

• alpha_layer0 (float, optional) – Scatter alpha for layer 0. Defaults to 0.1.

• layers (list, optional) – Specific layer indices to plot. Defaults to None (all).

plot_rf_diameters(max_layer=None, max_eccentricity_factor=4, save=True, show=True, dpi=100, cmap=plt.cm.cividis)

Plot receptive field diameter vs eccentricity for each layer.

Shows how RF size scales with eccentricity, a key property of foveated vision systems.

Parameters:

• max_layer (int, optional) – Maximum layer to plot. Defaults to None (all).

• max_eccentricity_factor (float, optional) – Factor to limit x-axis. Defaults to 4.

• save (bool, optional) – Whether to save the figure. Defaults to True.

• show (bool, optional) – Whether to display the figure. Defaults to True.

• dpi (int, optional) – Figure resolution. Defaults to 100.

• cmap (Colormap, optional) – Colormap for layers. Defaults to cividis.

print_all_functions()

Print all public methods available in this Visualizer.

fovi.visualizer.get_first_conv_weights(model)

Get the weights of the first convolutional layer in an arbitrary CNN.

Parameters:

model (nn.Module) – The CNN model.

Returns:

Weights of the first convolutional layer.

Return type:

torch.Tensor

fovi.visualizer.visualize_filters(weights)

Visualize convolutional filters from the first layer of a neural network.

This function creates a grid of images, each representing a single filter from the first convolutional layer. The filters are normalized to the range [0, 1] for better visibility.

Parameters:

weightstorch.Tensor

A tensor of shape (num_filters, channels, height, width) containing the weights of the first convolutional layer.

Returns:

figmatplotlib.figure.Figure

The figure object containing the visualized filters.

axmatplotlib.axes.Axes

The last axes object used in the grid (mainly for compatibility with existing return statement).

Notes:

The function assumes that the input weights are from the first convolutional layer and have a 3D structure (channels, height, width) for each filter.

fovi.visualizer.visualize_filters_knn(weights, coords, figsize=16, **kwargs)

Visualize convolutional filters from the first layer of a neural network.

This function creates a grid of images, each representing a single filter from the first convolutional layer. The filters are normalized to the range [0, 1] for better visibility.

Parameters:

weightstorch.Tensor

A tensor of shape (num_filters, channels, num_coords) containing the weights of the first convolutional layer.

coordstorch.Tensor

A tensor of shape (num_coords, 2) containing the coordinates of the points.

kwargs: dict

Additional keyword arguments for the scatter plot.

Returns:

figmatplotlib.figure.Figure

The figure object containing the visualized filters.

axmatplotlib.axes.Axes

The last axes object used in the grid (mainly for compatibility with existing return statement).

Notes:

The function assumes that the input weights are from the first convolutional layer and have a 3D structure (channels, height, width) for each filter.