rsqsim_api.visualisation.animation

Animation utilities for visualising earthquake sequences over time.

Provides AnimateSequence() for generating slip animations driven by a RsqSimCatalogue, AxesSequence for managing per-event plot visibility and fading, plot_axis_sequence() for driving the slider/animation loop, and write_animation_frame() / write_animation_frames() for parallel frame-by-frame rendering.

Classes

AxesSequence

Manage the visibility and fading of a time-ordered sequence of plots.

Functions

`AnimateSequence`(catalogue, fault_model[, ...])	Show an animation of a sequence of earthquake events over time.
`plot_axis_sequence`(frames, timestamps, all_plots, ...)	Drive the slider animation loop for a pre-rendered set of event plots.
`write_animation_frame`(frame_num, frame_time, ...[, ...])	Render a single animation frame and return the figure.
`write_animation_frames`(start_time, end_time, ...[, ...])	Write all animation frames to PNG files in parallel.
`calculate_alpha`(time_since_new, fading_increment)	Compute the opacity for an event that occurred `time_since_new` steps ago.
`calculate_fading_increment`(time_to_threshold, threshold)	Compute the fading increment so that alpha reaches `threshold` after `time_to_threshold` steps.

Module Contents

rsqsim_api.visualisation.animation.AnimateSequence(catalogue, fault_model, subduction_cmap='plasma', crustal_cmap='viridis', global_max_slip=10, global_max_sub_slip=40, step_size=1, interval=50, write=None, fps=20, file_format='gif', figsize=(9.6, 7.2), hillshading_intensity=0.0, bounds=None, pickled_background=None, fading_increment=2.0, plot_log=False, log_min=1.0, log_max=100.0, plot_subduction_cbar=True, plot_crustal_cbar=True, min_slip_value=None, plot_zeros=True, extra_sub_list=None, plot_cbars=False, write_frames=False, pickle_plots=None, load_pickle_plots=None, num_threads=4, **kwargs)[source]

Show an animation of a sequence of earthquake events over time.

Plots per-event slip distributions onto a NZ map background and animates them with a time slider. Supports pre-rendered pickled backgrounds and frame-by-frame writing via plot_axis_sequence().

Parameters:

catalogue (RsqSimCatalogue) – Catalogue of events to animate.
fault_model (RsqSimMultiFault) – Fault model providing patch geometry for each event.
subduction_cmap (str, optional) – Colourmap name for the subduction colourbar. Defaults to "plasma".
crustal_cmap (str, optional) – Colourmap name for the crustal colourbar. Defaults to "viridis".
global_max_slip (int, optional) – Maximum crustal slip (m) for the colour scale. Defaults to 10.
global_max_sub_slip (int, optional) – Maximum subduction slip (m) for the colour scale. Defaults to 40.
step_size (int, optional) – Year increment per animation frame. Defaults to 1.
interval (int, optional) – Delay between frames in milliseconds. Defaults to 50.
write (str or None, optional) – Output file path (without extension). If None, display interactively.
fps (int, optional) – Frames per second for the output file. Defaults to 20.
file_format (str, optional) – Output format: "gif", "mp4", "mov", or "avi". Defaults to "gif".
figsize (tuple, optional) – Figure size (width, height) in inches. Defaults to (9.6, 7.2).
hillshading_intensity (float, optional) – Hillshade overlay transparency (0–1). Defaults to 0.
bounds (tuple or None, optional) – (x_min, y_min, x_max, y_max) map extent.
pickled_background (str or None, optional) – Path to a pickled (fig, ax) background.
fading_increment (float, optional) – Fading divisor per time step. Defaults to 2.0.
plot_log (bool, optional) – If True, use a log colour scale. Defaults to False.
log_min (float, optional) – Lower bound for the log scale. Defaults to 1.
log_max (float, optional) – Upper bound for the log scale. Defaults to 100.
plot_subduction_cbar (bool, optional) – If True (default), show the subduction colourbar.
plot_crustal_cbar (bool, optional) – If True (default), show the crustal colourbar.
min_slip_value (float or None, optional) – Minimum slip to plot; patches below this are hidden.
plot_zeros (bool, optional) – If True (default), plot patches with zero slip.
extra_sub_list (list or None, optional) – Additional subduction patch numbers to highlight.
plot_cbars (bool, optional) – If True, plot per-event colourbars. Defaults to False.
write_frames (bool, optional) – If True, write individual PNG frames instead of animating. Defaults to False.
pickle_plots (str or None, optional) – Path to save pre-rendered plot pickles.
load_pickle_plots (str or None, optional) – Path to load pre-rendered plot pickles.
num_threads (int, optional) – Worker count for parallel frame rendering. Defaults to 4.

