aimbat.plot

def plot_matrix_image(
    iccs: ICCS, context: bool, all_seismograms: bool, return_fig: bool
) -> tuple["Figure", "Axes"] | None:
    """Plot the ICCS seismograms as a matrix image.

    The matrix is assembled from individual waveforms, with each row representing
    a different seismogram.

    Args:
        iccs: ICCS instance.
        context: If True, plot waveforms with extra context around the taper window.
        all_seismograms: If True, include deselected seismograms in the plot.
        return_fig: If True, return the figure and axes objects instead of showing the plot.

    Returns:
        A tuple of (Figure, Axes) if return_fig is True, otherwise None.
    """

    logger.info("Plotting matrix image.")

    return _plot_matrix_image(iccs, context, all_seismograms, return_fig=return_fig)  # type: ignore[call-overload]

def plot_seismograms(
    session: Session, plot_for: AimbatEvent | AimbatStation, return_fig: bool
) -> tuple[plt.Figure, plt.Axes] | None:
    """Plot all seismograms for a particular event or station.

    Args:
        session: Database session.
        plot_for: What to plot the seismograms for (Event or Station).
        return_fig: Whether to return the figure and axes objects instead of showing the plot.

    Returns:
        figure and axes objects if return_fig is True, otherwise None.

    Raises:
        RuntimeError: If no seismograms are found for the event or station.

    Note:
        The seismograms use the filter settings specified in the event parameters.
    """
    logger.info(f"Plotting seismograms for {type(plot_for).__name__}: {plot_for.id}.")

    fig, ax = _plot_seis(plot_for, session)
    _add_scroll_pan(ax)

    if return_fig:
        return fig, ax
    plt.show()
    return None

def plot_stack(
    iccs: ICCS, context: bool, all_seismograms: bool, return_fig: bool
) -> tuple["Figure", "Axes"] | None:
    """Plot the ICCS stack.

    Args:
        iccs: ICCS instance.
        context: If True, plot waveforms with extra context around the taper window.
        all_seismograms: If True, include deselected seismograms in the plot.
        return_fig: If True, return the figure and axes objects instead of showing the plot.

    Returns:
        A tuple of (Figure, Axes) if return_fig is True, otherwise None.
    """

    logger.info("Plotting ICCS stack.")
    return _plot_stack(iccs, context, all_seismograms, return_fig=return_fig)  # type: ignore[call-overload]

def update_min_cc(
    session: Session,
    event: AimbatEvent,
    iccs: ICCS,
    context: bool,
    all_seismograms: bool,
    return_fig: bool,
) -> tuple["Figure", "Axes", Any] | None:
    """Update the minimum cross-correlation threshold for the given event.

    Args:
        session: Database session.
        event: AimbatEvent.
        iccs: ICCS instance.
        context: If True, plot waveforms with extra context around the taper window.
        all_seismograms: If True, include deselected seismograms in the plot.
        return_fig: If True, return the figure, axes and widget objects instead of showing the plot.

    Returns:
        A tuple of (Figure, Axes, widgets) if return_fig is True, otherwise None.
    """

    logger.info(f"Updating minimum cross-correlation threshold for event {event.id}.")

    result = _update_min_cc(iccs, context, all_seismograms, return_fig=return_fig)  # type: ignore[call-overload]

    if not return_fig:
        logger.debug(
            f"Saving new minimum cross-correlation threshold for event {event.id}: {iccs.min_cc}"
        )
        set_event_parameter(
            session, event.id, EventParameter.MIN_CC, float(iccs.min_cc)
        )
        return None

    logger.warning(_RETURN_FIG_WARNING)
    return result

def update_pick(
    session: Session,
    iccs: ICCS,
    context: bool,
    all_seismograms: bool,
    use_matrix_image: bool,
    return_fig: bool,
) -> tuple["Figure", "Axes", Any] | None:
    """Update the phase pick (t1) for an event.

    Args:
        session: Database session.
        iccs: ICCS instance.
        context: If True, plot waveforms with extra context around the taper window.
        all_seismograms: If True, include deselected seismograms in the plot.
        use_matrix_image: If True, pick from the matrix image; otherwise pick from the stack plot.
        return_fig: If True, return the figure, axes and widget objects instead of showing the plot.

    Returns:
        A tuple of (Figure, Axes, widgets) if return_fig is True, otherwise None.
    """

    logger.info("Updating phase pick.")

    result = _update_pick(  # type: ignore[call-overload]
        iccs, context, all_seismograms, use_matrix_image, return_fig=return_fig
    )

    if not return_fig:
        _write_back_seismograms(session, iccs)
        return None

    logger.warning(_RETURN_FIG_WARNING)
    return result

def update_timewindow(
    session: Session,
    event: AimbatEvent,
    iccs: ICCS,
    context: bool,
    all_seismograms: bool,
    use_matrix_image: bool,
    return_fig: bool,
) -> tuple["Figure", "Axes", Any] | None:
    """Update the cross-correlation time window for the given event.

    Args:
        session: Database session.
        event: AimbatEvent.
        iccs: ICCS instance.
        context: If True, plot waveforms with extra context around the taper window.
        all_seismograms: If True, include deselected seismograms in the plot.
        use_matrix_image: If True, pick from the matrix image; otherwise pick from the stack plot.
        return_fig: If True, return the figure, axes and widget objects instead of showing the plot.

    Returns:
        A tuple of (Figure, Axes, widgets) if return_fig is True, otherwise None.
    """

    logger.info(f"Updating time window for event {event.id}.")

    result = _update_timewindow(  # type: ignore[call-overload]
        iccs, context, all_seismograms, use_matrix_image, return_fig=return_fig
    )

    if not return_fig:
        logger.debug(
            f"Saving new time window for event {event.id}: "
            f"pre={iccs.window_pre}, post={iccs.window_post}"
        )
        set_event_parameter(
            session, event.id, EventParameter.WINDOW_PRE, iccs.window_pre
        )
        set_event_parameter(
            session, event.id, EventParameter.WINDOW_POST, iccs.window_post
        )
        return None

    logger.warning(_RETURN_FIG_WARNING)
    return result