Document view settings controls

Author: rossant

docs/api.md

@@ -40,6 +40,7 @@ phy: interactive visualization and manual spike sorting of large-scale ephys dat
 * [phy.gui.screen_size](#phyguiscreen_size)
 * [phy.gui.screenshot](#phyguiscreenshot)
 * [phy.gui.thread_pool](#phyguithread_pool)
+* [phy.gui.view_settings_dialog](#phyguiview_settings_dialog)
 * [phy.gui.Actions](#phyguiactions)
 * [phy.gui.Debouncer](#phyguidebouncer)
 * [phy.gui.DockWidget](#phyguidockwidget)
@@ -49,6 +50,7 @@ phy: interactive visualization and manual spike sorting of large-scale ephys dat
 * [phy.gui.KeyValueWidget](#phyguikeyvaluewidget)
 * [phy.gui.Snippets](#phyguisnippets)
 * [phy.gui.Table](#phyguitable)
+* [phy.gui.ViewSettingsDialog](#phyguiviewsettingsdialog)
 * [phy.gui.Worker](#phyguiworker)
 
 
@@ -731,6 +733,18 @@ thread_pool().start(w)
 
 ---
 
+#### phy.gui.view_settings_dialog
+
+
+**`phy.gui.view_settings_dialog(title, fields, parent=None, validate=None)`**
+
+Show a typed settings dialog and return its values, or ``None`` when cancelled.
+
+``validate`` may return an error message. The dialog remains open until the
+values are valid or the user cancels it.
+
+---
+
 ### phy.gui.Actions
 
 Group of actions bound to a GUI.
@@ -1505,7 +1519,7 @@ user input.
 #### KeyValueWidget.add_pair
 
 
-**`KeyValueWidget.add_pair(self, name, default=None, vtype=None)`**
+**`KeyValueWidget.add_pair(self, name, default=None, vtype=None, label=None, minimum=None, maximum=None, decimals=None, suffix=None, tooltip=None)`**
 
 Add a key-value pair.
 
@@ -1977,6 +1991,21 @@ sizeHint(self) -> QSize
 
 
 
+---
+
+### phy.gui.ViewSettingsDialog
+
+A reusable typed settings form for view-specific parameters.
+
+---
+
+#### ViewSettingsDialog.values
+
+
+**`ViewSettingsDialog.values(self)`**
+
+Return the settings currently entered in the form.
+
 ---
 
 ### phy.gui.Worker
@@ -7675,6 +7704,15 @@ Decrease the scaling parameter.
 
 ---
 
+#### FiringRateView.edit_view_settings
+
+
+**`FiringRateView.edit_view_settings(self)`**
+
+Edit the histogram bin size and displayed range.
+
+---
+
 #### FiringRateView.get_clusters_data
 
 
@@ -7909,6 +7947,15 @@ Decrease the scaling parameter.
 
 ---
 
+#### HistogramView.edit_view_settings
+
+
+**`HistogramView.edit_view_settings(self)`**
+
+Edit the histogram bin size and displayed range.
+
+---
+
 #### HistogramView.get_clusters_data
 
 
@@ -8136,6 +8183,15 @@ Decrease the scaling parameter.
 
 ---
 
+#### ISIView.edit_view_settings
+
+
+**`ISIView.edit_view_settings(self)`**
+
+Edit the histogram bin size and displayed range.
+
+---
+
 #### ISIView.get_clusters_data
 
 

docs/changelog.md

@@ -8,7 +8,7 @@ This file records user-visible changes to phy. The format is based on
 
 Changes below are available from the latest source checkout but have not yet
 been included in a stable release. The current entries cover all user-visible
-changes committed on 23 July 2026; test-only commits are represented by the
+changes committed on 23–24 July 2026; test-only commits are represented by the
 behavior they verify rather than listed separately.
 
 ### Added
@@ -30,6 +30,10 @@ behavior they verify rather than listed separately.
 - Waveform, Amplitude, and Correlogram views support optional fixed total spike
   budgets across multi-cluster selections. They use fixed per-cluster budgets
   by default so sampling accuracy does not decrease as selections grow.
+- Configure per-cluster and optional shared spike budgets from **View
+  settings** in the Waveform, Amplitude, and Correlogram view menus.
+  Correlogram, Firing Rate, and ISI settings dialogs also expose their bin,
+  window, range, and related display parameters.
 - Hidden or inactive-tab Waveform, Amplitude, and Correlogram views defer
   selection plotting until they become visible, retaining only the latest
   selection.

docs/gui.md

@@ -19,6 +19,25 @@ Each graphical view has controls for:
 
 The arrangement and most view settings are restored the next time phy opens.
 
+### View settings
+
+Open a plot's view-specific menu and choose **View settings** to edit related
+parameters together:
+
+* Waveform, Amplitude, and Correlogram views expose independent per-cluster
+  spike budgets and an optional shared total budget.
+* The Amplitude View also exposes its gray background-spike budget.
+* The Correlogram View also exposes bin size, window size, and refractory
+  period.
+* Firing Rate and ISI views expose bin size and the displayed range. These
+  views use every spike in the displayed clusters and therefore have no
+  spike-sampling budget.
+
+Enabled budget checkboxes map directly to integer controller settings.
+Disabling one maps that setting to `None`. Changes apply and replot
+immediately. The existing snippets and mouse-wheel controls remain available
+for quick single-setting changes.
+
 ## Selecting clusters
 
 The Cluster View contains the primary selection. The first selected cluster is blue, the second
@@ -90,4 +109,9 @@ phy template-gui params.py --clear-state
 phy template-gui params.py --clear-cache
 ```
 
+Spike-budget controller settings are global and carry across datasets.
+Correlogram bin/window/refractory settings and Firing Rate/ISI bin/range
+settings are dataset-specific, because appropriate display scales can depend
+on the recording.
+
 For more detail, see [Configuration and customization](configuration.md).

docs/performance.md

@@ -32,6 +32,14 @@ predictable runtime or memory use matters more. For example,
 clusters, subject to the 100-per-cluster ceiling. Small clusters keep all
 their available spikes and leave their unused shares for larger clusters.
 
+You can change these values without a plugin: open the Waveform, Amplitude, or
+Correlogram view menu and choose **View settings**. **Use per-cluster budget**
+controls the corresponding `n_spikes_*` value, and **Use shared total budget**
+controls `n_spikes_*_total`. Disabling either checkbox stores `None` for that
+limit. The Amplitude dialog also exposes
+`n_spikes_amplitudes_background`. Changes apply immediately and are saved in
+the global Template GUI state when phy closes normally.
+
 Other common cluster display limits are eight clusters for the Waveform,
 Feature, Amplitude, and scatter views, and 20 for histogram and Probe views.
 These limits control what a view plots; they do not change the table selection.
@@ -69,6 +77,10 @@ cluster, with no spike-sampling budget. Its bin count and visible time range
 control the histogram. The time range is saved in the dataset's `.phy/state.json`
 and is not reused for fresh datasets.
 
+The Correlogram, Firing Rate, and ISI view menus expose their bin and range
+parameters together under **View settings**. These display parameters are
+dataset-local; changing them does not affect the controller spike budgets.
+
 Some actions explicitly request `load_all=True` and bypass a display limit.
 That does not turn the corresponding view setting into a global analysis
 setting; check the action or plugin doing the calculation.

docs/visualization.md

@@ -189,6 +189,10 @@ of spikes per cluster. By default,
 `controller.n_spikes_waveforms_total=None`, so every displayed cluster gets
 its own budget. Set the total to an integer, such as `400`, to share that fixed
 number across all displayed clusters.
+Choose **View settings** in the Waveform View menu to edit both limits
+together. Each limit has its own enable checkbox; disabling a limit stores
+`None`. Changes replot immediately, while the `:wn` snippet remains available
+for quickly changing only the per-cluster value.
 The parameter `controller.batch_size_waveforms=10`, by default, specifies the number of batches used to extract the waveforms. Each batch corresponds to a set of successive spikes. The different batch positions are uniformly spaced in time across the entire recording.
 
 You can select a channel with **Control+click** (this impacts the feature view). You can change the scaling of the channel positions and the waveforms.
@@ -323,6 +327,10 @@ auto- and cross-correlogram calculation. These spikes are picked randomly.
 See [Spike sampling and performance](performance.md) before increasing them.
 
 You can dynamically change the window size and bin size with control+mouse wheel and alt+mouse wheel.
+Choose **View settings** in the view menu to edit the two spike-budget modes,
+bin size, window size, and refractory period together. The budget settings are
+global controller preferences; the bin, window, and refractory settings are
+saved for the current dataset.
 
 *Note*: the central peak is artificially removed to avoid artifacts. Decrease the bin size (e.g. to 0.1 ms) if you need to visualize fine temporal structure.
 
@@ -455,6 +463,9 @@ The parameter `controller.n_spikes_amplitudes=10000` bounds the selected
 spikes per cluster. The default `controller.n_spikes_amplitudes_total=None`
 preserves that budget for every selected cluster. Set the total to an integer
 to share a fixed budget across the Amplitude View.
+Choose **View settings** in the Amplitude View menu to edit the per-cluster,
+optional shared total, and gray background budgets together. Changes take
+effect immediately and are saved as global controller preferences.
 
 *Note*: currently, this number is divided by 5 for the `raw` amplitudes, so as to keep loading delays reasonable.
 
@@ -496,8 +507,9 @@ This generic view shows histogram related to the selected clusters. Built-in sta
 
 The Firing Rate View does not sample or impose a spike budget. Its number of
 bins and visible time range only control how all cluster spikes are grouped.
-The time range is dataset-local, so a range saved for one recording does not
-clip a fresh dataset.
+Choose **View settings** in the Firing Rate or ISI view menu to edit bin size
+and the displayed range together. These parameters are dataset-local, so
+values saved for one recording do not clip or coarsen a fresh dataset.
 
 ![image](https://user-images.githubusercontent.com/1942359/58951704-193e5080-8792-11e9-873f-91a9115a9e7c.png)