user-guide
user-guide.Rmd- Introduction
- Installation
- Getting started
- Importing datasets
- Data processing
-
Event identification
- Signal types
-
Filters
- Conditional expression
- Drop/keep first/last N events
- Shift all events by X (sec)
- Pad to minimum X (sec)
- Limit at maximum X (sec)
- Drop if shorter/longer than X (sec)
- Aggregate if within X (sec)
- Aggregate if overlapping
- Keep if N within X (sec)
- Include events before/after X (sec)
- Drop if within X (sec)
- Normalizations
- Intervals
Introduction
FiPhA (Fiber Photometry Analysis) is a suite of tools for interactively exploring and visualizing fiber photometry datasets in context of event-based neurobehavior experiments. It is capable of importing and processing data from a variety of fiber photometry systems, such as those which are camera-based (e.g., Plexon), utilize a lock-in demodulation method (e.g., Tucker-Davis Technologies), or are spectrometer-based setups.
Intervals of interest surrounding arbitrary events can be defined using a flexible system which assigns named intervals to regions relative to each event, which can then be processed and visualized in order to investigate differences in fiber photometry responses relative to the event in question.
Processed datasets, graphics, analysis results, and summary tables can be exported at various stages for further use within R using the FiPhA session objects (a structured list() of datasets that represent the internal state of FiPhA), or more generally via CSV and formatted Excel output files for import and manipulation by hand or in other software.
Installation
FiPhA was developed using R v4.2.x and RStudio v2023.x.
You can install the latest development version directly from GitHub using the devtools package in RStudio with the following commands:
# install devtools if not already
install.packages("devtools")
# download and install FiPhA package from github
devtools::install_github("mfbridge/FiPhA@pkg")Issue: namespace ‘x’ is already loaded
Depending on the R version installed, packages that are both automatically loaded by RStudio and which are sub-dependencies of FiPhA’s (e.g., rlang, xfun, etc.) may be too out of date for FiPhA’s dependencies but fail to update when navigating to Tools → Check for Package Updates…, resulting in errors like the following:
Error in loadNamespace(i, c(lib.loc, .libPaths()), versionCheck = vI[[i]]) :
namespace ‘rlang’ 1.0.2 is already loaded, but >= 1.0.6 is requiredSince these packages are always in use within RStudio, they may need
to be updated externally using the plain R GUI (in Windows, this is
found under the Start Menu entry for R and is entitled something like “R
4.2.3”). Once RGui has been opened, packages may be updated by
navigating to Packages → Update packages…, or by entering
update.packages() in the console.
[Windows] Packages on CRAN may occasionally have newer versions available in source form compared to it’s latest binary release. It is not required to build and install any dependencies from source when installing FiPhA. Warnings about Rtools not being installed can be safely ignored.
Getting started
Once FiPhA has been installed, it can be started within RStudio from the Addins menu (Addins → FiPhA → Start FiPhA), or via the console:
FiPhA::FiPhA()Importing datasets
A variety of dataset formats are supported which do not require any additional processing prior to loading via the ‘Import’ drop down menu: time series datasets in the form of *.csv (comma separated values) or *.xlsx (Microsoft Excel) files, raw tab-delimited (*.txt) spectrometer recordings, as well as lock-in demodulation data in the form of binary *.tsq/*.tsv files from Tucker-Davis Technologies’ fiber photometry system.
Previous sessions (saved via the Export tab) may also be re-loaded using this menu, in addition to a sample dataset that has been bundled with FiPhA which contains a selection of data from both an auditory tone-based experiment and running wheel experiment.
Time series data (*.csv, *.xlsx)
One or more comma-separated values or Microsoft Excel Workbooks which share a consistent format may be loaded at once by specifying their header row, first data row, sheet number (Excel only), and observation frequency (in Hz). This format is intended for time series data that has already been processed or from systems that export directly to these (such as Plexon’s camera-based system).
Tab-delimited spectrometer recordings (*.txt)
Spectrometer-based systems which export raw spectral data as tab-delimited recordings require additional processing to derive fluorescent signal data. The expected format of this data consists of tabbed columns of wavelength intensity measurements over time (it is also assumed the first column is a timestamp).
Similar to time series data, this format requires specifying header and data row numbers in addition to observation frequency and a method of processing raw spectra. Available choices for this task are a linear unmixing algorithm (for instances where a normalized reference spectra are available), as well as a summary statistic method that allows users to choose ranges of wavelengths to summarize by taking their mean response amplitude.
Summary statistic method
This method of decomposing raw spectra into usable time series allows for arbitrary selection of up to two wavelength ranges, calculating either their integrated area under the curve, mean response, or median response. A preview window allows visualization of these ranges and includes options for automatically calculating their ratio or choosing a detrending method to compensate for fluorophore photobleaching (this step may also be performed at a later stage with additional options available).
For example, tdTomato’s peak emission occurs at 581 nm, and thus a range of 576-586 nm may be suitable for capturing changes in its fluorescence.
Linear unmixing algorithm
A linear unmixing algorithm as described by Meng et al., is also available to process spectrally-resolved data. Given a normalized reference spectra of a fluorescent response, it decomposes a spectral recording into a univariate time series by taking the linear regression coefficients of the reference fitted at each point in time.
Lock-in demodulation data
Data from Tucker-Davis Technologies’ lock-in demodulation fiber photometry systems are stored in a binary format along with a directory of metadata files. An implementation of code capable of directly reading this data is available as part of FiPhA which does not depend on any additional software, although its capabilities are currently limited to features of the format that are relevant to the data streams involved in a fiber photometry recording.
After selecting a directory containing a pair of *.tsq and *.tsv files (other *.tXX files are not currently used) the user is presented with a list of available data streams depending on what was saved, such as the individual intensity channels of the recorded wavelengths (e.g., 405 nm, 465 nm, 560 nm, etc.) and LED driver channels.
Data processing
Once imported, one or more transformations may be applied to each dataset via the Transform menu. Standard data manipulations such as subsetting, appending rows, down-sampling, rescaling, and applying low-pass filters are available. Tasks more specific to problems encountered with fiber photometry data are also available, such as temporally aligning a simultaneous recording and de-trending to compensate for photobleaching phenomena.
Temporal alignment of datasets
Datasets from other sources may be unsynchronized or have been recorded at a different observation frequency. FiPhA allows users to temporally align datasets, joining variables from other recordings across time. No interpolation is performed, selecting the nearest neighbor when down-/up-sampling.
Detrending/photobleaching compensation]
When dealing with fluorescent indicators, a gradual decay in the excited light received is often observed and is compensated for by the removal of a fitted decay trend.
Available choices are linear or a nonlinear exponental decay model, and options exist to control output column(s) created by centering around zero or exporting model fits.
Linear rescaling
Transforming the scale of one variable to that of another by applying a linear transformation.
Custom scripts
For instances where more complex functionality is required, users may
develop R scripts to apply custom transformations. The code is executed
in a blank environment where a dt variable is pre-populated
with the loaded dataset in question, and at the end of execution its
contents replace that of the selected dataset. Since FiPhA utilizes the
data.table package, many common transformations can be performed in one
liners:
Example: ratio of two variables and integer scaling
Given two variables, calculating their ratios and creating a third column can be easily performed using an appropriate data.table syntax:
# dt is an existing object in this environment.
# each column can be referenced like a normal dataset variable
# in addition to a `(time)` column. names with spaces or
# special characters need to be quoted with backticks (`)
# := is an assignment operator within a data.table
dt[, `new ratio` := `numerator variable` / denominator]
# similarly, scaling a variable by some constant:
dt[, value := value / 2^16]Event identification
Processing datasets into series of events for subsequent analysis requires the user to specify an event definition. This is done by selecting the signal type, which can be one of: a binary signal, an equally-spaced bin, or list of fixed timestamps; applying optional filters to remove spurious events or condition them on other variables; describing intervals of interest relative to the event in question; and finally choosing a normalization to be applied.
Signal types
Binary signal
A binary signal definition is useful for when a dataset column contains a logical binary (0/1) signal whose initial rising edge defines the start of an event, which lasts until the falling edge of the signal the defines its end. This is often behavior data or an event pulse from an external hardware device.
Filters
Optionally, one or more filters can be applied to the “raw” events derived from the specified event signal. These can condition events based on dataset variables, keep or remove based on order or time, aggregate a spuriously firing series of event signals into a single block, and more in order to filter out spurious and unwanted events in a systematic fashion.
In the case of the filter list, new rows can be added via the right click menu.
Conditional expression
Limiting event identification to a range that is determined by the
values of particular variables is performed using any valid R
expression, where dataset variable names are variables (those containing
spaces or special characters need to be quoted with
`\backticks/grave accents```), and at least one row (by
default) or all observations within a block of observations must meet
the criteria to pass as a valid event.
Pad to minimum X (sec)
If an event is shorter than X seconds, it is padded so that it lasts a minimum of X seconds.
Limit at maximum X (sec)
Events are capped at a maximum of X seconds, and no interleaved events are created to fill longer periods.
Aggregate if within X (sec)
If a subsequent event occurs within X seconds of a previous event, they are replaced by a single event lasting up to their total span + X.
Aggregate if overlapping
If an event starts before a previous one ends, both are coalesced into one larger event, can occur via fixed events or filters.
Normalizations
A selection of normalizations are available, as certain ones may be more appropriate under particular circumstances. Each normalization is applied only to data that fall within the bounds of intervals defined for an event.
Intervals
Intervals of interest may be assigned using the table available in the event creation dialog where they are defined by: a name, type of interval (reference point), and possibly start/end times.
Before event
An interval of this type is referenced to the start of an event, so that by setting its start value to a negative number and its end value to a zero it defines an interval occurring directly prior to the actual event.
Before event, non-overlapping
Similar to the above, but if an event’s interval defined using this type would happen to overlap with a previous event (whether the actual event or an interval defined post-event), it is shortened so that it does not overlap.