2.1.1.

Importing recordings

During FP experiments, experimenters typically collect photometry signal and behavioral tracking data using separate software packages. The FiPhA app allows importing data from various formats (.xlsx,.csv,.txt,.tsq, etc.).

2.1.2.

Spectrally resolved fiber photometry import

Prior to analysis, photometry signals collected using spectrally resolved photometry systems necessarily undergo a decomposition into signals of interest through the application of either a linear unmixing algorithm or a “summary statistic”-based option with user-defined ranges of wavelengths for optimal signal identification when using fluorophores with overlapped emission spectra (Fig. 2). FiPhA simplifies the linear unmixing step by allowing import of the raw spectrometer file, set the selected wavelength row, data row, and collection frequency, and then the import of a specific spectrometer reference file within a single interface. This spectrometer reference file contains standard fluorescence spectrograms specific to the wavelengths of the experimentally collected fluorescence signals.

Fig. 2

Import options for data collected using spectrally resolved photometry systems. (a) The linear unmixing algorithm showing a GCaMP and tdTomato fluorescence peak as well as a reference spectrum. (b) Importing data using the summary statistic option with calculating the area under the curve. (c) Dataset preview of a 900 s photometry recording session aligned with TTL pulses of five tone presentations.

The “summary statistic” option allows for the creation of a ratio of two fluorescence signals derived from user-specified wavelength ranges via application of a summary function (i.e., area under the curve, mean, and median), followed by automatic signal detrending. Spectrometer and behavioral data can then be plotted in the “preview” tab located within the “datasets” view.

2.1.3.

Import of lock-in demodulation and camera-based photometry

Data collected from the lock-in demodulation systems (e.g., TDT photometry system) are typically saved in “.tsq” or “.tev” formats, which can be imported into the FiPhA app using the “fiber photometry Gizmo” located under the “import” tab drop-down menu. Users specify the “.tsq” or “.tev” files by selection of a target directory and the desired fluorescence channel using the “available streams” drop down menu

Some FP collection systems will save the raw data as a tabular dataset in a “.xlsx” or “.csv” format. These can be easily imported into the FiPhA app using the “tabular dataset” function under the “import” tab drop-down menu. To use this feature, the header row numbers, data row numbers, collection frequencies, and workbook sheet number will need to be specified. Data can then be similarly visualized using the “preview” tab in the “datasets” view.

Previous analysis sessions using the FiPhA app can be saved as a “.rds” file and reimported using the “previous session” import option in the drop-down menu.

2.1.4.

Preview

After the data are imported into the FiPhA app, the recordings can be observed in the “preview” tab. Additional recordings can then be added by simply selecting another recording to import, which then appear as a list under the top drop-down menu. In the “preview” tab, the recording time is typically depicted on the $x$-axis, but can be changed on the left drop-down menu. Manipulating the $y$-axes can be done under the right drop-down menu. Two datasets can be viewed at once using the left and right $y$-axes.

2.1.5.

Signal analysis

Signal analysis and investigation of periodic components of a given recording’s continuous variables can be performed using the “signal analysis” tab. Selection of a dataset will produce a lag autocorrelation plot, a power density spectrum plot, and a spectrogram along with options to customize the resulting figures (Fig. 3). Lag-N autocorrelation is a measure of a signal’s correlation with a delayed (by N time points) copy of itself, while the power density spectrum and spectrogram both visualize the overall individual frequencies that contribute to a signal and how these change over time. Although FP data is a slow signal, typically collected at 25 to 30 Hz, spectral analysis can reveal oscillatory information at or below the Nyquist frequency (approximately 12 to 15 Hz). This includes important frequencies such delta waves which are indicative of slow wave sleep.¹⁶

2.1.6.

Transforms

Recordings can be combined with additional datasets from external hardware (such as behavior information derived from video recordings) after a dataset has been imported. This functionality is available under the “transform” menu. Alignment of datasets which do not begin simultaneously or those which have been recorded at different collection frequencies are addressed by nearest neighbor sampling of the behavioral dataset and concatenation of the resulting data as a new column.

Additional operations available under the “transform” menu include the ability to append two datasets (row-wise), renaming either the dataset itself or any of its constituent variables, and calculating a ratio of two dataset variables Low-pass filters can be applied in tandem with down-sampling of larger datasets. Linear scaling transformations can also be applied, which helps adjust the magnitude of a variable to that of another and is a necessary step in recreating the “robust z-score” transformation (see Sec. 2.2.3).

Photobleaching/photoswitching is a common phenomenon seen in FP experiments whereby the magnitude of fluorescent activity decreases over time [Fig. 4(a)]. To account for this effect, activity can be modeled as a decreasing function of time via linear or exponential models under the “detrending” transformation option. Model parameters may be either manually specified or estimated using least squares fits, and model residuals; predicted values can be returned. The detrended fluorescence activity (calculated by subtracting the model’s predicted values from their raw values) can then be used for subsequent analysis. A ratio of the detrended variables can be created using the “create ratio” transformation option and the signal can be visualized in the “dataset preview” tab (Fig. 4).

Fig. 3

Functions located within the signal analysis tab (a), power density spectrum (b), lag autocorrelation (c), and spectrogram.

2.1.7.

Custom scripts

