ClusteringView

class ClusteringView()

Bases: MetaView

Subclass of MetaView for displaying and interacting with clustering analysis.

Handles plotting, user input, and signal exchanges.

Public Methods

ClusteringView.get_current_view() → str

Abstract method to get the name of the current view.

Subclasses must override this to return the current view name.

Returns:

The name of the view currently displayed.

Return type:

str

Raises:

NotImplementedError – Always, unless overridden by a subclass.

ClusteringView.get_save_filename() → str

Opens a file dialog to select a location for saving a CSV file.

Returns:

The selected file path.

Return type:

str

ClusteringView.get_walkthrough_steps() → List[Tuple[str, str, str, Callable[[], QWidget | List[QWidget]]]]

Abstract method to retrieve the walkthrough steps for the current view.

Subclasses must override this to return a list of walkthrough steps, each a (title, description, view name, widget getter) tuple.

Returns:

The ordered walkthrough steps for this view.

Return type:

List[WalkthroughStep]

Raises:

NotImplementedError – Always, unless overridden by a subclass.

ClusteringView.handle_parameter_change(submodel_name: str, action_name: str, args: tuple) → None

Handles actions triggered by the control panel.

Parameters:

  • submodel_name (str) – Name of the submodel.

  • action_name (str) – Action to perform (e.g., ‘merge_clusters’).

  • args (tuple) – Parameters passed with the action.

ClusteringView.notify_plugin_state_changed(metaclass: str, plugin_key: str, reason: str) → None

Called when some other plugin instance’s state changed elsewhere in the app. Refreshes this tab’s column list only when the change concerns a MetaDatabaseLoader’s columns and the loader that changed is the one currently selected here; any other metaclass, reason, or a loader that isn’t currently selected in this tab is ignored.

Parameters:

  • metaclass (str) – The metaclass of the plugin instance whose state changed.

  • plugin_key (str) – The unique key identifying the plugin instance that changed.

  • reason (str) – A short string identifying what kind of change occurred.

Returns:

None

Return type:

None

ClusteringView.on_cluster_column_checked(loader: str, existing_table: str | None) → None

Confirm an overwrite if needed, then ask the Controller to commit.

The confirmation stays in the View - it is a modal dialog - which is why this is two round trips rather than one. existing_table being None means there is nothing to overwrite and the commit proceeds without asking.

Parameters:

  • loader (str) – Name or ID of the database loader plugin.

  • existing_table (Optional[str]) – The table already holding cluster columns, or None.

Returns:

None

Return type:

None

ClusteringView.on_clusters_committed(loader: str, status: bool) → None

Refresh this tab and tell the rest of the app, once the write has landed.

Parameters:

  • loader (str) – Name or ID of the database loader plugin.

  • status (bool) – True if the write succeeded.

Returns:

None

Return type:

None

ClusteringView.on_metadata_loaded(config: Dict[str, Any], loader: str, plot_data: DataFrame) → None

Parse the settings dialog, then ask for the rows to be clustered.

The second half of _load_metadata_and_request_clustering(). The rows are a parameter now rather than something read back off self.plot_data, so the clear-before-emit guard that used to protect that read is gone with the read.

The filtering itself is ClusteringModel.build_clustering_frame()’s. What stays here is reading the settings dialog - the per-column flags and the method parameters are strings the user typed, so a bad one is this form’s problem to report.

Parameters:

  • config (Dict[str, Any]) – Dictionary with selected columns and method configuration.

  • loader (str) – Identifier of the loader plugin.

  • plot_data (pd.DataFrame) – the rows the Controller loaded

Returns:

None

Return type:

None

Raises:

ValueError – If the clustering method or its parameters are invalid or missing.

ClusteringView.set_clustering_result(data: DataFrame, labels: Sequence[Any] | ndarray, confidence: Sequence[Any] | ndarray) → None

Receive the Model’s clustering result and plot it.

The other half of cluster_requested: the clustering is ClusteringModel’s, so everything that depends on its result is drawn from here rather than inline after the call.

Parameters:

  • data (pd.DataFrame) – the normalized frame the Model clustered

  • labels (Union[Sequence[Any], np.ndarray]) – cluster label per row

  • confidence (Union[Sequence[Any], np.ndarray]) – cluster confidence per row

Returns:

None

Return type:

None

ClusteringView.set_query(query: str, table_name: str) → None

Sets the SQL query and target table name.

Parameters:

  • query (str) – SQL query string.

  • table_name (str) – Name of the target table.

ClusteringView.update_available_columns(loader: str) → None

Ask the Controller for the column names the given loader offers.

The answer arrives at update_column_names. There is no try/except here: emitting a request does not raise, and the call that can fail is the Controller’s, which is where a failure can be reported.

Parameters:

loader (str) – Identifier for the loader plugin.

ClusteringView.update_available_plugins(available_plugins: Dict[str, List[str]]) → None

Called whenever a new plugin is instantiated elsewhere in the app, to keep an up-to-date list of possible data sources for use by this plugin.

Parameters:

available_plugins (Dict[str, List[str]]) – dict of lists keyed by MetaClass, listing the identifiers of all instantiated plugins throughout the app.

ClusteringView.update_column_names(column_names: List[str]) → None

Updates the list of available column names.

Parameters:

column_names (List[str]) – List of column names returned from the loader.

ClusteringView.update_column_units(unit: str | None, column: str) → None

Updates the unit for a specific column.

Parameters:

  • unit (Optional[str]) – Unit of the column (e.g., ‘ms’), or None if the loader could not resolve one.

  • column (str) – Name of the column.

ClusteringView.update_plot(data: DataFrame, labels: Sequence[Any] | ndarray, confidence: Sequence[Any] | ndarray, logs: Sequence[bool], normalized: Sequence[bool], units: Sequence[str | None], plot: Sequence[bool]) → None

Updates the plot with clustered data and redraws it.

Parameters:

  • data (pd.DataFrame) – DataFrame with clustering results.

  • labels (Union[Sequence[Any], np.ndarray]) – Cluster labels for each row.

  • confidence (Union[Sequence[Any], np.ndarray]) – Cluster confidence values.

  • logs (Sequence[bool]) – Flags indicating if each column is log-scaled.

  • normalized (Sequence[bool]) – Flags indicating if each column is normalized.

  • units (Sequence[Optional[str]]) – Units for each column.

  • plot (Sequence[bool]) – Flags indicating if a column should be plotted.

ClusteringView.update_units(loader: str, column: str) → None

Ask the Controller for one column’s unit string.

The answer arrives at update_column_units.

Parameters:

  • loader (str) – Plugin name or ID.

  • column (str) – Name of the column.

Private Methods

ClusteringView._init() → None

Initializes the ClusteringView’s internal state and clears cache.

ClusteringView._reset_actions(axis_type: str = '2d') → None

Clears the figure and reinitializes axes. This will also add a flag to the tab action history if @register_action is being used to keep track of actions. Only actions applied after the most recent call to this function will be recreated if the related file is loaded.

Parameters:

axis_type (str) – Either ‘2d’ or ‘3d’ to determine plot projection.