cell_attn.model_evaluation_utils

Functions

`load_model`(stdir)	Load a deep attention network model.
`load_data`(datadir[, experiments, batch_size])	Loads trajectory input and label data in the form of a DataLoader.
`plot_losses`(stdir[, w])	Plot the test and training loss from the training process of a model. Designed to
`plot_losses_per_epoch`(stdir[, w])	Plots the test loss after each epoch. Designed to
`ewma`(x, w)	Computes an exponential weighted moving average of a time series. Called by plot_losses().
`plot_attention_heatmap`(model[, datadir, batch_size, ...])	Plots an attention heatmap for a given trained deep attention network and DataLoader. Designed to
`plot_weight_function`(model, xlim, ylim[, palette, ...])	Plot the trained weight function of a deep attention network. Designed to
`plot_attraction_repulsion_heatmap`(model[, datadir, ...])	Plots an attraction-repulsion heatmap for a given trained deep attention network and DataLoader. Designed to
`plot_alignment_heatmap`(model[, datadir, batch_size, ...])	Plots an alignment heatmap for a given trained deep attention network and dataloader. Designed to
`weight_distance_plot`(model, dataloader[, ...])	Plots normalised weight vs distance for one batch of a given DataLoader. Designed to
`radial_weight_plot`(model, rlim[, r_meshsize, ...])	Plots radially averaged weight vs distance for the weight function of a deep atttention network.

Module Contents

cell_attn.model_evaluation_utils.load_model(stdir: str)

Load a deep attention network model.

Parameters

stdir: str: Directory where the deep attention network is stored, state_dict should be stored at stdir/model.pth.

Returns

model: model_definition_utils.velocity_predictor: Deep attention network model.

cell_attn.model_evaluation_utils.load_data(datadir: str, experiments: list[str] | None = None, batch_size: int = 20000)

Loads trajectory input and label data in the form of a DataLoader.

Parameters

datadir: str: Directory where input and label data are stored, within this directory should be a set of subdirectories, one for each experiment, each containing a input data file called input_data.npy, and label files called labels.npy, as created by create_data_from_trajectories().
experiments: list[str] | None, default=None: Specify which experiments to take data from for the dataset.
batch_size: int, default=20000: Batch size of the DataLoader.

Returns

dataloader: torch.utils.data.DataLoader: DataLoader for trajectory data.

cell_attn.model_evaluation_utils.plot_losses(stdir: str, w: float = 0.01)

Plot the test and training loss from the training process of a model. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

stdir: str: Directory where the model (and thus loss files) are stored.
w: float, default=0.01: Parameter controlling the degree of smoothing in the plots. A lower w leads to a smoother average. See ewma() for details.

cell_attn.model_evaluation_utils.plot_losses_per_epoch(stdir: str, w: float = 0.01)

Plots the test loss after each epoch. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

stdir: str: Directory where the model (and thus loss files) are stored.
w: float, default=0.01: Parameter controlling the degree of smoothing in the plots. A lower w leads to a smoother average. See ewma() for details.

cell_attn.model_evaluation_utils.ewma(x, w: float)

Computes an exponential weighted moving average of a time series. Called by plot_losses().

Parameters

x: 1d array: Time series data.
w: float: Weight to use in ewma calculation. Lower w leads to smoother average.

Returns

x_smoothed: list: A smoothed version of x.

cell_attn.model_evaluation_utils.plot_attention_heatmap(model, datadir: str | None = None, batch_size: int = 20000, dataloader: torch.utils.data.DataLoader | None = None, experiments: list[str] | None = None, point_size: float = 1, min_weight: float | None = None, max_weight: float | None = None, palette: str = 'gnuplot', colorbar_ndp: int | None = None)

Plots an attention heatmap for a given trained deep attention network and DataLoader. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

model: model_definition_utils.velocity_predictor: Trained deep attention network, loaded in using load_model().
datadir: str, default=None: Directory containing input data. Should have subdirectories for each experiment.
batch_size: int, default=20000: How many individual focal & neighbour cell plots to superimpose.
dataloader: torch.utils.data.DataLoader | None, default=None: Dataloader to draw data from for plotting. Specifying this overrides datadir, experiments, and batch_size. Negates the need to construct a DataLoader from datadir.
experiments: list[str] | None, default=None: If constructing a DataLoader, specify which experiments to take data from.
point_size: float, default=1: Size of points in the AHM. Passed to s in seaborn.scatterplot().
min_weight: float | None, default=None: Specify the lower weight to normalise the colour palette to. If None, will bet set to the 1st percentile of the computed weights.
max_weight: float | None, default=None: Specify the upper weight to normalise the colour palette to. If None, will be set to the 99th percentile of the computed weights.
palette: str, default=’gnuplot’: Specify which matplotlib colour palette to use.
colorbar_ndp: int | None, default=None: Number of decimal places to round color bar labels to.

cell_attn.model_evaluation_utils.plot_weight_function(model, xlim: tuple[float, float], ylim: tuple[float, float], palette: str = 'gnuplot', cutoff_radius: float = None, show_center: bool = True, min_weight: float = 0, max_weight: float | None = None, colorbar_ndp: int | None = None)