Users familiar with the R programming language may optionally apply custom transformations to imported datasets before event detection. A dialog box provides a text field for users to execute snippets of code in an environment that has been set up to contain the dataset as a “data.table” object, an extension of the standard “data.frame” class in base R. Any transformations made are then carried over to the imported dataset. This functionality allows for the inclusion of complex operations in workflows that are not already features of FiPhA.

Fig. 4

Isosbestic import and photobleaching/photoswitching corrections. (a) Detrending variables is possible using either an exponential or linear model and predicted values are provided. (b) Raw data showing two signals undergoing photobleaching/photoswitching over time. (c) The corrected channels can be visualized simultaneously in the “dataset preview.” (d) A ratio of the corrected signals can be created using the “create ratio” transformation.

2.2.1.

Binary, binned, and peak events

Timestamped events

For certain experimental setups, events may not be suitably described using variables within the same dataset. In such cases, FiPhA enables users to manually input a list of start/end timestamps, which correspond to the desired events [Fig. 5(a)].

Fig. 5

Event-triggered averages for a mouse hearing five separate tone presentations. (a) Screenshot of events window depicting events being created with a 3 s baseline and 5 s after the end of the tone. (b) Visualizations of the signal can be made using different normalization methods, such as $\mathrm{\Delta }$ F/F, z-score, and the robust z-score. Equations for computing these quantities are in Sec. 2.2.2.

2.2.2.

Normalizations

The FiPhA app provides the choice of three normalization methods based on the distributional properties of the signal [Fig. 5(b)].

Robust z-score

A more robust z-score is calculated by subtracting the median percent change in intensity of the interval of interest from the observation and dividing by the median absolute deviation.¹² This method is less sensitive to outlying observations than the standard z-score, but may be difficult to interpret since its reference period is no longer centered at zero.

Fig. 6

Data analysis options for viewing event-triggered averages. (a) Normalized z-score of the data traces of all event-triggered averages calculated during five tone presentations. (b) Event heatmap of same five tone presentation. (c) Interval summaries depicting box and whisker plots of the mean values of all events for each interval and normalization scheme.

2.2.3.

Custom filters

2.2.4.

Custom interval times

Intervals of interest can be manually specified in a table, where each entry specifies the name, reference point, and start/end times in relation to the reference point. Available choices include the beginning of the event signal, the end of the event signal, the raw event signal itself, or a “beginning” variant that ensures no overlap occurs with preceding events or their intervals by adjusting the interval’s start time if necessary.

2.3.1.

Event heat maps

Heatmaps, which visualize all processed events, are produced under the “analysis” tab. Events are aligned such that their event signals all start at time zero, with options to sort events by their order, total length, or area under the curve between either the full event or two specified points [Fig. 6(b)].

2.3.2.

Dataset traces

Likewise, visualizations of averaged event responses are also available using the “analysis” tab. For a given dataset, multiple event series may be plotted simultaneously with options to also include a shaded area that represents the mean plus or minus a user-provided number of standard deviations (or standard errors).

2.3.3.

Interval summaries

Boxplots containing summary values of event interval across multiple dataset and event series can be found under the “analysis” tab. In addition to the mean interval value, the median interval value can also be plotted, as well as the area under the curve value between two time points of each event [Fig. 6(c)].

5.1.1.

Z-score

A standard z-score transformation of $x$ relative to a baseline, $r$, where $\overline{r}$ is the mean of the reference interval, and ${\sigma }_r$ is its standard deviation

5.1.2.

Delta F/F

The relative change of $x$ to a baseline, $r$, where $\overline{r}$ is the reference mean. This quantity is also often expressed as a percentage¹²

5.1.3.

Robust z-score

A robust z-score-like transformation is described by Bruno et al.,¹² which is based on medians rather than means and uses the median absolute deviation as a measure of dispersion, calculated as $\mathrm{MAD}(x)=\text{median}(|x-\text{median}(x)|)$. Consequently, this normalization is less sensitive to baseline noise, but it is not as straightforward to interpret as baseline values become centered about their median rather than their mean

5.2.1.

Linear spectral un-mixing algorithm

As described by Meng et al.,¹⁷ normalized reference spectra of each signal’s peak emission is fit to every frame of spectral data, which gives sets of linear regression coefficients as a measure of the change in fluorescence intensity over time. FiPhA’s implementation supports any number of reference spectra provided in a simple comma separated value (CSV) format with a column for wavelength bins followed by a column for each signal’s normalized response over that range of wavelengths [Fig. 2(a)].

5.2.2.

Summary statistic method

In cases where reference spectra are not available or the response in a particular range of wavelengths is of interest, an alternative method allows users to select ranges of wavelengths and calculate summaries based on them over time, such as their mean, median, or integrated area under the curve. This is essentially a simple deconvolution of the multidimensional spectrometer readout at each time point. These values can then be used in place of the linear unmixing process to determine the activity-dependent sensor values (e.g., GCaMP) versus the control fluorophore (e.g., tdTomato) values for calculating the final signal [Fig. 2(b)].

5.2.3.

Animals

All procedures related to animal use were approved by the Animal Care and Use Committee of the National Institute of Environmental Health Sciences. Animal procedures were performed in accordance with the recommendations in the Guide for the Care and Use of Laboratory animals of the National Institutes of Health (NIH).