class rsqsim_api.visualisation.animation.AxesSequence(fig, timestamps, plots, coast_ax, fading_increment=2.0)[source]

Bases: object

Manage the visibility and fading of a time-ordered sequence of plots.

Tracks which event plots are currently on screen and progressively fades them out according to fading_increment as the animation advances.

Parameters:: fading_increment (float)

fig[source]

The figure containing all plots.

Type:: matplotlib.figure.Figure

timestamps[source]

Sorted year timestamps corresponding to each entry in plots.

Type:: list of int

plots[source]

Per-event lists of matplotlib artist objects.

Type:: list of list

coast_ax[source]

The main map axis.

Type:: matplotlib.axes.Axes

fading_increment[source]

Alpha divisor applied each time step. Defaults to 2.0.

Type:: float

on_screen[source]

Currently visible plot groups.

Type:: list

fig[source]

timestamps[source]

plots[source]

coast_ax[source]

on_screen = [][source]

fading_increment = 2.0[source]

set_plot(val)[source]

Advance the sequence to show all events at time val and fade older ones.

Parameters:: val (int) – Current slider year value.

fade(plot, index)[source]

Reduce the alpha of a plot group and hide it once fully transparent.

Parameters:

plot (list) – List of matplotlib artists for one event.
index (int) – Position of plot in on_screen; removed if invisible.

stop()[source]: Hide all on-screen plots and reset the sequence to the start.

show()[source]: Display the animation figure interactively.

rsqsim_api.visualisation.animation.plot_axis_sequence(frames, timestamps, all_plots, pickled_background, step_size=1, interval=50, write=None, write_frames=False, file_format='gif', fps=20, fading_increment=2.0, figsize=(9.6, 7.2), hillshading_intensity=0.0)[source]

Drive the slider animation loop for a pre-rendered set of event plots.

Attaches an AxesSequence to a time slider and either saves individual frames, saves an animation file, or shows the animation interactively.

Parameters:

frames (int or array-like) – Number of frames, or array of frame indices.
timestamps (list of int) – Year timestamps for each entry in all_plots.
all_plots (list of list) – Per-event lists of matplotlib artists.
pickled_background (tuple or None) – (fig, background_ax, coast_ax, slider_ax, year_ax) tuple loaded from a pickled background, or None to build one.
step_size (int, optional) – Year increment per frame. Defaults to 1.
interval (int, optional) – Delay between frames in milliseconds. Defaults to 50.
write (str or None, optional) – Output file path (without extension). If None, show interactively.
write_frames (bool, optional) – If True, write individual PNG frames to frames/. Defaults to False.
file_format (str, optional) – Output format: "gif", "mp4", "mov", or "avi". Defaults to "gif".
fps (int, optional) – Frames per second for the output file. Defaults to 20.
fading_increment (float, optional) – Alpha divisor per time step. Defaults to 2.0.
figsize (tuple, optional) – Figure size (width, height) in inches. Defaults to (9.6, 7.2).
hillshading_intensity (float, optional) – Hillshade transparency (0–1). Defaults to 0.

rsqsim_api.visualisation.animation.write_animation_frame(frame_num, frame_time, start_time, end_time, step_size, catalogue, fault_model, pickled_background, subduction_cmap='plasma', crustal_cmap='viridis', global_max_slip=10, global_max_sub_slip=40, bounds=None, fading_increment=2.0, time_to_threshold=10.0, plot_log=False, log_min=1.0, log_max=100.0, min_slip_value=None, plot_zeros=True, extra_sub_list=None, min_mw=None, decimals=1, subplot_name='main_figure')[source]

Render a single animation frame and return the figure.

Filters the catalogue to events within time_to_threshold years before frame_time, plots their slip distributions with faded alpha, and returns the figure for saving.

Parameters:

