wip: vignettes

pkgdown/_pkgdown.yml

@@ -3,7 +3,7 @@ template:
   bootstrap: 5
 
 development:
-  mode: auto
+  mode: devel
 
 navbar:
   structure:

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/atp_calculation.Rmd

@@ -0,0 +1,76 @@
+---
+title: "ATP calculation"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{ATP calculation}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(ceas)
+```
+
+<!--Needed to load the mchem library for correct chemical equation rendering-->
+<script>
+window.MathJax = {
+  tex: {
+    // inlineMath: [['$', '$'], ['\\(', '\\)']],
+    packages: {'[+]': ['mhchem']}
+  },
+  loader: {load: ['[tex]/mhchem']},
+};
+</script>
+<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
+<!---->
+
+![](mito_glyco_tests.png "GLYCO and MITO stress tests")
+
+\usepackage[version=4,arrows=pgf]{mhchem}
+Proton production rate (PPR):
+
+\[\text{PPR} = \frac{\text{ECAR value}}{\text{buffer}}\]
+
+\[\text{PPR}_{\text{mito}} = \frac{10^{\text{pH}-\text{pK}_a}}{1+10^{\text{pH}-\text{pK}_a}} \cdot \frac{\text{H}^+}{\text{O}_2} \cdot \text{OCR}\]
+
+Calculates the proton production from glucose during its conversion to
+bicarbonate and \ce{H+} assuming max \(\frac{\ce{H}^+}{\ce{O2}}\) of 1
+
+\[\text{PPR}_\text{glyc} = \text{PPR} - \text{PPR}_\text{resp}\]
+
+\[
+\ce{2H2 + O2 -> 2H2O}
+\]
+
+Calculates the proton production from glucose during its conversion to
+\(\ce{lactate + H+}\).
+
+Joules of ATP (JATP) production:
+
+\[
+\text{ATP}_{\text{glyc}} = \Bigl(\text{PPR}_\text{glyc} \cdot \frac{\text{ATP}}{\text{lactate}}\Bigl) + \Bigl(\text{MITO}_\text{resp} \cdot 2 \cdot \frac{\text{P}}{\text{O}_\text{glyc}}\Bigl)
+\]
+
+\[
+\frac{\text{ATP}}{\text{lactate}} = 1
+\]
+
+with \(\frac{\text{P}}{{\text{O}_\text{glyc}}}\) = 0.167 for glucose
+(0.242 for glycogen).
+
+\[
+\text{ATP}_\text{resp} =
+ \Bigl(\text{coupled MITO}_\text{resp} \cdot 2 \cdot \frac{\text{P}}{\text{O}_\text{oxphos}}\Bigl) +
+ \Bigl(\text{MITO}_\text{resp} \cdot 2 \cdot \frac{\text{P}}{\text{O}_\text{TCA}}\Bigl)
+\]
+
+with \(\frac{\text{P}}{{\text{O}_\text{oxphos}}}\) = 2.486 and
+\(\frac{\text{P}}{{\text{O}_\text{TCA}}}\) = 0.167.
+

vignettes/ceas.Rmd

@@ -0,0 +1,285 @@
+---
+title: "Getting started with CEAS"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Getting started with CEAS}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+bibliography: refs.bib
+link-citations: yes
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Setup
+
+```{r setup}
+library(ceas)
+```
+
+## Importing Seahorse rates data
+
+The `read_data` function takes a list of Excel files. An easy way to get
+such a list is to put all your data in a directory and list its contents. Here
+we use the package's internal datasets, but `list.files` will take a directory
+name as its first argument.
+
+```{r data}
+rep_list <- system.file("extdata", package = "ceas") |>
+  list.files(pattern = "*.xlsx", full.names = TRUE)
+raw_data <- readxl::read_excel(rep_list[1], sheet = 2)
+knitr::kable(head(raw_data))
+```
+
+The data requires the following columns: `r colnames(raw_data)`. The `Group`
+column needs to be in the format `biological_group<space>Assay_type` as shown
+above. Upon reading with `read_data`, the `Group` column is split into two
+`group` and `assay` columns on the space. This output format can be set in the
+Seahorse machine before starting the experiment. If you already have the data,
+this column will have to be converted to this format to work with ceas.
+
+```{r read_dataformat}
+seahorse_rates <- read_data(rep_list)
+knitr::kable(head(seahorse_rates))
+```
+
+## Calculating energetics
+
+### Partitioning data
+
+The energetics calculation workflow involves partitioning the data into its time
+point and assay intervals.
+
+```{r partition_data}
+partitioned_data <- partition_data(seahorse_rates)
+```
+
+#### Alternative data formats {.tabset}
+
+While the default options are set for an experiment with both a mitochondrial
+and glycolysis assay, if you have only a mitochondrial assay or no glycolysis
+assay, the `assay_types` list parameter can be modified to account for that.
+
+##### Mito + Glyco (our default)
+
+```{r, eval = FALSE}
+partitioned_data <- partition_data(
+  seahorse_rates,
+  assay_types = list(
+    basal = "MITO",
+    uncoupled = "MITO",
+    maxresp = "MITO",
+    nonmito = "MITO",
+    no_glucose_glyc = "GLYCO",
+    glucose_glyc = "GLYCO",
+    max_glyc = "GLYCO"
+  ),
+  basal_tp = 3,
+  uncoupled_tp = 6,
+  maxresp_tp = 8,
+  nonmito_tp = 12,
+  no_glucose_glyc_tp = 3,
+  glucose_glyc_tp = 6,
+  max_glyc_tp = 8
+)
+```
+
+##### Data in the form of @mookerjee2017:
+
+```{r, eval = FALSE}
+partitioned_data <- partition_data(
+  seahorse_rates,
+  assay_types = list(
+    basal = "MITO",
+    uncoupled = "MITO",
+    maxresp = NA,
+    nonmito = "MITO",
+    no_glucose_glyc = NA,
+    glucose_glyc = "MITO",
+    max_glyc = "MITO"
+  ),
+  basal_tp = 3,
+  uncoupled_tp = 6,
+  maxresp_tp = NA,
+  nonmito_tp = 12,
+  no_glucose_glyc_tp = NA,
+  glucose_glyc_tp = 3,
+  max_glyc_tp = 6
+)
+```
+
+##### Just Mito
+
+```{r, eval = FALSE}
+partitioned_data <- partition_data(
+  seahorse_rates,
+  assay_types = list(
+    basal = "MITO",
+    uncoupled = "MITO",
+    maxresp = "MITO",
+    nonmito = "MITO",
+    no_glucose_glyc = NA,
+    glucose_glyc = "MITO",
+    max_glyc = "MITO"
+  ),
+  basal_tp = 3,
+  uncoupled_tp = 6,
+  maxresp_tp = 8,
+  nonmito_tp = 12,
+  no_glucose_glyc_tp = NA,
+  glucose_glyc_tp = 3,
+  max_glyc_tp = 6
+)
+```
+
+####
+
+Note that the time point parameters (`maxresp_tp` and `no_glucose_glyc_tp`) also
+need to be changed accordingly.
+
+The `get_energetics` function requires pH, pK$_a$ and buffer values.
+
+```{r get_energetics}
+energetics <- get_energetics(partitioned_data, ph = 7.4, pka = 6.093, buffer = 0.10)
+```
+
+For more information on the calculations see the article on [ATP
+calculations](atp_calculation.html).
+
+## Plotting
+
+### Bioenergetic scope plot
+
+TODO: purpose of plot
+
+```{r bioscope_plot}
+(bioscope <- bioscope_plot(energetics))
+```
+
+### Rate plots {.tabset}
+
+#### Oxygen consumption rate (OCR)
+
+TODO: purpose of plot
+
+```{r ocr}
+(ocr <- rate_plot(seahorse_rates, measure = "OCR"))
+```
+
+#### Extracellular Acidification Rate (ECAR)
+
+TODO: purpose of plot
+
+```{r ecar}
+(ecar <- rate_plot(seahorse_rates, measure = "ECAR"))
+```
+
+### ATP plots {.tabset}
+
+TODO: purpose of plot
+
+#### Basal glycolysis
+
+```{r basal_glyc}
+(basal_glyc <- atp_plot(energetics, basal_vs_max = "basal", glyc_vs_resp = "glyc"))
+```
+
+#### Basal respiration
+
+```{r basal_resp}
+(basal_resp <- atp_plot(energetics, basal_vs_max = "basal", glyc_vs_resp = "resp"))
+```
+
+
+#### Max glycolysis
+
+```{r max_glyc}
+(max_glyc <- atp_plot(energetics, basal_vs_max = "max", glyc_vs_resp = "glyc"))
+```
+
+
+#### Max glycolysis
+
+```{r max_resp}
+(max_resp <- atp_plot(energetics, basal_vs_max = "max", glyc_vs_resp = "resp"))
+```
+
+### Customizing plots
+
+CEAS is designed to work with existing `ggplot2` customization functionality and
+doesn't include more than shape and size options for its plots.
+
+For example, to change the colors used in the plot, simply make the plot and
+add the custom colors you'd like:
+
+#### Colors
+
+```{r custom_colors}
+custom_colors <- c("#e36500", "#b52356", "#3cb62d", "#328fe1")
+```
+
+```{r}
+bioscope +
+ggplot2::scale_color_manual(
+  values = custom_colors
+)
+```
+
+```{r}
+ocr +
+ggplot2::scale_color_manual(
+  values = custom_colors
+)
+```
+
+#### Labels {.tabset}
+
+##### Change axis labels
+
+```{r}
+ecar +
+    ggplot2::labs(x = "Time points")
+```
+
+##### Change label size
+
+```{r}
+basal_glyc +
+    ggplot2::theme(axis.text = ggplot2::element_text(size = 20))
+```
+
+#### Editing functions
+
+We are working on making the plots as customizable as possible. However, if
+there are options that cannot be set in the calls to the plotting functions or
+with `ggplot2` functions, you can get the code used to make the plots by running
+the function name without parenthesis and modify it. Further, since every step
+in the ceas workflow provides a dataset, you can run the modified function or
+your own custom plotting functions on those datasets.
+
+```{r, eval = FALSE}
+rate_plot
+```
+
+
+```{r, results = 'asis', echo = FALSE}
+func_code <- capture.output(dput(rate_plot))
+cat("```r\n")
+cat(func_code, sep = "\n")
+cat("\n```")
+```
+
+In RStudio, you can run `utils::edit` to modify a function.
+
+```{r, eval = FALSE}
+edit(rate_plot)
+```
+
+
+
+## References