SpikePlotter

SpikePlotter is a class for plotting SpikeAnalysis data (raster plots, firing rates). It is initiated with an instance of SpikeAnalysis and then plots the data using a primarily matplotlib background. There was some seaborn features, which have been mostly removed to reduce the dependencies.

Initializing Plotting Classes

Utilizing matplotlib` under the hood allows for some customization. During the intialization of the class different defaults can be applied using the kwargs. These should be a dictionary of standard matplotlib values, eg, {"dpi": 300, "figsize": (10,8)}. The class will warn if the attempted value is not currently customizable (ie, it is not used internally currently). Defaults are reasonable x-axis defaults to "Time (s)"

To allow the plotter for different datasets to use the same plotting defaults there is an option to initialize without datasets.

plotter = SpikePlotter(analysis=None, **{"dpi": 800}) # all plotter have reset dpi values
plotter.set_analysis(analysis=spiketrain) # now the data set is set for this plotter

from copy import deepcopy

plotter = SpikePlotter(analysis=None, **{"dpi": 800}) # all plotter have reset dpi values
plotter2 = deepcopy(plotter)

plotter.set_analysis(analysis=spiketrain1)
plotter2.set_analysis(analysis=spiketrain2)

To initialize with dataset:

plotter = SpikePlotter(analysis=spiketrain, **{"figsize": (20,16)})

If at any time the user would like to change the plotting kwargs used they can use the set_kwargs() function to change.

plotter.set_kwargs(**{'figsize': (10,8)})

Note these are global kwargs to be used on all plots. Most plotting functions also accept plot_kwargs a dictionary of standard matplotlib paramaters to be applied. If plot_kwargs is given it will overide the global kwargs set in set_kwargs.

Using the `SpikePlotter` Class

Once the class is initialized various plotting fuctions can be used: plot_zscores, plot_raster, plot_sm_fr, and plot_z_scores_ind. These functions provide common summary plotting options for data in a controllable way. Each function has its own section below.

`plot_kwargs`

Most functions accept plot_kwargs which should be a dictionary of keyword argument to apply jsut for that one function call. Currently supported are figsize, dpi, xlim, ylim, x_axis (for labeling), y_axis (for labeling), title, and cmap.

plot_kwargs = {
                'figsize' = (10,10),
                'dpi' = 200,
                'xlim' = (0,10),
                'ylim' = (-1,1),
                'title' = 'my title',
                'cmap' = 'viridis'
            }

or with the dict() constructor:

plot_kwargs = dict(figsize=(20,16), dpi=80, x_axis='Time (ms)')

Either method can then be entered into the appropriate plotting functions.

Plotting Heatmaps

Heat maps can be plotted for z scores or raw firing rate data. These use common parameters including sorting_index, figsize. They also have an optional return value of ordered_cluster_ids which returns the cluster_ids organized based on how they were plotting for use with other code. This is controlled with the boolean flag indices. These functions accept plot_kwargs.

Plotting Z scores

Two functions are provided to generate z score heatmaps: plot_zscores and plot_z_scores_ind. First plot_zscores switches the default figsize to (24,10) because it separates data by trial groupings. This requires a long, but not tall figure. It also has an optional sorting_index, which allows for the choosing which trial group to sort on. This sorting allows for the same unit to be represented on the same row of the heatmap for each trial group to compare the same unit across trials. Trial groups are sorted by size so to sort by the smallest trial group one would use sorting_index = 0, etc. Since it is sometimes nice to plot trial groups individually rather than all on the same figures this can be accomplished with plot_z_scores_ind. The one issue with plot_z_scores_ind is that it sorts each trial group individually, so that units are not on the same rows and cannot be directly compared by just aligning the figures. Additionally, in the case of needing fine control over the color bar the optional argument z_bar can be given such that z_bar=(min, max). This will set that range for all values.

plotter.plot_zscores(sorting_index = 1) # sort by 2nd trial group
plotter.plot_zscores(sorting_index = None) # auto sorts by largest trial group

or to see individually (with z bar example)

plotter.plot_zscores_ind(z_bar = [-15,15])

Plotting Raw Firing Rate heatmap

In a similar vein a heatmap of raw firing rates can be plotted with plot_raw_firing(). It uses the exact same parameters as above, sorting_index, bar

plotter.plot_raw_firing(bar=[-5, 10])

And an example return values:

ordered_cluster_ids = plotter.plot_raw_firing(bar=[-5, 10], sorting_index = 1, indices = True)

Plotting Raster plots

Raster plots are plots, which represent each action potential of a neuron as a bar with time on the X access and events on the y axis. The function plot_raster aligns a raster plot based on the window as well as highlighting the start and end of each stimulus bout (with red lines) window can either be one global window for all stimulus or a list of lists with each nested list given the window for a substimulus. To show vertical lines to mark the beginning and end of the stimulus use show_stim. To only plot rasters for specific clusters give the cluster id of that unit inside include_ids. Finally color_raster is a boolean to show color codes of each trial group to the right of the figure.

plotter.plot_raster(window = [-10,10]) # ten seconds before and after stimulus onset

# we can choose to only look at one cluster
plotter.plot_raster(window=[-1,4], include_ids = [6])

# or we can show stim lines and color bars for the trial groups
plotter.plot_raster(window=[-2,2], show_stim=True, color_raster=True)

Plotting smoothed firing rate

Firing rates of a neuron are often given in Hz or spikes/second. Because counting firing rates in bins can lead to some variability, especially in very small bin size, this function uses a Gaussian smoothing filter convolved over each trial group to reduce this variability for plotting. The trial groups are colored from cool to hot with rainbow colors, but if this is not desired the default cmap can be loaded during the initialization kwargs with {'cmap': 'vlag'}. Similarly to the raster a window should be given. include_ids can limit plotting to only the desired neurons.

plotter.plot_sm_fr(window=[-10, 10], sm_time_ms = 50) # ten seconds before and after stimulus
                                                      # smoothing over ~ 50 ms for each bin

To show the power of combining the code we can return cluster ids sorted based on z scored responses and use that to show the smoothed firing of only the top ten neurons.

cluster_ids_sorted = plotter.plot_zscores(indices=True)

plotter.plot_sm_fr(window=[-10,10], sm_time_ms = 50, include_ids = cluster_ids_sorted[:10])

Plotting trial-trial correlations

To create comparisons of trial-trial correlations of different trial groups the plot_correlations can be used. This function lets one specify the plot_type, which can be whisker, violin, or bar. The mode can be either mean or median, which determines what is displayed. Finally the boolean sem determines whether the standard error of the mean or the standard devation should be used for bar. This function accepts plot_kwargs. Finally to control the color of each trial group a user can specify a colors dictionary where each stimulus is a key and each desired color is the value of those keys. Since this comes us a lot let’s look at one quick example:

colors = {'stim1': 'blue', 'stim2': 'red'}

or one global color can be given:

colors = 'red'

To put this all together we would running

plotter.plot_correlations(plot_type='violin', mode='median', colors=dict(stim1='blue', stim2='red', stim3='green'))

Plotting response traces

These are similar to the smoothed firing rate, but give the option of looking at different metrics of the data plotted over time. We also have the option to average over the data many different ways. To start the fr_type is specified as either raw or zscore. Then one selects how they want to assess the data. mode can be mean, max, median, min. Optionally the user can supply their own function to apply to the data, but note this function must work on matrices (3d) and must be able to handle np.nan datapoints. (When the user specifies :mode:`mean`, internal the function uses np.nanmean).

Then we specify which axes of the data to assess: by_neuron, by_trial, by_trialgroup. These three booleans interact to determine the data type.

by_neuron and by_trial will do one trace/trial/stimulus/neuron (ie this isn’t ideal since it will potentially be 100s of traces) by_neuron will average over all trials for a stimulus and so be 1 trace/ neuron /stimulus by_trial will average over all neurons for each trial so it will be 1 trace/trial /stimulus by_trialgroup will average over each trial group

Note in the discussion above average is written, but any of the mode’s can be substituted here.

Finally, the user can choose to display ebar to show standard deviations of the traces or sem to show standard error of the mean.

plotter.plot_response_trace(fr_type='zscore', by_neuron=True, sem=True, mode='mean') # do the mean
plotter.plot_response_trace(fr_type='zscore', by_neuron=True, sem=True, mode='max') # same but take the max response only