Plot the trained weight function of a deep attention network. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

model: model_definition_utils.velocity_predictor: Trained deep attention network, loaded in using load_model().
xlim: tuple[float,float]: Limits for horizontal axis of plot.
xlim: tuple[float,float]: Limits for vertical axis of plot.
pallete: str, default=’gnuplot’: Name of matplotlib colour palette to use.
cutoff_radius: float, default=None: If show_center=False, grey out all points inside this radius.
show_center: bool, default=True: Specify whether to plot points near the origin. If False, grey out all points inside the cutoff_radius.
min_weight: float, default=0: Snap all weights below min_weight to min_weight.
colorbar_ndp: int | None, default=None: Number of decimal places to round colour bar labels to.

cell_attn.model_evaluation_utils.plot_attraction_repulsion_heatmap(model, datadir: str | None = None, batch_size: int = 20000, dataloader: torch.utils.data.DataLoader | None = None, experiments: list[str] | None = None, prediction_timestep: int = 1, point_size: float = 1, palette: str = 'seismic_r', colorbar_ndp: int = None)

Plots an attraction-repulsion heatmap for a given trained deep attention network and DataLoader. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

model: model_definition_utils.velocity_predictor: Trained deep attention network, loaded in using load_model().
datadir: str, default=None: Directory containing input data. Should have subdirectories for each experiment.
batch_size: int, default=20000: How many individual focal & neighbour cell plots to superimpose.
dataloader: torch.utils.data.DataLoader | None, default=None: DataLoader to draw data from for plotting. Specifying this overrides datadir, experiments, and batch_size. Negates the need to construct a DataLoader from datadir.
experiments: list[str] | None, default=None: Specify which experiments to take data from for the DataLoader, if constructing one.
prediction_timestep: int, default=1: Length of the interval over which the deep attention network was trained to predict cell displacement over.
point_size: float, default=1: Size of points in the ARHM. Passed to s in seaborn.scatterplot().
palette: str, default=’seismic_r’: Specify which matplotlib colour palette to use.
colorbar_ndp: int | None, default=None: Number of decimal places to round colour bar labels to.

cell_attn.model_evaluation_utils.plot_alignment_heatmap(model, datadir: str | None = None, batch_size: int = 20000, dataloader: torch.utils.data.DataLoader | None = None, experiments: list[str] | None = None, point_size: float = 1, palette: str = 'seismic_r', colorbar_ndp: int | None = None)

Plots an alignment heatmap for a given trained deep attention network and dataloader. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

model: model_definition_utils.velocity_predictor: Trained deep attention network, loaded in using load_model().
datadir: str, default=None: Directory containing input data. Should have subdirectories for each experiment.
batch_size: int, default=20000: How many individual focal & neighbour cell plots to superimpose.
dataloader: torch.utils.data.DataLoader | None, default=None: DataLoader to draw data from for plotting. Specifying this overrides datadir, experiments, and batch_size. Negates the need to construct a DataLoader from datadir.
experiments: list[str] | None, default=None: Specify which experiments to take data from for the dataset, if loading in a dataset from datadir.
point_size: float, default=1: Size of points in the ARHM. Passed to s in seaborn.scatterplot().
palette: str, default=’seismic_r’: Specify which matplotlib colour palette to use.
colorbar_ndp: int | None, default=None: Number of decimal places to round colour bar labels to.

cell_attn.model_evaluation_utils.weight_distance_plot(model, dataloader: torch.utils.data.DataLoader, plot_averages: bool = True, avg_xlim: tuple[float, float] = None, n_bins: int = 100, attraction_scores: bool = False, point_size: float = 0.1, prediction_timestep: int = 1)

Plots normalised weight vs distance for one batch of a given DataLoader. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

model: model_definition_utils.velocity_predictor: Trained deep attention network, loaded in using load_model().
dataloader: torch.data.DataLoader: Cell trajectory DataLoader.
plot_averages: bool, default=True: If True, will plot average weight against distance from neighbour cells.
avg_xlim: tuple[float,float] | None, default=None: Specify distance limits to plot average weight between.
n_bins: int, default=100: Number of points to plot average weight at.
attraction_scores: bool, default=False: If True, colour points by attraction score.
point_size: float, default=0.1: Size of points. Passed to s in seaborn.scatterplot.
prediction_timestep: int, default=1: Timestep over which the deep attention network is trained to predict over.

cell_attn.model_evaluation_utils.radial_weight_plot(model, rlim: tuple[float, float], r_meshsize: int = 100, theta_meshsize: int = 100)

Plots radially averaged weight vs distance for the weight function of a deep atttention network. Designed to be called with an active matplotlib.pyplot.figure.

Parameters

model: model_definition_utils.velocity_predictor: Trained deep attention network, loaded in using load_model().
rlim: tuple[float,float]: Limits to compute average weight between.
r_meshsize: int, default=100: Number of points to compute average weight at.
theta_meshsize: int, default=100: Number of angles to use when computing average weight.