frame_num (int) – Frame index (used as the return key).
frame_time (float) – Current animation time in years.
start_time (float) – Animation start time in years.
end_time (float) – Animation end time in years.
step_size (int) – Year increment per frame.
catalogue (RsqSimCatalogue) – Event catalogue to filter.
fault_model (RsqSimMultiFault) – Fault model for plotting slip distributions.
pickled_background (str) – Path to a pickled (fig, ax) background file.
subduction_cmap (str, optional) – Colourmap for subduction slip. Defaults to "plasma".
crustal_cmap (str, optional) – Colourmap for crustal slip. Defaults to "viridis".
global_max_slip (int, optional) – Maximum crustal slip (m) for the colour scale. Defaults to 10.
global_max_sub_slip (int, optional) – Maximum subduction slip (m). Defaults to 40.
bounds (tuple or None, optional) – (x_min, y_min, x_max, y_max) map extent.
fading_increment (float, optional) – Base of the exponential alpha decay. Defaults to 2.0.
time_to_threshold (float, optional) – Look-back window in years. Defaults to 10.
plot_log (bool, optional) – If True, use a log colour scale. Defaults to False.
log_min (float, optional) – Lower bound for the log scale. Defaults to 1.
log_max (float, optional) – Upper bound for the log scale. Defaults to 100.
min_slip_value (float or None, optional) – Minimum slip to plot.
plot_zeros (bool, optional) – If True (default), plot zero-slip patches.
extra_sub_list (list or None, optional) – Extra subduction patch numbers to highlight.
min_mw (float or None, optional) – Minimum magnitude filter.
decimals (int, optional) – Decimal places for the year label. Defaults to 1.
subplot_name (str, optional) – Key for the main axes in the axes dict. Defaults to "main_figure".

Returns:

frame_num (int) – The input frame index.
fig (matplotlib.figure.Figure or None) – Rendered figure, or None if no events fall in the window.

rsqsim_api.visualisation.animation.write_animation_frames(start_time, end_time, step_size, catalogue, fault_model, pickled_background, subduction_cmap='plasma', crustal_cmap='viridis', global_max_slip=10, global_max_sub_slip=40, bounds=None, fading_increment=2.0, time_to_threshold=10.0, plot_log=False, log_min=1.0, log_max=100.0, min_slip_value=None, plot_zeros=False, extra_sub_list=None, min_mw=None, decimals=1, subplot_name='main_figure', num_threads_plot=4, frame_dir='frames')[source]

Write all animation frames to PNG files in parallel.

Iterates over time steps from start_time to end_time in step_size increments and submits each frame to a ThreadPoolExecutor. Frames without events are written separately after the parallel pass.

Parameters:

start_time (float) – Animation start time in years.
end_time (float) – Animation end time in years.
step_size (int) – Year increment per frame.
catalogue (RsqSimCatalogue) – Event catalogue.
fault_model (RsqSimMultiFault) – Fault model for slip distributions.
pickled_background (str) – Path to a pickled (fig, ax) background file.
subduction_cmap (str, optional) – Colourmap for subduction slip. Defaults to "plasma".
crustal_cmap (str, optional) – Colourmap for crustal slip. Defaults to "viridis".
global_max_slip (int, optional) – Maximum crustal slip (m). Defaults to 10.
global_max_sub_slip (int, optional) – Maximum subduction slip (m). Defaults to 40.
bounds (tuple or None, optional) – (x_min, y_min, x_max, y_max) map extent.
fading_increment (float, optional) – Base of the exponential alpha decay. Defaults to 2.0.
time_to_threshold (float, optional) – Look-back window in years. Defaults to 10.
plot_log (bool, optional) – If True, use a log colour scale. Defaults to False.
log_min (float, optional) – Lower bound for the log scale. Defaults to 1.
log_max (float, optional) – Upper bound for the log scale. Defaults to 100.
min_slip_value (float or None, optional) – Minimum slip to plot.
plot_zeros (bool, optional) – If False (default), skip zero-slip patches.
extra_sub_list (list or None, optional) – Extra subduction patch numbers to highlight.
min_mw (float or None, optional) – Minimum magnitude filter.
decimals (int, optional) – Decimal places for the year label. Defaults to 1.
subplot_name (str, optional) – Key for the main axes dict. Defaults to "main_figure".
num_threads_plot (int, optional) – Thread count for parallel rendering. Defaults to 4.
frame_dir (str, optional) – Directory for output PNG frames. Defaults to "frames".

rsqsim_api.visualisation.animation.calculate_alpha(time_since_new, fading_increment)[source]

Compute the opacity for an event that occurred time_since_new steps ago.

Parameters:

time_since_new (float) – Number of time steps since the event occurred.
fading_increment (float) – Base of the exponential decay; higher values fade faster.

Returns:

Alpha value clamped to [0, 1].

Return type:

float

rsqsim_api.visualisation.animation.calculate_fading_increment(time_to_threshold, threshold)[source]

Compute the fading increment so that alpha reaches threshold after time_to_threshold steps.

Parameters:

time_to_threshold (float) – Number of time steps until the event fades to threshold.
threshold (float) – Target alpha value after time_to_threshold steps (e.g. 0.01 for near-invisible).

Returns:

The fading increment base to pass to calculate_alpha().

Return type:

float