Title:	Cellular Energetics Analysis Software
Version:	1.3.0
Description:	Measuring cellular energetics is essential to understanding a matrix’s (e.g. cell, tissue or biofluid) metabolic state. The Agilent Seahorse machine is a common method to measure real-time cellular energetics, but existing analysis tools are highly manual or lack functionality. The Cellular Energetics Analysis Software (ceas) R package fills this analytical gap by providing modular and automated Seahorse data analysis and visualization using the methods described by Mookerjee et al. (2017) <doi:10.1074/jbc.m116.774471>.
URL:	https://jamespeapen.github.io/ceas/, https://github.com/jamespeapen/ceas/
BugReports:	https://github.com/jamespeapen/ceas/issues/
Imports:	data.table, ggplot2, lme4, readxl, stats
Encoding:	UTF-8
RoxygenNote:	7.3.2
License:	MIT + file LICENSE
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-12-20 21:04:58 UTC; james.eapen
Author:	Rachel House [aut, cre], James P. Eapen [aut], Hui Shen [fnd], Carrie R. Graveel [fnd], Matthew R. Steensma [fnd], Van Andel Institute [cph]
Maintainer:	Rachel House <rachel.house@vai.org>
Repository:	CRAN
Date/Publication:	2024-12-21 00:00:02 UTC

ceas: Cellular Energetics Analysis Software

Description

Measuring cellular energetics is essential to understanding a matrix’s (e.g. cell, tissue or biofluid) metabolic state. The Agilent Seahorse machine is a common method to measure real-time cellular energetics, but existing analysis tools are highly manual or lack functionality. The Cellular Energetics Analysis Software (ceas) R package fills this analytical gap by providing modular and automated Seahorse data analysis and visualization using the methods described by Mookerjee et al. (2017) doi:10.1074/jbc.m116.774471.

Author(s)

Maintainer: Rachel House rachel.house@vai.org (ORCID)

Authors:

• James P. Eapen james.eapen@vai.org (ORCID)

Other contributors:

• Hui Shen hui.shen@vai.org (ORCID) [funder]

• Carrie R. Graveel carrie.graveel@vai.org (ORCID) [funder]

• Matthew R. Steensma matthew.steensma@vai.org (ORCID) [funder]

• Van Andel Institute [copyright holder]

See Also

Useful links:

• https://jamespeapen.github.io/ceas/

• https://github.com/jamespeapen/ceas/

• Report bugs at https://github.com/jamespeapen/ceas/issues/

ATP Plot

Description

Generate the ATP Plot

Usage

atp_plot(
  energetics,
  model = "ols",
  error_bar = "ci",
  conf_int = 0.95,
  size = 2,
  shape = 16,
  basal_vs_max = "basal",
  glyc_vs_resp = "glyc",
  group_label = "Experimental group",
  sep_reps = FALSE,
  ci_method = "Wald"
)

Arguments

Details

Note: When we use the term 'max' in the package documentation we mean the maximal experimental OCR and ECAR values rather than absolute biological maximums.

Value

a ggplot

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics <- get_energetics(
  partitioned_data,
  ph = 7.4,
  pka = 6.093,
  buffer = 0.1
)
atp_plot(energetics, sep_reps = FALSE)

atp_plot(energetics, basal_vs_max = "max", sep_reps = FALSE)

atp_plot(
  energetics,
  basal_vs_max = "basal",
  glyc_vs_resp = "resp",
  sep_reps = TRUE
)
# to change fill, the geom_point shape number should be between 15 and 25
atp_plot(
  energetics,
  sep_reps = FALSE
) +
  ggplot2::scale_fill_manual(
    values = c("#e36500", "#b52356", "#3cb62d", "#328fe1")
  )

# to change color, use ggplot2::scale_color_manual
atp_plot(energetics, sep_reps = FALSE) +
  ggplot2::scale_color_manual(
    values = c("#e36500", "#b52356", "#3cb62d", "#328fe1")
  )

Bioenergetic Scope Plot

Description

Generate the Bioenergetic Scope Plot

Usage

bioscope_plot(
  energetics,
  model = "ols",
  error_bar = "ci",
  conf_int = 0.95,
  size = 2,
  basal_shape = 1,
  max_shape = 19,
  group_label = "Experimental Group",
  sep_reps = FALSE,
  ci_method = "Wald"
)

Arguments

Value

a ggplot

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics <- get_energetics(
  partitioned_data,
  ph = 7.4,
  pka = 6.093,
  buffer = 0.1
)
bioscope_plot(energetics, sep_reps = FALSE)

