README.Rmd

---
output: github_document
markdown: kramdown

kramdown:
  input: GFM
---

<!-- badges: start -->
[![R-CMD-check](https://github.com/calico/impulse/workflows/R-CMD-check/badge.svg)](https://github.com/calico/impulse/actions)
<!-- badges: end -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
```

# Impulse

This package implements the [Chechik & Koller](https://www.ncbi.nlm.nih.gov/pubmed/19193146) impulse model using TensorFlow to improve scaleability and allow for the introduction of priors which improve model interpretability. This model describes timeseries data using two sigmoidal responses which are sufficient to capture the dynamics of many biological perturbations. While this model was formulated to capture biological dynamics, the model is generally suitable for any kind of saturation behavior described by half-max value(s) and asymptote(s).

The core functionality of **impulse** is:

- Simulate timecourse parameters and resulting timecourses
- Fit sigmoid and impulse models to timecourses with or without priors on kinetic parameters
- Compare sigmoid and impulse models
- Visualize measurements and parametric fits

## The models

This package revolves around two phenomenological models, the sigmoid (single response) and impulse (double sigmoid). The plot below highlights the value of these models. It is easy to mentally convert between timecourses and kinetic paramters, but the kinetic parameters are generally more meaningful since they indicate the timing and magnitdue of responses.

A sigmoid with parameters {t_rise = 25, v_inter = 3, rate = 0.25} and an impulse with two additional parameters {t_fall = 45, v_final = -3} are shown. The t_rise of 25 indicates a half-max time of 25 and v_inter of 3 indicates saturation at 3. In the impulse model there is a second response with a half-max time of 45 and final asymptote at -3.

```{r sigmoid_impulse_compare, echo = FALSE, message = FALSE, warning = FALSE}
library(dplyr)
library(ggplot2)
library(impulse)

sigmoid_impulse_plot <- function(timecourse_parameters) {
  
  fit_timecourse(timecourse_parameters, model = "sigmoid", fit.label = "sigmoid") %>%
    dplyr::left_join(fit_timecourse(timecourse_parameters, model = "impulse", fit.label = "impulse"), by = "time") %>%
    tidyr::gather(eqtn, level, -time) %>%
    ggplot(aes(x = time, y = level, color = eqtn)) +
    geom_path(size = 2) +
    scale_color_brewer("Model", palette = "Set2", breaks = c("sigmoid", "impulse")) +
    scale_y_continuous("Response", breaks = seq(-3, 3)) +
    scale_x_continuous("Time") +
    theme_bw() +
    theme(text = element_text(size = 15), legend.position = "top")
}

sigmoid_impulse_plot(tibble(t_rise = 25, rate = 0.25, v_inter = 3, v_final = -3, t_fall = 45))
```

### sigmoid

![Sigmoid](https://github.com/calico/impulse/blob/master/man/figures/sigmoid.png)

### implulse

![Impulse](https://github.com/calico/impulse/blob/master/man/figures/impulse.png)

## *Impulse* functionality

### Fitting Data

The primary functionality in this package is fitting parametric models to user-supplied timecourses. The vignette *fitting-timecourses* simulates time series, fits multiple models to each timecourse and then determines the model that best fits each timecourse.

### Formulating priors

The most important contribution of this work is applying priors to impulse models since there are natural constraints on parameter values which should hold (non-negative rates, non-negative times, rise before fall). When these constraints are violated, a good fit may occur, but interpretability of timing and effect sizes will be lost. The vignette *setting_priors* describes how to formulate the priors and can be used to guide the tuning of parameters for other application.

## Installation

The package can be installed from GitHub using:

```{r, eval=FALSE}
# install.packages("devtools")
remotes::install_github('calico/impulse')

# for vignettes
remotes::install_github('calico/impulse', build = TRUE, build_opts = c("--no-resave-data", "--no-manual"))
```

The package utilizes TensorFlow for parameter fitting so a python distribution is required for use. This can be configured using any of the methods discussed in [R-TensorFlow](https://github.com/rstudio/tensorflow), but using Conda (e.g., [Miniconda](https://docs.conda.io/en/latest/miniconda.html)) is straight-forward to configure. Conda can be installed using:

```{r, eval = FALSE}
remotes::install_github('rstudio/reticulate')
reticulate::install_miniconda()
```

Once conda and impulse are installed, A conda environment configured with TensorFlow can be created using:

```{r, eval=FALSE}
auto_config_tf()
```

Alternatively, create a minimal environment with:

```{bash venv_setup, eval = FALSE}
<<PATH TO PYTHON BINARY>> -m venv .venv
source .venv/bin/activate
pip install --upgrade pip wheel setuptools ipykernel
pip install -r requirements.txt
```

Where, requirements.txt is just:

```{bash requirements, eval = FALSE}
tensorflow==2.9.*
numpy==1.23.*
tensorflow-probability==0.17.*
```