surmeierlab/EZT2022SA: EZTNotebooks

Jupyter Notebooks for Science Advances paper ZampeseSA2022 README (8 AUG 2022): This repository contains five Jupyter Notebooks (Python 3.0) created or modified for specific use with action potential analysis for the Zampese, et.al. 2022 Science Advances paper. APandFRatio4Dplots.ipynb was created to generate multi-dimensional plots from any .csv file organized with 4 variables in columns. For the present paper, the Notebook was used to plot time synchronized recordings of action potential peak voltage time, spike frequency, and inter-spike-interval variability (ISI cV), plus the dual excitation wavelength fluorescence normalized ratiometric data. The Notebooks focused solely on voltage action potential (AP) analysis and figure panel plots are: APplotsPanelFiguretopdf.ipynb, APDetectPeaksDatatocsv.ipynb, APanddVdtDatatocsv.ipynb, APandcVDatatocsv.ipynb. ZampeseSA2022.pdf These Notebooks were used to analyze time series electrophysiological recordings obtained with MultiClampCommanderV2.1 software, 700B amplifier hardware, via signals routed from VoltageOutput and VoltageRecord windows within Prairie View 5.3-5.5 (Bruker Nano Fluorescence). A VoltageRecord electrophysiology experiment folder contains .xml configuration metadata and a .csv data file. The VoltageRecord.xml file includes the gain settings read from the MultiClampCommander, for scaling factors, and the voltage analog-to-digital card sampling rate employed in the acquisition. The VoltageRecord.csv file includes the time plus up to eight selected channels, for our electrophysiology needs the "Time", "Primary", and "Secondary" headers with data for each sampled time are provided in descending rows. The Notebooks are designed to open the defined folder containing multiple experiment recording folders and combine each folder VoltageRecord.csv file with the technical information in the VoltageRecord.xml files to create a Pandas DataFrame to properly access the recording data and enable the execution of the subsequent steps of analysis. The default time axis is converted to ms, while the electrical signals are voltages in mV, and current (injected and holding) in pA. All Notebooks create plots of the recording raw data, as Primary output over time (s) and/or Secondary output over time (s). Additionally, all Notebooks have plots that are designed to allow inspection of smaller temporal windows, or ranges, from the entire acquisition time series by applying a “mask” to define a specific time interval window. Requirements: the following modules required to run the Notebooks in this repository are already available online: detecta, glob, lxml, matplotlib, medfilt, neo, neurphys, numpy, pandas, plotlyscipy. APplotsPanelFiguretopdf.ipynb opens a VoltageRecord.csv file within a defined directory and experiment folder containing the file and plots the time series data which then can be saved as a .pdf file (figure panel) for the entire recording or for a defined time interval. APDetectPeaksDatatocsv.ipynb is used to locate and confirm the voltage peaks of action potentials (APs) within a voltage time series. The Notebook opens a VoltageRecord.csv file within a defined directory and experiment folder containing the file and then plots the recording raw data. The DetectPeaks program is used from the Detecta repository to find the time associated with each AP peak voltage. The program inputs are: minimum peak height (mph; the threshold mV value above which a peak will be detected), minimum peak distance (mpd; the number of ms to ignore after a found peak -- to avoid counting multiple points above, and after, the threshold within a peak or a plateau). Note, the selection of these parameters will often depend upon the type of cell, nature of recording (mph), amplifier settings (mpd), and the observed firing frequency (mpd). For example, reviewing voltage recording data from SNc dopaminergic neurons acquired with perforated patch current clamp at 10kHz acquisition rate with resting spike rate of 1-4 Hz we recommend mph -20mV and mdp of 800-200ms (1 to 4 Hz). The functions “intervals” and “freqs” calculate the inter-spike interval, and its corresponding frequency, between neighboring APs of spikes within the recording. The Notebook can define a specific time interval window and thus calculate ISI spike rate only for this segment. Importantly, the Notebook can generate a plot of the recording where each detected peak event is indicated by a symbol overlaid on the voltage recording at each detected peak time point and voltage value. This functionality is essential to enable inspection of the voltage recording during analysis to manually verify that the chosen mph and mpd parameters are appropriate for finding the actual AP peaks for the defined recording data window. Finally, the Notebook generates .csv output files reporting a row for each AP peak time point and the ISI values (1/frequency). APanddVdtDatatocsv.ipynb is used to estimate the action potential (AP) voltage threshold and a maximum dV/dt for APs, within the sampling period limitations, in selected voltage recordings. The Notebook opens a VoltageRecord.csv file, generates a plot of the recording and applies a defined degree of mean smoothing to the voltage trace, which is often required to reduce sampling noise in the discrete difference dV/dt data traces. Note, displaying a raw data trace with no smoothing is achieved by selecting “1” as the number of points considered for the smoothing. Next, the Notebook can calculate the derivative of the voltage over time, dV/dt (mV/ms). The plot of the derivative with time can then be plotted and also overlaid (with a DC shift offset for dV/dt) with the voltage recording to observe the temporal correlation around AP threshold between the two traces. Then, the Notebook also plots the cell voltage (mV) vs the derivative, dV/dt, (mV/ms) for all sampled times, generating an AP phase plot. To determine the AP initiation threshold for the APs in the recording the DetectOnset program is used from the Detecta repository. The program inputs are: minimum dV/dt threshold (threshold, to ignore sub-threshold oscillations) and minimum number of sampled points above threshold (n_above, to restrict detecting short-lived noise events as AP spikes). A second threshold value, threshold2, can also be used to confirm an increasing signal and rule out flat plateaus. Recommended values: threshold = 5, n_above= 4, threshold2 = 10. A phase plot is available with the symbols added to indicate the points where the AP threshold is being crossed in the V/dVdt plot. The Notebook also runs the DetectPeaks program twice to find the peak of APs and again with a negative mph to find the minimum of the AP during the hyperpolarization phase of each AP. Parameters for peak (mph, mpd) and minimum (mph, mpd, valley) detections again need to be established by the operator, based on the recording trace. Another output is a plot, that can also be restricted to specific time intervals, where symbols indicating AP thresholds, AP peaks detected, and AP minimums detected can be added. We recommend carefully inspecting the plot to verify that the parameters selected are appropriate and don’t result in artifacts. The Notebook creates a Pandas DataFrame with all the calculated parameters from each AP found represented in a separate row. A .csv file of the DataFrame can be generated as an output. APandcVDatatocsv.ipynb is used to inspect the variation of the action potential (AP) spike timing within a time series recording. The Notebook opens a VoltageRecord.csv file within a defined directory and experiment folder containing the file and then plots the recording raw data. It then calculates an array of parameters over the entire recording, including time of AP spike peak voltage, interval between time adjacent spikes (ISI), an average spike rate over a selected unit of time (stays with units of s, not ms), and also the coefficient of variation of ISI over a selected unit of time. The Notebook can also determine a rolling average specifying the time window considered for each average, and the stride between averages, plot them and save them as a .cvs output file. APandFRatio4Dplots.ipynb is used to generate 4 dimensional plots (xyz + a “c” dimension represented in a colorimetric scale). This Notebook operates on a .csv file with 4 columns, each corresponding to one variable. The title of each column will be used as the name of the variable in the script. A Pandas DataFrame with the 4 variables is created and a plot can be generated. Each axis of the plot can be selected among the variables of the DataFrame; the colormap and angle of the plot can be changed according to user defined preferences. The figure generated can be saved as .pdf.