rsqsim_api.visualisation.animation ================================== .. py:module:: rsqsim_api.visualisation.animation .. autoapi-nested-parse:: Animation utilities for visualising earthquake sequences over time. Provides :func:`AnimateSequence` for generating slip animations driven by a :class:`~rsqsim_api.catalogue.catalogue.RsqSimCatalogue`, :class:`AxesSequence` for managing per-event plot visibility and fading, :func:`plot_axis_sequence` for driving the slider/animation loop, and :func:`write_animation_frame` / :func:`write_animation_frames` for parallel frame-by-frame rendering. Classes ------- .. autoapisummary:: rsqsim_api.visualisation.animation.AxesSequence Functions --------- .. autoapisummary:: rsqsim_api.visualisation.animation.AnimateSequence rsqsim_api.visualisation.animation.plot_axis_sequence rsqsim_api.visualisation.animation.write_animation_frame rsqsim_api.visualisation.animation.write_animation_frames rsqsim_api.visualisation.animation.calculate_alpha rsqsim_api.visualisation.animation.calculate_fading_increment Module Contents --------------- .. py:function:: 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) 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 :func:`plot_axis_sequence`. :param catalogue: Catalogue of events to animate. :type catalogue: RsqSimCatalogue :param fault_model: Fault model providing patch geometry for each event. :type fault_model: RsqSimMultiFault :param subduction_cmap: Colourmap name for the subduction colourbar. Defaults to ``"plasma"``. :type subduction_cmap: str, optional :param crustal_cmap: Colourmap name for the crustal colourbar. Defaults to ``"viridis"``. :type crustal_cmap: str, optional :param global_max_slip: Maximum crustal slip (m) for the colour scale. Defaults to 10. :type global_max_slip: int, optional :param global_max_sub_slip: Maximum subduction slip (m) for the colour scale. Defaults to 40. :type global_max_sub_slip: int, optional :param step_size: Year increment per animation frame. Defaults to 1. :type step_size: int, optional :param interval: Delay between frames in milliseconds. Defaults to 50. :type interval: int, optional :param write: Output file path (without extension). If ``None``, display interactively. :type write: str or None, optional :param fps: Frames per second for the output file. Defaults to 20. :type fps: int, optional :param file_format: Output format: ``"gif"``, ``"mp4"``, ``"mov"``, or ``"avi"``. Defaults to ``"gif"``. :type file_format: str, optional :param figsize: Figure size ``(width, height)`` in inches. Defaults to ``(9.6, 7.2)``. :type figsize: tuple, optional :param hillshading_intensity: Hillshade overlay transparency (0–1). Defaults to 0. :type hillshading_intensity: float, optional :param bounds: ``(x_min, y_min, x_max, y_max)`` map extent. :type bounds: tuple or None, optional :param pickled_background: Path to a pickled ``(fig, ax)`` background. :type pickled_background: str or None, optional :param fading_increment: Fading divisor per time step. Defaults to 2.0. :type fading_increment: float, optional :param plot_log: If ``True``, use a log colour scale. Defaults to ``False``. :type plot_log: bool, optional :param log_min: Lower bound for the log scale. Defaults to 1. :type log_min: float, optional :param log_max: Upper bound for the log scale. Defaults to 100. :type log_max: float, optional :param plot_subduction_cbar: If ``True`` (default), show the subduction colourbar. :type plot_subduction_cbar: bool, optional :param plot_crustal_cbar: If ``True`` (default), show the crustal colourbar. :type plot_crustal_cbar: bool, optional :param min_slip_value: Minimum slip to plot; patches below this are hidden. :type min_slip_value: float or None, optional :param plot_zeros: If ``True`` (default), plot patches with zero slip. :type plot_zeros: bool, optional :param extra_sub_list: Additional subduction patch numbers to highlight. :type extra_sub_list: list or None, optional :param plot_cbars: If ``True``, plot per-event colourbars. Defaults to ``False``. :type plot_cbars: bool, optional :param write_frames: If ``True``, write individual PNG frames instead of animating. Defaults to ``False``. :type write_frames: bool, optional :param pickle_plots: Path to save pre-rendered plot pickles. :type pickle_plots: str or None, optional :param load_pickle_plots: Path to load pre-rendered plot pickles. :type load_pickle_plots: str or None, optional :param num_threads: Worker count for parallel frame rendering. Defaults to 4. :type num_threads: int, optional .. py:class:: AxesSequence(fig, timestamps, plots, coast_ax, fading_increment = 2.0) Bases: :py:obj:`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. .. attribute:: fig The figure containing all plots. :type: matplotlib.figure.Figure .. attribute:: timestamps Sorted year timestamps corresponding to each entry in ``plots``. :type: list of int .. attribute:: plots Per-event lists of matplotlib artist objects. :type: list of list .. attribute:: coast_ax The main map axis. :type: matplotlib.axes.Axes .. attribute:: fading_increment Alpha divisor applied each time step. Defaults to 2.0. :type: float .. attribute:: on_screen Currently visible plot groups. :type: list .. py:attribute:: fig .. py:attribute:: timestamps .. py:attribute:: plots .. py:attribute:: coast_ax .. py:attribute:: on_screen :value: [] .. py:attribute:: fading_increment :value: 2.0 .. py:method:: set_plot(val) Advance the sequence to show all events at time ``val`` and fade older ones. :param val: Current slider year value. :type val: int .. py:method:: fade(plot, index) Reduce the alpha of a plot group and hide it once fully transparent. :param plot: List of matplotlib artists for one event. :type plot: list :param index: Position of ``plot`` in :attr:`on_screen`; removed if invisible. :type index: int .. py:method:: stop() Hide all on-screen plots and reset the sequence to the start. .. py:method:: show() Display the animation figure interactively. .. py:function:: 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) Drive the slider animation loop for a pre-rendered set of event plots. Attaches an :class:`AxesSequence` to a time slider and either saves individual frames, saves an animation file, or shows the animation interactively. :param frames: Number of frames, or array of frame indices. :type frames: int or array-like :param timestamps: Year timestamps for each entry in ``all_plots``. :type timestamps: list of int :param all_plots: Per-event lists of matplotlib artists. :type all_plots: list of list :param pickled_background: ``(fig, background_ax, coast_ax, slider_ax, year_ax)`` tuple loaded from a pickled background, or ``None`` to build one. :type pickled_background: tuple or None :param step_size: Year increment per frame. Defaults to 1. :type step_size: int, optional :param interval: Delay between frames in milliseconds. Defaults to 50. :type interval: int, optional :param write: Output file path (without extension). If ``None``, show interactively. :type write: str or None, optional :param write_frames: If ``True``, write individual PNG frames to ``frames/``. Defaults to ``False``. :type write_frames: bool, optional :param file_format: Output format: ``"gif"``, ``"mp4"``, ``"mov"``, or ``"avi"``. Defaults to ``"gif"``. :type file_format: str, optional :param fps: Frames per second for the output file. Defaults to 20. :type fps: int, optional :param fading_increment: Alpha divisor per time step. Defaults to 2.0. :type fading_increment: float, optional :param figsize: Figure size ``(width, height)`` in inches. Defaults to ``(9.6, 7.2)``. :type figsize: tuple, optional :param hillshading_intensity: Hillshade transparency (0–1). Defaults to 0. :type hillshading_intensity: float, optional .. py:function:: 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') 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. :param frame_num: Frame index (used as the return key). :type frame_num: int :param frame_time: Current animation time in years. :type frame_time: float :param start_time: Animation start time in years. :type start_time: float :param end_time: Animation end time in years. :type end_time: float :param step_size: Year increment per frame. :type step_size: int :param catalogue: Event catalogue to filter. :type catalogue: RsqSimCatalogue :param fault_model: Fault model for plotting slip distributions. :type fault_model: RsqSimMultiFault :param pickled_background: Path to a pickled ``(fig, ax)`` background file. :type pickled_background: str :param subduction_cmap: Colourmap for subduction slip. Defaults to ``"plasma"``. :type subduction_cmap: str, optional :param crustal_cmap: Colourmap for crustal slip. Defaults to ``"viridis"``. :type crustal_cmap: str, optional :param global_max_slip: Maximum crustal slip (m) for the colour scale. Defaults to 10. :type global_max_slip: int, optional :param global_max_sub_slip: Maximum subduction slip (m). Defaults to 40. :type global_max_sub_slip: int, optional :param bounds: ``(x_min, y_min, x_max, y_max)`` map extent. :type bounds: tuple or None, optional :param fading_increment: Base of the exponential alpha decay. Defaults to 2.0. :type fading_increment: float, optional :param time_to_threshold: Look-back window in years. Defaults to 10. :type time_to_threshold: float, optional :param plot_log: If ``True``, use a log colour scale. Defaults to ``False``. :type plot_log: bool, optional :param log_min: Lower bound for the log scale. Defaults to 1. :type log_min: float, optional :param log_max: Upper bound for the log scale. Defaults to 100. :type log_max: float, optional :param min_slip_value: Minimum slip to plot. :type min_slip_value: float or None, optional :param plot_zeros: If ``True`` (default), plot zero-slip patches. :type plot_zeros: bool, optional :param extra_sub_list: Extra subduction patch numbers to highlight. :type extra_sub_list: list or None, optional :param min_mw: Minimum magnitude filter. :type min_mw: float or None, optional :param decimals: Decimal places for the year label. Defaults to 1. :type decimals: int, optional :param subplot_name: Key for the main axes in the ``axes`` dict. Defaults to ``"main_figure"``. :type subplot_name: str, optional :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. .. py:function:: 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') 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. :param start_time: Animation start time in years. :type start_time: float :param end_time: Animation end time in years. :type end_time: float :param step_size: Year increment per frame. :type step_size: int :param catalogue: Event catalogue. :type catalogue: RsqSimCatalogue :param fault_model: Fault model for slip distributions. :type fault_model: RsqSimMultiFault :param pickled_background: Path to a pickled ``(fig, ax)`` background file. :type pickled_background: str :param subduction_cmap: Colourmap for subduction slip. Defaults to ``"plasma"``. :type subduction_cmap: str, optional :param crustal_cmap: Colourmap for crustal slip. Defaults to ``"viridis"``. :type crustal_cmap: str, optional :param global_max_slip: Maximum crustal slip (m). Defaults to 10. :type global_max_slip: int, optional :param global_max_sub_slip: Maximum subduction slip (m). Defaults to 40. :type global_max_sub_slip: int, optional :param bounds: ``(x_min, y_min, x_max, y_max)`` map extent. :type bounds: tuple or None, optional :param fading_increment: Base of the exponential alpha decay. Defaults to 2.0. :type fading_increment: float, optional :param time_to_threshold: Look-back window in years. Defaults to 10. :type time_to_threshold: float, optional :param plot_log: If ``True``, use a log colour scale. Defaults to ``False``. :type plot_log: bool, optional :param log_min: Lower bound for the log scale. Defaults to 1. :type log_min: float, optional :param log_max: Upper bound for the log scale. Defaults to 100. :type log_max: float, optional :param min_slip_value: Minimum slip to plot. :type min_slip_value: float or None, optional :param plot_zeros: If ``False`` (default), skip zero-slip patches. :type plot_zeros: bool, optional :param extra_sub_list: Extra subduction patch numbers to highlight. :type extra_sub_list: list or None, optional :param min_mw: Minimum magnitude filter. :type min_mw: float or None, optional :param decimals: Decimal places for the year label. Defaults to 1. :type decimals: int, optional :param subplot_name: Key for the main axes dict. Defaults to ``"main_figure"``. :type subplot_name: str, optional :param num_threads_plot: Thread count for parallel rendering. Defaults to 4. :type num_threads_plot: int, optional :param frame_dir: Directory for output PNG frames. Defaults to ``"frames"``. :type frame_dir: str, optional .. py:function:: calculate_alpha(time_since_new, fading_increment) Compute the opacity for an event that occurred ``time_since_new`` steps ago. :param time_since_new: Number of time steps since the event occurred. :type time_since_new: float :param fading_increment: Base of the exponential decay; higher values fade faster. :type fading_increment: float :returns: Alpha value clamped to ``[0, 1]``. :rtype: float .. py:function:: calculate_fading_increment(time_to_threshold, threshold) Compute the fading increment so that alpha reaches ``threshold`` after ``time_to_threshold`` steps. :param time_to_threshold: Number of time steps until the event fades to ``threshold``. :type time_to_threshold: float :param threshold: Target alpha value after ``time_to_threshold`` steps (e.g. 0.01 for near-invisible). :type threshold: float :returns: The fading increment base to pass to :func:`calculate_alpha`. :rtype: float