2. Usage instructions
Upon launching, the GUI automatically finds subjects within the IBL that have probe tracing completed. To select a subject, click on the subject drop down list in the top right hand corner and scroll through to find the subject of interest (see figure below). A list of sessions for the chosen subject and previous alignments associated with each session will then be loaded into the second and third drop down menus respectively. If this is the first time an alignment is being conducted for a session the only alignment option will be original. If, however, the session has been previously aligned, it is possible to initiate the GUI from the previous alignment. Once the drop down options have been chosen, click on the Get Data button to download the data. The GUI automatically downloads all data necessary and once loaded plots should appear.
For issues regarding loading data into the GUI please refer to the Troubleshooting section
Once the GUI has launched you will see a button in top right hand corner with the symbol ... (note this will be in place of the subject drop down list indicated in the layout figure below). Click on this button and navigate to the folder where the input data is stored. Once you have selected the folder click the Get Data to load the data into the GUI.
The GUI comprises four main figure areas.
The first figure contains three panels which display electrophysiology data in the form of:
- Image Plots (2D representation of data in image or scatter plots)
- Line Plots (1D representation of data in a line plot)
- Probe Plots (2D representation of data as a heatmap overlaid on the Neuropixel 3B geometry)
Different types of data can be viewed in each of the panels and the available options can be seen by clicking on the Image Plots, Line Plots and Probe Plots menu bar. The display in each panel can be changed by clicking through the options in each menu bar or by using the shortcuts Alt+ 1, Alt + 2, Alt + 3, for the image, line and probe plots respectively.
The order of the panels can also be rearranged by changing the view (under the Display Options menu bar) or by pressing, Shift + 1, Shift + 2 or Shift + 3.
The second figure displays the brain regions through which the traced probe track passes (the trajectory). It is split into three panels, which display, from left to right,
- Scaled brain regions
- Scale factor applied to brain regions - represented as heatmap
- Original (unscaled) brain regions - for reference
The black dotted lines on the left and right panels indicate the location along the trajectory of the most ventral and dorsal electrode. The labels overlaid on the brain regions can be toggled on and off using Shift + L.
The actual scale factor value is displayed in the title of the colourbar (top of figure) when hovering over a region on the central scale factor plot.
The third figure displays a slice through the brain where the traced probe track passes. Each layer of the slice is obtained from the coordinate of the trajectory at that depth and thus if the trajectory is not smooth, the image can appear to jump in some regions.
Overlaid on the slice is a black line linking the traced points (the trajectory), extended to the top and bottom of the brain, and the location of the electrodes on the probe along this trajectory (red points). When reference lines are added to the Ephys and Histology figures, they are displayed as black dotted lines perpendicular to the local trajectory.
The collection of lines and points overlaid on the slice figure can be toggled on and off using Shift + C and the intensity of the slice images can be changed using the intensity scale bar located on the right hand side of the figure.
There are four options for the tilted slice displayed (changed using Alt+ 4):
- Slice taken from red channel of histology image
- Slice taken from green channel of histology image
- Slice taken from Allen brain atlas average template
- Slice taken from Allen brain atlas annotation template
The red and and green channel histology images are optional inputs. If these files are not provided or found then a slice from the Allen brain atlas average template will be shown instead.
For IBL users unable to see the green and red histology image for a subject, please refer to this Troubleshooting section
The fourth figure provides a 2D representation of the scaling applied along the depth of the trajectory. Coordinates are relative to the location of the most ventral electrode. Three lines are displayed in this figure
- Reference line (black dotted line) - reference for when no fit/scaling is applied
- Fit line (blue solid line) - piecewise fit along depth of trajectory
- Linear fit line (red dotted line) - linear fit along depth of trajectory (only present when three or more reference lines are implemented)
Reference line pairs are used to align features on the Ephys and Histology figures. A pair can be added to the GUI by double clicking at any point on either the Ephys or Histology figure. A pair of lines with the same colour and style should appear on both figures and can be moved independently. Once the two lines of a reference pair line have been moved to the feature/landmark that needs to be aligned, the fit can be applied by pressing the Fit button or by pressing Enter key.
Different types of fit are applied depending on the number of reference lines implemented.
A fit applied with a single reference line pair will result in an offset.
A fit applied with two reference line pairs will result in an offset and scaling of regions between the two reference line pairs. The remaining regions, located beyond the reference lines, will be offset, however, will remain unscaled.
A fit applied with three or more reference line pairs will result in an offset and piecewise scaling of regions between each of the reference lines. By default the remaining regions will be scaled according to a linear fit through all the reference lines (red dotted line in fit figure). If instead, one wants to keep the regions beyond the reference lines unscaled, the default can be turned off by un-ticking the linear fit checkbox located in the top left corner of the Fit figure.
When a fit is applied the location of the electrodes on the slice figure will update.
A reference line can be deleted by hovering over the line and pressing Shift + D. Any fits anchored on a reference line will be lost once the line is deleted. The reference lines can be hidden/ redisplayed using Shift + H.
Once you are happy with the alignment, the new locations of the electrodes can be saved by pressing the Upload button or Shift + U.
Once the upload button has been clicked a window will pop-up asking to determine 1) the confidence in alignment, 2) the QC (which will label the insertion), 3) the reason for that QC (e.g. Drift and Noise seen in the recording).
The electrode locations and reference lines will then be saved in Alyx. If more than one person has alignment the same session, at this point the alignment qc is computed to determine whether the two alignments agree.
The location of your electrodes will be saved into a json file called channel_locations.json in the folder where all the input data is stored. The location of your reference lines used for the alignments will also be saved into a file called prev_alignments.json so that previous alignments can be recovered at any point.
If any notes associated with a session have been uploaded to Alyx, these can be displayed as a popup by clicking on Session Information on the menu bar and selecting Session Notes
Information about brain regions can be displayed by hovering over a brain region in the histology figure and pressing Shift + I. This will bring up a popup with the brain regions organised according to the Allen atlas structure tree.
When displaying the cluster plots on the 2D image plots, the cluster autocorrelogram and waveform can be viewed in a popup by clicking on a scatter point. It is possible to display many popups for different clusters. To collectively minimise/ show the cluster popup windows press Alt + M (make sure your cursor is located on the main GUI window, not a popup window). To close the cluster popup windows press Alt + X
By default, the plots in the Ephys figure are shown for all units that have been classified as Good and Mua following spike sorting. The Filter Unit option in the menu bar can be used to restrict the type of unit displayed.
A total of 10 previous fits are stored in memory. One can move to previous fits by using the Previous and Next buttons or by using the Left and Right arrow keys.
To reset the GUI to the original state, i.e. no alignments, press the Reset button or Shift + R.
It is possible to zoom in on some plots in the Ephys and Histology figures. To reset the axis press Shift + A.