---
title: "FRApp Package Vignette: Analyzing FRAP Data"
author:
- Gioia Di Credico^[University of Trieste, gioia.dicredico@deams.units.it]
date: "`r format(Sys.Date(), '%B %d, %Y')`"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 4
vignette: >
%\VignetteIndexEntry{FRApp Package Vignette: Analyzing FRAP Data}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
FRApp is an R package designed to streamline the analysis of Fluorescence Recovery
After Photobleaching (FRAP) experiments, specifically focusing on actin dynamics in dendritic spines.
This vignette provides a comprehensive guide on using FRApp for fitting nonlinear
mixed-effects regression models and analyzing the results, briefly describing the analysis of the example data included in the package.
However, it is important to note that FRApp is not limited to the analysis of FRAP experiments only.
The package offers a versatile framework for fitting any nonlinear mixed-effects models with an asymptotic exponential functional relationship to hierarchical data in various domains.
Whether you are dealing with experimental data in biology, ecology, or any other
field where hierarchical structures are present, FRApp can be a valuable tool
for efficient model fitting and visualization.
In the FRAP experimental paradigm, the estimation of recovery curves over
time is integrated with a nested data structure of spines belonging to
neurons and neurons belonging to cultures. In the mixed-effects model
framework, this structure is modeled through random effects.
Moreover, the effect of an experimental condition, e.g., the
downregulation of the actin-binding protein CAP2 on the actin dynamics, can
be evaluated at different levels, including interactions with fixed and
random effects and the variance coefficient.
The autocorrelation structure over time can also be modeled by an
autoregressive model.
## Installating the app
To install FRApp, you can use the following command
```{r, eval=F}
install.packages("FRApp")
```
Load the library with the command
```{r}
library("FRApp")
```
You must execute this command every time you restart Rstudio.
## Data Organization and preprocessing
Users need to check that their data comply with a suitable structure for the analysis.
FRApp expects hierarchical data organized with grouping levels that uniquely
identify the hierarchical structure.
Data should be organized with hierarchical levels that, when combined, distinctively identify the units at the lowest level of the hierarchy.
Experimental conditions, if any, should be included in naming the highest
level of the hierarchy where they are applied.
As an example, the FRApp package includes sample FRAP data, which can be loaded
in R using the following code:
```{r}
data(FRAPdata)
```
The function \texttt{head} prints the first six lines of the dataset.
```{r}
head(FRAPdata)
```
The FRAP dataset uses the following naming convention to identify spines grouped
in the three nested levels:
- *Culture.id*: Identifies the culture
- *neuron*: Identifies the neuron and its genetic condition. When combined with
Culture.id, the neuron variable identifies uniquely each neuron. Here, the highest level where the experimental condition applies is neuron.
- *spine.ID*: Identifies the spine. When combined with Culture.id and neuron
identifies uniquely each spine.
Please note that using this naming convention, spines can be identified only
specifying the complete hierarchical structure, i.e. culture/neuron/spine.
Therefore, if you want to fit a model including random effects at spine level only,
you have to assign a unique name to each spine, otherwise they will not be uniquely identified.
When data are ready, they can be exported in a csv file format. Make sure that the first line of the csv file contains variable names and take note of the field and decimal separators, to allow for a proper upload of the dataset for the analysis.
## Fitting Nonlinear Mixed-Effects Regression Models
Launch the FRApp application with the command
```{r, eval = F}
FRApp()
```
{width=90%}
The application automatically opens in the browser. While the application is running, it is not possible to have access to the console. To close the application and get access to the R console again, you have to close the application by clicking on the red stop button located in the top right corner of the frame of the R console.
The application allows for:
- [Loading the data]
- [Estimating and comparing exponential mixed-effects models]
- [Printing a model report and exporting the data and the model]
### Loading the data
The FRApp application accepts the csv files format. By default, it uses the semicolon as the field separator and the period as the decimal separator, but you can select different separators from the drop-down menu.
The first line of the file must contain the variable names.
The *Browse…* button allows you to load your own data file to be analyzed. Check that your import is correct by looking on the right at the summary description of the variables and number of observations imported.
Please, double-check variable types:
- the response variable must be numeric (num)
- the explanatory variable, e.g. time, can be either integer (int) or numeric (num).
For response and explanatory variables, *factor* variable type is not allowed.
Alternatively, to showcase the functionality and usability of FRApp, the *Load example data* button allows you to load the dataset analyzed in the paper and automatically selects the specification of the final selected model.
In the case of the example data, the response variable y, the fluorescence intensity, and the explanatory variable, time, are numeric.
{width=90%}
### Estimating and comparing exponential mixed-effects models
The following list highlights the main characteristics of an exponential mixed-effects model that can be implemented in FRApp and within our FRAP example.
Model fitting is perfomed with the `nlme` function.
**Fixed effects**
For each unit, the response variable $y$ is modeled through an asymptotic regression function on time $t$, that is,
$$y_i = Asym+(R0−Asym)exp(−exp(lrc)t_i)+\epsilon_i,\quad \text{for } i = 1,...,n$$
This asymptotic function is characterized by three parameters: $R0$, the response $y$ at time $t = 0$, the horizontal asymptote $Asym$ (reached for $t \rightarrow \infty$) and the log rate constant $lrc$.
- FRApp: Begin by selecting the response variable and the explanatory variable from the drop-down menu.
- Example data: In the context of our example analysis, the fluorescence intensity $y$ was the response variable, and $time$ was the explanatory variable. The model parameters had a biological interpretation in describing the actin cytoskeleton dynamics in spines. Specifically, $R0$ represented the fluorescence intensity after photobleaching, $Asym$ denoted the fluorescence intensity recovered in time, and $lrc$ measured how fast the fluorescence intensity recovered.
**Random effects**
Mixed-effects models combine fixed effects describing the population mean and random effects accounting for variation among groups. When the data show a nested structure, the hierarchy can be easily handled specifying random effects for each level of the hierarchy. In the FRApp, random effects are assumed to be independent and normally distributed.
- FRApp: Choose the hierarchical structure levels, starting with the highest level. You can specify up to three hierarchical levels. For each specified hierarchical level, you must select at least one random effect.
There is no a priori rule for constructing the random effect structure. You can begin by defining a structure that best captures the expected variability between groups. Alternatively, you can fit the initial model with all possible random effects and adjust it by removing unnecessary random effects, i.e. those with variability almost close to zero.
- Example data: In our case, the parameters $Asym$, $lrc$, and $R0$ were expected to vary across cultures, neurons, and spines, which were organized in a hierarchical structure, i.e., spines (level 3) within neurons (level 2) within cultures (level 1). Therefore, we could specify a random effect for each level-specific parameter to capture the variability among entities belonging to the same group. For instance, the random effect on $Asym$ at the culture level described the variability among asymptotes of different cultures.
**Variance and temporal dependence**
When model residuals, which are the difference between fitted and observed values, show a non constant behavior, several variance functions can be evaluated to account for their heteroscedasticity. The temporal dependence among data can be also modeled by introducing an autoregressive (AR) additional step.
- FRApp: Select the variance function from the drop-down menu. The variance section allows you to specify different variance functions to model the heteroscedasticity of the error term. The default function is *Constant*, which represents the assumption of constant error variance. The temporal dependence section allows you to select the order of the AR model on the error term. The default value is 0, which corresponds to the uncorrelated errors structure.
- Example data: Through visual inspection of the residuals, we detected heteroscedasticity, which we modeled with a non-constant variance function. Our example data were recorded over time, so we anticipated the presence of temporal dependence among the data.
**Interactions**
Interactions with an experimental condition can be included with different model components: random effects, fixed effects, and the variance structure. Interactions allow to estimate specific effects for each experimental condition.
- FRApp: Select the variable representing the experimental condition from the drop-down menu and choose the interaction to be included in the model.
- Example data: The experimental condition, here indicated as genetic.id, was the main effect of interest in the data analyzed in the paper.
It's advisable to move from simplest structures towards greater model complexity by exploring model diagnostics including residual plots, random effects normality, and serial correlation.
You can save models for model comparison. Saved models must have different names. When multiple models are saved, the table at the bottom of the page displays comparisons among saved models as based on AIC, BIC, and likelihood ratio tests.
The *Reset model list* button allows you to delete the saved models from the list.
### Printing a model report and exporting the data and the model
From the drop-down menu in the Download section, you can select a saved model from the list and download a report and some model's objects.
You can download the model report using the *Download report* button. It includes the output shown in the app after model fitting, i.e. model summary, diagnostic plots (scatterplot of residuals vs. estimated values and quantile-quantile plot of the residuals), and the approximate 95% confidence intervals.
The *Download RData* button allows you to export an RData file containing six objects:
- data: the dataset in the format used for the analysis
- fit: the output of the estimated model
- pred: the values estimated by the model
- CI: the approximate 95% confidence intervals of the parameters of interest
- resid: the residuals of the model
- raneff: the random effects available at the different hierarchical levels.
You can open the Rdata file with RStudio, and use the included objects to create further plots including curves estimated at the different hierarchical levels (using the pred object), plots of residuals (with resid) or random effects (with raneff).
## FRAP example data analysis
In this section, we walk through our example analysis of the FRAP dataset using FRApp.
**Model 1.** We start by fitting a model with three random effects at culture level and one random effect on the $Asym$ parameter for the neuron and spine levels. We consider a constant variance function and no temporal dependence on the error term. Also we do not evaluate interactions with the genetic condition.
At the end of the estimation process, we obtain:
- a model summary that includes parameter estimates and model information;
- a scatterplot of residuals vs. estimated values and a quantile-quantile plot of the residuals, useful to assess model diagnostics. In the scatterplot, residuals should exhibit randomness, spreading approximately evenly across the range of predicted values.
In the quantile-quantile plot, a diagonal line suggests that the residuals are normally distributed;
- the approximate 95% confidence intervals of the parameters of interest.
We save this model as "Model 1" with the button *Add to model list*.
{width=90%}
**Model 2.** We update the random effect structure by fitting a model with the final random effects structure selected in the paper: three random effects at culture and spine levels and one random effect on the R0 parameter at the neuron level.
We save this model as "Model 2" with the button *Add to model list*.
Under the confidence intervals, a table showing AIC, BIC, and likelihood ratio test criteria appears. According to the showed criteria, Model 2 outperforms Model 1.
However, the residuals plot shows the presence of heteroscedasticity.
{width=90%}
**Model 3.** We fit the final model selected in the paper, by choosing the exponential function on the variance interacting with the experimental condition, and by adding an AR model of order one.
We save this model with the name "Model 3" by pressing the *Add to model list* button.
According to the criteria in the comparison table, Model 3 outperforms Model 2.
{width=90%}
We download the Model 3 report using the *Download report* button.
## References
As a reference for the construction of the model and the different options to specify, we refer to the book: Pinheiro, J., & Bates, D. (2006). Mixed-effects models in S and S-PLUS. Springer science & business media.
As a reference for the FRAP data analysis example:
Di Credico, G., Pelucchi, S., Pauli, F. et al. Nonlinear mixed-effects models to analyze actin dynamics in dendritic spines. *Scientific Reports* 15, 5790 (2025). https://doi.org/10.1038/s41598-025-87154-w