Interactive visualization of ephys data
phy provides two GUIs:
- the Template GUI for KiloSort/SpykingCircus datasets.
- the Kwik GUI for Kwik datasets, obtained with the klusta spike-sorting program.
These GUIs let you visualize ephys data that has already been spike-sorted. You can also refine the clustering manually if needed. Finally, you can use the GUI as a platform for interactive ephys data analysis. The IPython view lets you interact with the data interactively from within the GUI.
Opening a dataset in the GUI
Note: there will be a simpler procedure to open the GUI on Windows in a future version.
To open the GUI on a given dataset, you need to use the command-line from the directory containing your dataset.
phy template-gui params.py in the directory that contains the
Usage: phy template-gui [OPTIONS] PARAMS_PATH Launch the template GUI on a params.py file. Options: --clear-state / --no-clear-state Clear the GUI state in `~/.phy/` and in `.phy`. --clear-cache / --no-clear-cache Clear the .phy cache in the data directory. --help Show this message and exit.
The dataset is made of a set of
.npy files (
spike_clusters.npy, and so on). There are also
.tsv files for cluster-dependent data.
cluster_info.tsv is automatically saved along with your data. It contains all information from the cluster view.
spike_clusters.npy and TSV files are ever modified by phy. The rest of the data files are open in read-only mode.
phy kwik-gui filename.kwik in the directory that contains the
Note: only the
filename.kwik file is ever modified by phy.
General presentation of the GUI
Note: we focus here on the template GUI.
The GUI is made of several parts:
- Menu bar (top)
- Dock widgets (main window)
- Cluster view
- Similarity view
- Graphical views
- Status bar (bottom)
Dock widgets can be moved anywhere in or outside of the GUI (floating mode). They can be closed as well. New views can be added from the
View menu in the menu bar.
Use the menu, keyboard shortcuts, or snippets to trigger actions. Press
F1 to see the list of Keyboard shortcuts.
The Cluster view shows the list of all clusters in your dataset.
You can click on one cluster to select it. Select multiple clusters by keeping Control or Shift pressed. Selected clusters are shown in the different graphical views (detailled below). Clustering actions (merge, split, move, label...) operate on selected clusters.
Select quickly one or several cluster(s) by using snippets: for example, type
:c 47 49 to select clusters 47 and 49. See the list of keyboard shortcuts and snippets for more details.
Selected clusters are assigned with a special color: blue for the first selected cluster, red for the second, yellow for the third, etc.
In addition to this temporary color mapping, there is also a notion of global color map that assigns a (relatively) unique color to all clusters. This is especially useful in views that can display many spikes from many non-selected clusters at once: the Trace view (when the
toggle_highlighted_spikes option is enabled), the Raster view, and the Template view.
Several colormaps are provided by phy (linear, divergent, categorical...). You can choose which cluster attribute to use for the color mapping. For example, you can use a cluster color depending on the depth, the number of spikes, the waveform amplitude, etc.
To display all clusters like in the cluster view (unsorted clusters are white, noise/mua clusters are gray, good clusters are green, selected clusters are in bright colors), use the following parameters:
- Color field: group
- Colormap: cluster group
- Toggle categorical colormap
Default columns in the cluster view include the cluster id, best channel (channel with peak waveform amplitude), depth (mostly useful for Neuropixels probes), n_spikes. Click on a column to sort by the corresponding attribute. You can add custom columns (labels, see next page). Use the
:s snippet to quickly sort by a given column.
Clusters found by spike sorting algorithms have different qualities. Some are genuine single units, others are mixtures of neurons, others are essentially made of artifacts. For historical reasons, the cluster group is one of:
mua(multi-unit activity, light grey)
None: unsorted (white)
Rows in the cluster view are shown in different colors according to the cluster group.
To do: customizable groups and associated colors.
You can filter the list of clusters shown in the cluster view, in the
filter text box at the top of the cluster view. Type a boolean expression using the column names as variables, and press
Escape to clear the filtering. You can also use the
group == 'good': only show good clusters
n_spikes > 10000: only show clusters that have more than 10,000 spikes
group != 'noise' && depth >= 1000: only show non-noise clusters at a depth larger than 1000 ``
The similarity view is very similar to the cluster view. It has an additional column: the similarity. It represents the similarity to clusters selected in the cluster view. As such, its contents change every time the cluster selection changes in the cluster view. By default, clusters in the similarity view are sorted by decreasing similarity.
The similarity score is obtained from the
Graphical views constitute the most important part of the GUI. They represent different aspects of the selected clusters and the corresponding spikes.
Views can be resized, moved around, tabbed in the GUI. You can close views that you don't need, you can add new views. You can also add multiple views of the same type. You can disable automatic updating of any view upon cluster selection.
Interactivity in all graphical views:
- Pan: left-click and drag
- Zoom: right-click and drag, mouse wheel
- Reset pan and zoom: double-click
- Increase or decrease scaling: control+wheel (only in some views).
- Scatter plots: change the marker size
- Histograms: change the range on the x axis
- Waveform, template, trace views: change the y scaling
This view shows the waveforms of a selection of spikes, on the relevant channels (based on amplitude and proximity to the peak waveform amplitude channel).
controller.n_spikes_waveforms=100, by default, specifies the maximum number of spikes per cluster to pick for visualization in the waveform view. 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.
You can show: spike waveforms, mean spike waveforms, or template waveforms (
Keyboard shortcuts for WaveformView - change_box_size ctrl+wheel - decrease ctrl+down - extend_horizontally shift+right - extend_vertically shift+up - increase ctrl+up - narrow ctrl+left - next_waveforms_type w - previous_waveforms_type shift+w - shrink_horizontally shift+left - shrink_vertically shift+down - toggle_mean_waveforms m - toggle_show_labels ctrl+l - toggle_waveform_overlap o - widen ctrl+right Snippets for WaveformView - change_n_spikes_waveforms :wn
This view shows the principal component features of a selection of spikes in the selected clusters, on the relevant channels. The exact channels can be changed by control-clicking in the waveform view. A, B, C... refer to the first, second, third... principal components.
Background spikes from all clusters are shown in grey.
controller.n_spikes_features=2500, by default, specifies the maximum number of spikes per cluster to pick for visualization in the feature view. The parameter
controller.n_spikes_features_background=1000, by default, specifies the maximum number of spikes to pick for the background features. These background spikes are uniformly spaced in time across the entire recording, and across all clusters indistinctively.
The default subplot organization of the feature view is (x and y for each of the 4x4 subplots, 0 refers to first selected channel, 1 refers to second select channel):
time,0A 1A,0A 0B,0A 1B,0A 0A,1A time,1A 0B,1A 1B,1A 0A,0B 1A,0B time,0B 1B,0B 0A,1B 1A,1B 0B,1B time,1B
The documentation provides a plugin example showing how to customize the subplot organization.
Keyboard shortcuts for FeatureView - add_lasso_point ctrl+click - change_marker_size ctrl+wheel - decrease ctrl+- - increase ctrl++ - stop_lasso ctrl+right click - toggle_automatic_channel_selection c Snippets for FeatureView
Template feature view
This view is only active when exactly two clusters are selected. It shows the
template_features.npy file, which is created by KiloSort.
Keyboard shortcuts for ScatterView - change_marker_size ctrl+wheel Snippets for ScatterView
This view shows the autocorrelograms and cross-correlograms between all pairs of selected clusters.
Subplot at row i, column j, shows the cross-correlogram of selected cluster #i versus cluster #j.
The baseline firing rate is shown. You can also display horizontal lines for the refractory period.
controller.n_spikes_correlograms=100000, by default, specifies the maximum number of spikes across all selected clusters to pick for computation of the cross-correlograms. These spikes are picked randomly.
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.
Keyboard shortcuts for CorrelogramView - change_window_size ctrl+wheel Snippets for CorrelogramView - set_bin :cb - set_refractory_period :cr - set_window :cw
This view shows the raw data traces across all channels, with spikes from the selected clusters as well. You can also choose to show spikes from all clusters, not just selected clusters.
You can switch the origin (top or bottom) with the
Keyboard shortcuts for TraceView - change_trace_size ctrl+wheel - decrease alt+down - go_left alt+left - go_right alt+right - go_to alt+t - go_to_end alt+end - go_to_next_spike alt+pgdown - go_to_previous_spike alt+pgup - go_to_start alt+home - increase alt+up - jump_left shift+alt+left - jump_right shift+alt+right - narrow alt++ - select_channel_pcA shift+left click - select_channel_pcB shift+right click - select_spike ctrl+click - switch_origin alt+o - toggle_highlighted_spikes alt+s - toggle_show_labels alt+l - widen alt+- Snippets for TraceView - go_to :tg - shift :ts
This view shows the amplitude of a selection of spikes belonging to the selected clusters, along with vertical histograms on the right.
Different types of amplitudes
You can toggle between different types of amplitudes by pressing
template: the template amplitudes (stored in
amplitudes.npy, multiplied by the template waveform maximum amplitude on the peak channel)
raw: the raw spike waveform maximum amplitude on the peak channel (at the moment, extracted on the fly from the raw data file, so this is slow).
feature: the spike amplitude on a specific dimension, by default the first PC component on the peak channel. The dimension can be changed from the feature view with
alt+left click(x axis) and
alt+right click(y axis).
Number of spikes.
controller.n_spikes_amplitudes=5000, by default, specifies the maximum number of spikes per cluster to pick for visualization in the amplitude view.
Note: currently, this number is divided by 5 for the
raw amplitudes, so as to keep loading delays reasonable.
This view supports splitting like in the feature view. When splitting, all spikes (and not just displayed spikes) are loaded before computing the spikes that belong to the lasso polygon.
Extra spikes beyond those of the selected clusters are shown in gray. These spikes come from clusters whose best channels include the first selected cluster's peak channel.
The time interval currenty displayed in the trace view is shown as a vertical yellow bar. You can change the current time range with
Alt+click in the amplitude view: that will automatically change the time range in the trace view.
Keyboard shortcuts for AmplitudeView - change_marker_size ctrl+wheel - next_amplitudes_type a - previous_amplitudes_type shift+a - select_time alt+click - select_x_dim shift+left click - select_y_dim shift+right click Snippets for AmplitudeView
Cluster statistics view
This generic view shows histogram related to the selected clusters. Built-in statistics views include:
- Inter-spike intervals (computed using all spikes for the selected clusters)
- Instantenous firing-rate (computed using all spikes for the selected clusters)
Keyboard shortcuts for ISIView - change_window_size ctrl+wheel Snippets for ISIView - set_bin_size (ms) :isib - set_n_bins :isin - set_x_max (ms) :isimax - set_x_min (ms) :isimin
Keyboard shortcuts for FiringRateView - change_window_size ctrl+wheel Snippets for FiringRateView - set_bin_size (s) :frb - set_n_bins :frn - set_x_max (s) :frmax - set_x_min (s) :frmin
This view shows a raster plot of all clusters. The order of the rows depends on the sort in the cluster view. If filtering is enabled in the cluster view, only filtered in clusters are shown in the raster view.
Select a cluster with Control+click.
Keyboard shortcuts for RasterView - change_marker_size ctrl+wheel - decrease_marker_size ctrl+shift+- - increase_marker_size ctrl+shift++ - select_cluster ctrl+click Snippets for RasterView
This view shows all templates. The position of the templates depends on the sort in the cluster view. If filtering is enabled in the cluster view, only filtered in clusters are shown in the template view.
Select a cluster with Control+click.
Keyboard shortcuts for TemplateView - change_template_size ctrl+wheel - decrease ctrl+alt+- - increase ctrl+alt++ - select_cluster ctrl+click Snippets for TemplateView
Spike attribute view
A spike attribute view is a view automatically created for every
spike_somename.npy file in the data directory, that contains as many 1D or 2D points as spikes. In other words, the array shape should be
- 1D array: the view shows time (x axis) versus the value (y axis) for every spike
- 2D array: the view shows the (x, y) values for every spike
In the following screenshot, a
spike_hello.npy array containing
sin(spike_time) was saved, and a
SpikeHelloView was automatically created:
You can split clusters by drawing polygons in the spike attribute views, as in the feature, amplitude, and template feature views.
Keyboard shortcuts for ScatterView - change_marker_size ctrl+wheel Snippets for ScatterView
The IPython view is an interactive IPython console that runs in the GUI's process. It lets you interact with the data and the GUI interactively.
For convenience, the following variables are available in the GUI:
TemplateModelinstance that represents the dataset.
TemplateControllerinstance that links the model to the views.
Supervisorinstance that handles the cluster and similarity views, the cluster assignments, the clustering actions, etc. The clustering process by itself (which spikes are assigned to which clusters) is managed by
You can use matplotlib to make quick plots in the IPython view, although it is better to write a custom view properly if you need to reuse it (see the developer section in this documentation).