# to change fill, the geom_point shape should be between 15 and 20.
# These shapes are filled without border and will correctly show on the legend.
bioscope_plot(
  energetics,
  sep_reps = TRUE,
  size = 3,
  basal_shape = 2,
  max_shape = 17 # empty and filled triangle
) +
  ggplot2::scale_fill_manual(
    values = c("#e36500", "#b52356", "#3cb62d", "#328fe1")
  )

# to change color, use ggplot2::scale_color_manual
bioscope_plot(energetics, sep_reps = FALSE) +
  ggplot2::scale_color_manual(
    values = c("#e36500", "#b52356", "#3cb62d", "#328fe1")
  )

Get mean and confidence intervals from energetics mixed-effects models

Description

Runs linear mixed-effects models on the ATP measure columns from get_energetics with replicates as the random-effect. Estimates mean and confidence intervals for ATP production from glycolysis and OXPHOS at points defined in partition_data

Usage

energetics_lme_summary(atp_col, energetics, conf_int, ci_method)

Arguments

Value

a data.table with mean and the confidence interval bounds by experimental group

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics <- get_energetics(
  partitioned_data,
  ph = 7.4,
  pka = 6.093,
  buffer = 0.1
)
# Only for one column. For the full energetics table run
# `get_energetics_summary` with `model = "mixed"`.
energetics_lme_summary(
  "ATP_max_resp",
  energetics,
  conf_int = 0.95,
  ci_method = "Wald"
)

Get ordinary least squares mean and confidence intervals from energetics

Description

Helper function to calculate mean and standard deviation of ATP production from glycolysis and OXPHOS at points defined in partition_data and with values calculated using the get_energetics function. Should only be called from get_energetics_summary as the function itself only operaes on a vector without any of the grouping that get_energetics does.

Usage

energetics_ols_summary(atp_col, error_metric, conf_int)

Arguments

Value

a data.table with mean and the confidence interval bounds by experimental group

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics <- get_energetics(partitioned_data, ph = 7.4, pka = 6.093, buffer = 0.1)
# Only for one row and across all groups and replicates.
# For the full correctly grouped energetics table run
# `get_energetics_summary` with `model = "ols"`.
energetics_ols_summary(energetics$ATP_max_resp, error_metric = "ci", conf_int = 0.95)

Estimate mean and confidence intervals using a mixed-effects model

Description

Estimates mean and standard deviation of energetics or rates with replicates as the random-effect

Usage

fit_lme(
  data_col,
  input,
  group_colname = "exp_group",
  rep_colname = "replicate"
)

Arguments

Value

an lme4::lmer mixed effects model

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics <- get_energetics(partitioned_data, ph = 7.4, pka = 6.093, buffer = 0.1)
fit_lme("ATP_max_glyc", energetics)

Calculate ATP Production from OXPHOS and Glycolysis

Description

Calculates ATP production from glycolysis and OXPHOS at points defined in patitioned_data

Usage

get_energetics(partitioned_data, ph, pka, buffer)

Arguments

Details

TODO: check that all symbols are defined

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 \text{H}^+ assuming max \frac{\text{H}^+}{\text{O}_2} of 1

\text{PPR}_\text{glyc} = \text{PPR} - \text{PPR}_\text{resp}

calculates the proton production from glucose during its conversion to lactate + \text{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.

Value

a data.table of glycolysis and OXPHOS rates

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics <- get_energetics(
  partitioned_data,
  ph = 7.4,
  pka = 6.093,
  buffer = 0.1
)
head(energetics, n = 10)

Calculate ATP Production Mean and Standard Deviation

Description

Calculates mean and standard deviation of ATP production from glycolysis and OXPHOS at points defined in partition_data and with values calculated using the get_energetics function via ordinary least squares or a mixed-effects model

Usage

get_energetics_summary(
  energetics,
  model = "ols",
  error_metric = "ci",
  conf_int = 0.95,
  sep_reps = FALSE,
  ci_method = "Wald"
)

Arguments

Details

To get the means and confidence intervals for experiments with replicates, users can either use sep_reps = TRUE to get replicate-level summary statistics or set model = "mixed" to use a linear mixed-effects model on with replicate as the random-effect. The confidence intervals are generated using confint(method = "Wald").

Value

a list of groups from the data

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)
energetics_list <- get_energetics(
  partitioned_data,
  ph = 7.4,
  pka = 6.093,
  buffer = 0.1
)
energetics_summary <- get_energetics_summary(energetics_list, sep_reps = FALSE)
head(energetics_summary[, c(1:5)], n = 10)
head(energetics_summary[, c(1, 2, 6, 7)], n = 10)

