Setup Module

Setup module for UI and dataclass management.

This module handles UI setup, connects UI elements to back-end functions, and defines essential dataclasses used throughout the application.

Functions

setup_ui(obj): Initialize and configure the main application window with panels, plots, and widgets.
connect_ui(obj, ui): Connect UI widgets and menu actions to their corresponding back-end functions.
setup_folders(): Create necessary application folders (‘state’ and ‘output’) if they do not exist.
setup_utility(): Initialize commonly used variables, color maps, plotting options, and map data.

Notes

Import this module at the start of the application to ensure proper UI initialization.
Uses PyQt6 for UI elements and VisPy for visualization canvases.
Defines dataclasses for managing state, plot options, and animation control.

class setup.Animate(start_time=0, duration=5.0, active=False, timer=<factory>, var='utc_sec')[source]

Bases: object

Manage animation state and control.

start_time

The start time of the animation in seconds.

Type:: float

duration

Duration of the animation in seconds.

Type:: float

active

Whether the animation is currently active.

Type:: bool

timer

VisPy timer controlling animation updates.

Type:: app.Timer

var

The variable to animate.

Type:: str

active: bool = False

duration: float = 5.0

start_time: float = 0

timer: Timer

update(**kwargs)[source]

Update animation attributes and start the animation.

Accepts keyword arguments corresponding to Animate attributes. If a valid attribute is provided, updates its value, sets the start time, marks the animation as active, and starts the timer.

Parameters:: **kwargs (dict) – Arbitrary keyword arguments matching Animate attribute names and their new values.
Return type:: None

var: str = 'utc_sec'

class setup.LoadingDialog(message)[source]

Bases: QDialog

Modal loading dialog that blocks user interaction.

Displays a simple message while a background task is running. The dialog is frameless, stays on top of other windows, and prevents user interaction until closed.

message

The message displayed in the dialog.

Type:: str

class setup.PlotOptions(cvar='seconds', cmap=<factory>, features=<factory>, map=<factory>)[source]

Bases: object

Manage plot options and visualization settings.

cvar

Variable used for coloring the plot.

Type:: str

cmap

Colormap used for the plot.

Type:: ListedColormap

features

Dictionary of features to display on the map.

Type:: dict

map

Geospatial map data for plotting.

Type:: gpd.GeoDataFrame

cmap: ListedColormap

cvar: str = 'seconds'

features: dict

map: GeoDataFrame

update(**kwargs)[source]

Update attributes of the PlotOptions instance.

Only valid attributes are updated.

Parameters:: **kwargs (dict) – Arbitrary keyword arguments matching PlotOptions attribute names and their new values.
Return type:: None

class setup.State(all=<factory>, stations=<factory>, plot=<factory>, plot_options=<factory>, replot=None, history=None, future=None, gsd=<factory>, gsd_mask=<factory>)[source]

Bases: object

Manage the application state, including data, plot options, and history.

all

Main dataset used for plotting and analysis.

Type:: pd.DataFrame

stations

List of station coordinates or identifiers.

Type:: list of tuple

plot

Current plot data.

Type:: pd.Series

plot_options

Visualization options for plotting.

Type:: PlotOptions

replot

Function to trigger a replot of the current state.

Type:: callable

history

Circular buffer storing past states for undo functionality.

Type:: deque

future

Circular buffer storing future states for redo functionality.

Type:: deque

_initialized

Internal flag indicating if post-initialization is complete.

Type:: bool

gsd

DataFrame containing ground strike data.

Type:: pd.DataFrame

gsd_mask

Mask applied to the ground strike data.

Type:: pd.Series

all: DataFrame

future: deque = None

gsd: DataFrame

gsd_mask: Series

history: deque = None

plot: Series

plot_options: PlotOptions

replot: callable = None

stations: list[tuple]

update(**kwargs)[source]

Update attributes of the state or plot options and trigger a replot.

Keyword arguments can correspond to any attribute of State or PlotOptions. If the lengths of all and plot match, the previous state is saved in history for undo functionality, and future is cleared.

Parameters:: **kwargs (dict) – Arbitrary keyword arguments matching State or PlotOptions attribute names and their new values.
Return type:: None

setup.connect_ui(obj, ui)[source]

Connect UI widgets and menus to backend functions.

Wires signals and slots for the main application, including menu actions, filter inputs, plot options, animation controls, and feature checkboxes. Ensures that user interactions trigger the appropriate updates in the application state and visualization.

Parameters:

obj (QMainWindow) – The main application window instance containing state, animation, and utility objects to be updated by UI actions.
ui (SimpleNamespace) – Namespace containing all UI widgets, layouts, menus, and visualization canvases created in the setup_ui function.

Return type:

None

setup.setup_folders()[source]

Create necessary application folders.

Ensures that the ‘state’ and ‘output’ directories exist for storing application state and output files. Creates them if they do not exist.

Return type:: None

setup.setup_ui(obj)[source]

Set up the main user interface for a QMainWindow.

Organizes the main window into a left panel with filters, map, color, and animation options, and a right panel with multiple visualization canvases arranged in a grid. Initializes scene canvases, markers, line plots, menus, and associated actions.

Parameters:: obj (QMainWindow) – The main window to which UI elements will be attached.
Returns:: Namespace containing references to all created widgets, layouts, and visualization canvases for easy access and manipulation.
Return type:: SimpleNamespace

setup.setup_utility()[source]

Set up utility data and return a container with commonly used variables.

This function initializes a SimpleNamespace containing: - Available color maps (cmaps) loaded from colorcet. - Variables for plotting and animation (cvars, avars). - Geospatial features loaded from parquet files. - Preloaded map data for states, counties, CWAs, and congressional districts.

Returns:: Namespace containing cmaps, cvars, avars, features, and maps.
Return type:: SimpleNamespace