Rates summary

Description

Summarize OCR and ECAR as mean and bounded standard deviations or standard error with confidence intervals

Usage

get_rate_summary(
  seahorse_rates,
  measure = "OCR",
  assay,
  model = "ols",
  error_metric = "ci",
  conf_int = 0.95,
  sep_reps = FALSE,
  ci_method = "Wald"
)

Arguments

Value

a data.table with means, standard deviations/standard error with bounds around the mean(sd or confidence intervals)

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
combined_reps <- get_rate_summary(
  seahorse_rates,
  measure = "OCR",
  assay = "MITO",
  model = "ols",
  error_metric = "ci",
  conf_int = 0.95,
  sep_reps = FALSE
)
head(combined_reps, n = 10)

# separate replicates
sep_reps <- get_rate_summary(
  seahorse_rates,
  measure = "OCR",
  assay = "MITO",
  model = "ols",
  error_metric = "ci",
  conf_int = 0.95,
  sep_reps = TRUE
)
head(sep_reps, n = 10)

# mixed effects model
reps_as_random_effects <- get_rate_summary(
  seahorse_rates,
  measure = "OCR",
  assay = "MITO",
  model = "mixed",
  error_metric = "ci",
  conf_int = 0.95,
  sep_reps = FALSE
)
head(reps_as_random_effects, n = 10)

Bioenergetic Scope Plot Shortcut

Description

Wrapper to create a 2D plot visualizing the mean and standard deviation basal and maximal ATP production from glycolysis and OXPHOS for each experimental group Create a Bioenergetic scope plot from input Seahorse Wave export, long-form rates excel files

Usage

make_bioscope_plot(rep_list, ph, pka, buffer, sheet = 2)

Arguments

Value

a ggplot

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
make_bioscope_plot(rep_list, ph = 7.4, pka = 6.093, buffer = 0.1)

Normalize Seahorse data

Description

Normalizes input data according to a sample normalization measure (e.g. cell number or \mug of protein). It assumes your data is background normalized.

Usage

normalize(
  seahorse_rates,
  norm_csv,
  norm_column = "well",
  norm_method = "minimum"
)

Arguments

Details

This normalization is distinct from the background normalization done by the Wave software. If the data are not background normalized, read_data() will output a warning showing rows with OCR, ECAR and PER values greater than 0.

Normalization Methods

When norm_method is set to "self", each OCR, ECAR, and PER value is divided by the measure it"self". OCR and ECAR values are divided by the corresponding raw value in the "measure" column: an intra-well or experimental group normalization. Each normalized value is then interpreted as pmol/min per measure (e.g. pmol/min/cell or pmol/min/\mug of protein.

When set to "minimum", each OCR, ECAR, and PER value is normalized by the minimum value in the norm_csv "measure" column. In this method, every "measure" column's value in the provided CSV file is divided by the lowest of the "measure" values to get a normalization factor for each well or experimental group. The OCR, ECAR, and PER values in each well or experimental group are divided by their corresponding normalization factors. Compared to "self", this is an inter-well/experimental group normalization based on the lowest "measure". The results may be interpreted as pmol/min per minimum of the measure (eg: group cell count or \mug of protein.)

Value

a normalized seahorse_rates data.table

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
norm_csv <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "^norm.csv", full.names = TRUE)
read.csv(norm_csv)
seahorse_rates <- read_data(rep_list, sheet = 2)
head(seahorse_rates, n = 10)
# normalize by experimental group based on the minimum cell count or protein quantity
seahorse_rates.normalized <- normalize(
  seahorse_rates,
  norm_csv,
  norm_column = "exp_group",
  norm_method = "minimum"
)
head(seahorse_rates.normalized, n = 10)

Organize Seahorse Data

Description

Organizes Seahorse OCR and ECAR rates based on defined time points (i.e. the Measurement column) during the experiment. This time point can be specified if you are modifying the Mito and Glyco Stress Test (i.e. from 3 measurements per cycle to X measurements)

Usage

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
)

Arguments

Details

Note: When we use the term 'max' in the package documentation we mean the maximal experimental OCR and ECAR values rather than absolute biological maximums.

partition_data sets up the rates data for ATP calculations by the get_energetics function. To do this, it takes a list assay_types with the named values basal, uncoupled, maxresp, nonmito, no_glucose_glyc, glucose_glyc, and max_glyc. In the default setting, it is configured for an experiment with both Mito and Glyco assays. However, partitioning can be configured for other experimental conditions.

• Only MITO data:

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 = NA
  ),
  basal_tp = 3,
  uncoupled_tp = 6,
  maxresp_tp = 8,
  nonmito_tp = 12,
  no_glucose_glyc_tp = NA,
  glucose_glyc_tp = 3,
  max_glyc_tp = NA
)

Respiratory control ratio (RCR) and glycolytic capacity (GC) assay:

partitioned_data <- partition_data(
  seahorse_rates,
  assay_types = list(
    basal = "RCR",
    uncoupled = "RCR",
    maxresp = "RCR,"
    nonmito = "RCR",
    no_glucose_glyc = NA,
    glucose_glyc = "GC",
    max_glyc = "GC"
  ),
  basal_tp = 3,
  uncoupled_tp = 6,
  maxresp_tp = 8,
  nonmito_tp = 12,
  no_glucose_glyc = NA,
  glucose_glyc_tp = 3,
  max_glyc_tp = 9
)

• Data according to Mookerjee et al. 2017 J Biol Chem;292:7189-207.

partitioned_data <- partition_data(
  seahorse_rates,
  assay_types = list(
    basal = "RefAssay",
    uncoupled = "RefAssay",
    maxresp = NA,
    nonmito = "RefAssay",
    no_glucose_glyc = "RefAssay",
    glucose_glyc = "RefAssay",
    max_glyc = NA
  ),
  basal_tp = 5,
  uncoupled_tp = 10,
  nonmito_tp = 12,
  maxresp = NA,
  no_glucose_glyc_tp = 1,
  glucose_glyc_tp = 5,
  max_glyc = NA
)

Also see the vignette.

Value

a list of named time points from each assay cycle

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
partitioned_data <- partition_data(seahorse_rates)

Rate plot

Description

Generate OCR and ECAR plots

Usage

rate_plot(
  seahorse_rates,
  measure = "OCR",
  assay = "MITO",
  model = "ols",
  error_bar = "ci",
  conf_int = 0.95,
  group_label = "Experimental group",
  linewidth = 2,
  sep_reps = FALSE,
  ci_method = "Wald"
)

Arguments

Value

a ggplot

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
rate_plot(
  seahorse_rates,
  measure = "OCR",
  error_bar = "ci",
  conf_int = 0.95,
  sep_reps = FALSE
)
rate_plot(
  seahorse_rates,
  measure = "OCR",
  error_bar = "ci",
  conf_int = 0.95,
  sep_reps = TRUE
)

Estimate mean and confidence intervals for ATP measures using a mixed-effects model

Description

Estimates mean and standard deviation of ATP production from glycolysis and OXPHOS at points defined in partition_data and with values calculated using the get_energetics function

Usage

rates_lme_summary(measure, assay, rates, conf_int, ci_method)

Arguments

Value

a list of groups from the data

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
rates_lme_summary(
  measure = "OCR",
  assay = "MITO",
  rates = seahorse_rates,
  conf_int = 0.95,
  ci_method = "Wald"
)

Read Seahorse Wave Excel File

Description

Reads input seahore data from an excel Seahorse Wave File. It assumes your data is background normalized.

Usage

read_data(
  rep_list,
  norm = NULL,
  sheet = 2,
  delimiter = " ",
  norm_column = "exp_group",
  norm_method = "minimum"
)

Arguments

Details

Although ceas enables integration of multiple biological and/or technical replicates, previous work has reported high inter-plate variation (Yepez et. al 2018). If you don't want your replicate data combined, you can either:

• make sure that the names of the common groups between the replicates are different.

• in downstream analyses (get_energetics_summary, bioscope_plot, rate_plot, atp_plot), use sep_reps = TRUE to do all calculations and plotting separately for each replicate.

NOTE: to maintain backwards compatibility sep_reps is currently FALSE by default, but will be set to TRUE in a future release.

Value

a seahorse_rates table

References

Yépez et al. 2018 OCR-Stats: Robust estimation and statistical testing of mitochondrial respiration activities using Seahorse XF Analyzer PLOS ONE 2018;13:e0199938. doi:10.1371/journal.pone.0199938

Examples

rep_list <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "*.xlsx", full.names = TRUE)
seahorse_rates <- read_data(rep_list, sheet = 2)
head(seahorse_rates, n = 10)

# normalization by well using raw cell count or protein quantity
norm_csv <- system.file("extdata", package = "ceas") |>
  list.files(pattern = "well_norm.csv", full.names = TRUE)
seahorse_rates.norm <- read_data(
  rep_list,
  norm = norm_csv,
  norm_column = "well",
  norm_method = "self",
  sheet = 2
)
head(seahorse_rates.norm, n = 10)