adjust_rate: Adjust rates to account for background respiration or oxygen...

In januarharianto/respR: Import, Process, Analyse, and Calculate Rates from Respirometry Data

Adjust rates to account for background respiration or oxygen flux.

Description

The adjust_rate function adjusts oxygen uptake or production rates (for example, as determined in calc_rate() or auto_rate()) for background oxygen use by microbial organisms, or for other removal or input of oxygen during a respirometry experiment. The function accepts numeric values, as well as regular respR objects, and data frames. See calc_rate.bg() for determining background rates, which is the recommended way of passing background rates to adjust_rate. Rates determined in calc_rate are also accepted as background rates.

Usage

adjust_rate(
  x,
  by,
  method = NULL,
  by2 = NULL,
  time_x = NULL,
  time_by = NULL,
  time_by2 = NULL
)

Arguments

x	numeric. A single numeric value, numeric vector, or object of class calc_rate, calc_rate.int, auto_rate, or auto_rate.int. This contains the experimental rate value(s) to be adjusted.
by	numeric. A single numeric value, numeric vector, or object of class calc_rate.bg or calc_rate. This is the background rate(s) used to perform the adjustment to x. Can also be a data.frame or inspect object for "concurrent", "linear" or "exponential" adjustments. See Details.
method	string. Method of background adjustment. Defaults to "mean". Other inputs are: "value", "paired", "concurrent", "linear", "exponential". See Details.
by2	numeric. Either a single numeric value, a calc_rate.bg or calc_rate object, a data.frame, or inspect object. This is the source of the second background adjustment rate, and used only for dynamic adjustments ("linear" or "exponential"). See Details.
time_x	numeric. The timestamp(s) for the rate(s) in x, if it was entered as a numeric (otherwise it is extracted from the x input object). Generally this is the midpoint of the time range over which each x rate was calculated. Used only in dynamic adjustments ("linear" or "exponential"). See Details.
time_by	numeric. The timestamp of the background correction rate in by, if it was entered as a numeric (otherwise it is extracted from the by input object). Generally the midpoint of the time range over which it was calculated. Used only in dynamic adjustments ("linear" or "exponential"). See Details.
time_by2	numeric. The timestamp of the background correction rate in by2, if it was entered as a numeric (otherwise it is extracted from the by2 input object). Generally the midpoint of the time range over which it was calculated. Used only in dynamic adjustments ("linear" or "exponential"). See Details.

Details

adjust_rate allows the rate, or multiple rates, in x to be adjusted in a number of ways, as detailed below. Note that for those methods which accept them, by and by2 inputs of class calc_rate, calc_rate.bg, data.frame or inspect can contain multiple columns of background oxygen data, as long as they share the same numeric time data in column 1. In this case, the mean of all rates calculated for all oxygen columns is used to perform adjustments (see inspect() and calc_rate.bg() to coerce data to this form). The exception to this is the "paired" method, where each rate in by (i.e. rate in each oxygen column) is paired with the rate at the same position in x and used to adjust it.

Note: take special care with the sign of the rate used for adjustments. In respR oxygen uptake rates are negative, as they represent a negative slope of oxygen against time. Background rates will normally also be a negative value, while any input of oxygen would be positive. See Examples.

Methods

There are six methods of adjustment, briefly summarised here, with more detail below:

"value" - All experimental rates in x are adjusted by a single background rate value in by.

"mean" - This is the default method. All experimental rates in x are adjusted by the mean of all background rate values in by.

"paired" - Experimental rates in x are adjusted by the background rate value at the same position in by. Therefore requires x and by to have the same number of rates.

"concurrent" - Experimental rates in x are adjusted by a background rate calculated over the same time window in the data in by. Therefore requires x and by to share the same time data and length (broadly speaking).

"linear" - The time values for experimental rates in x are used to calculate an adjustment value based on a background rate that changes linearly with respect to time over the course of an experiment. Requires two background recordings or values (by, by2), and that all data share the same time data or scale.

"exponential" - The time values for experimental rates in x are used to calculate an adjustment value based on a background rate that changes exponentially with respect to time over the course of an experiment. Requires two background recordings or values (by, by2), and that all data share the same time data or scale.

More Detail

"value" - For experiments in which the rate from a single background experiment (or any single background value) is being used to adjust one or more specimen rates. Each rate in x is adjusted by the subtracting the single value in by. x can be a numeric value, numeric vector, calc_rate, calc_rate.int, auto_rate, or auto_rate.int object. by can be a single numeric value, a calc_rate.bg object containing a single ⁠$rate.bg⁠ (i.e. calculated from a 2-column data frame of time~oxygen), or a calc_rate object containing a single ⁠$rate⁠. All other inputs should be NULL.

"mean" - For experiments in which the mean rate from multiple background experiments is being used to adjust one or more specimen rates. Each rate in x is adjusted by subtracting the mean of all background rates in by. x can be a numeric value, numeric vector, calc_rate, calc_rate.int, auto_rate, or auto_rate.int object. by can be a numeric value, numeric vector, calc_rate.bg object containing multiple ⁠$rate.bg⁠, or a calc_rate object containing multiple ⁠$rate⁠. All other inputs should be NULL. If by is a single value, this will obviously have the same output as the "value" method.

"paired" - For experiments where multiple specimen experiments are being adjusted by multiple different background rates. This is a vectorised adjustment operation: rates in x are adjusted by the background rates at the same position in by. That is, the first x adjusted by the first by, second x by second by, etc. x can be a numeric value, numeric vector, calc_rate, calc_rate.int, auto_rate, or auto_rate.int object. by can be a numeric vector of the same length, a calc_rate.bg or calc_rate object where the ⁠$rate.bg⁠ or ⁠$rate⁠ element is the same length as the rates in x to be adjusted. All other inputs should be NULL.

"concurrent" - For experiments in which one or more concurrent "blanks" or background experiments are run alongside specimen experiments. Rates in x are adjusted by a background rate calculated over the same time window in the data in by. That is, the start and end time of each x rate is used to fit a linear regression and calculate a background rate in the ⁠$dataframe⁠ in by. x must be an calc_rate, calc_rate.int, auto_rate, or auto_rate.int object. by must be a data.frame, inspect, calc_rate.bg, or calc_rate object containing time~oxygen data. If there are multiple columns of background oxygen the mean rate across the same time window in all columns is used. In calc_rate.bg and calc_rate objects the ⁠$rate.bg⁠ or ⁠$rate⁠ element is not used, only the ⁠$dataframe⁠. The x and by data must share (broadly) the same time data or scale in the same units. If the x and by data differ in length by more than 5% or some time values are not shared between the two datasets, a warning is given, but the adjustment is nevertheless performed using the available data, by using the closest matching time window in the background data.

"linear" - This is a dynamic adjustment, intended for experiments in which the background oxygen rate changes over the course of the experiment linearly with respect to time. This is typical of long duration respirometry experiments in high temperatures, where a "blank" is conducted at the start of the experiment before the specimen is put in, and again at the end after it is taken out. It requires therefore two background recordings sharing the same numeric time data or time scale, in the same units as the experiment to be adjusted. These can also be entered as two rate values with associated timestamps, which again must share the same time scale and units as the rate to be adjusted. This method can also be used in experiments in which a concurrent blank experiment is conducted alongside specimen experiments (as described in the concurrent method above), but in which the background data is deemed too noisy to fit reliable regressions over the short timescales specimen rates are determined. In this case, any two reliable segments of the background data of any duration can be used to determine how the background rate changes over the course of the experiment, and then this used to adjust specimen rates using the appropriate rate timestamps. The time~background rate linear relationship is calculated using the midpoint of the time range of the by and by2 rate regressions (or values plus timestamps). The adjustments to x rates are calculated by taking the midpoint of the time range over which it was determined and applying it to the by~by2 linear relationship. The x input can be a numeric value, numeric vector, or a calc_rate, calc_rate.int, auto_rate, or auto_rate.int object containing single or multiple rates. The by input is the first background recording or rate value, and by2 the second background recording or rate value.

While it is typical, the x rates do not necessarily need to be at intermediate timepoints to the by/by2 times. these are used only to establish a time~background rate linear relationship, which can be extrapolated before or after the time values used to calculate it. The by and by2 inputs can be a data.frame, inspect or calc_rate.bg object containing background time~oxygen data. Alternatively, the rate x, and background rates by and by2 can be entered as values, in which case the associated timepoints at which these were determined (generally the midpoint of the time range over which the linear regression was fit) must be entered as time_x, time_by, and time_by2 (these timepoints are otherwise automatically extracted from the input objects). Multiple x rates with multiple time_x timepoints can be entered and adjusted, but only one linear background rate relationship applied, that is by, by2, time_by, and time_by2 must be single numeric values in the correct units.

"exponential" - This is a dynamic adjustment, intended for experiments in which the background oxygen rate changes over the course of the experiment exponentially with respect to time. This is typical of long duration respirometry experiments in high temperatures, where a "blank" is conducted at the start of the experiment before the specimen is put in, and again at the end after it is taken out, and the background rate is found to increase exponentially. This is identical to the "linear" method (see above for requirements), except the adjustment is calculated as an exponential relationship of the form - lm(log(c(by, by2)) ~ c(time_by, time_by2)).

S3 Generic Functions

Saved output objects can be used in the generic S3 functions print(), summary(), and mean().

• print(): prints a single result, by default the first adjusted rate. Others can be printed by passing the pos input. e.g. print(x, pos = 2)

• summary(): prints summary table of all results and metadata, or those specified by the pos input. e.g. summary(x, pos = 1:5). The summary can be exported as a separate dataframe by passing export = TRUE.

• mean(): calculates the mean of all adjusted rates, or those specified by the pos input. e.g. mean(x, pos = 1:5) The mean can be exported as a separate value by passing export = TRUE.

More

For additional help, documentation, vignettes, and more visit the respR website at https://januarharianto.github.io/respR/

Value

Output is a list object of class adjust_rate containing all inputs, input rates, adjustment values, adjustment method and model (if relevant), and the primary output of interest ⁠$rate.adjusted⁠.

Examples

# Note that oxygen uptake rates are negative in respR since they represent a
# decrease in dissolved oxygen and negative slope. Typically both
# specimen rate and background rate values are negative.

# Simple background adjustment to a single rate
# This is (-7.44) - (-0.04) = -7.40
adjust_rate(x = -7.44, by = -0.04, method = "value")

# Oxygen input adjustment
# This is (-7.44) - (0.1) = -7.54
adjust_rate(x = -7.44, by = 0.1, method = "value")

# Mean background respiration correction to a single rate.
adjust_rate(x = -7.44, by = c(-0.04, -0.05, -0.06),
            method = "mean")

# Mean background respiration correction to multiple rates.
out <- adjust_rate(x = c(-7.44, -7.20, -7.67),
                   by = c(-0.04, -0.05, -0.06),
                   method = "mean")
summary(out)

# Paired background respiration correction to multiple rates.
out <- adjust_rate(x = c(-7.44, -7.20, -7.67),
                   by = c(-0.04, -0.05, -0.06),
                   method = "paired")
summary(out)

# Dynamic linear adjustment
# With a linear relationship between the 'by' and 'by2' rates,
# at the midpoint time value the adjustment to 'x' should be -0.5
adjust_rate(x = -10,
            time_x = 500,
            by = 0, by2 = -1,
            time_by = 0, time_by2 = 1000,
            method = "linear")

# Same operation to multiple rates
out <- adjust_rate(x = c(-10, -11, -12),
                   time_x = c(500, 600, 700),
                   by = 0, by2 = -1,
                   time_by = 0, time_by2 = 1000,
                   method = "linear")
summary(out)

# A complete workflow using objects instead of values.

# Extract a single replicate from the middle of the zebrafish data
# and calculate rates
zeb_rate <- subset_data(zeb_intermittent.rd,
                        from = 38300,
                        to = 38720,
                        by = "time") %>%
  inspect() %>%
  auto_rate()

# Calculate background rate at start of experiment
bg_start <- subset_data(zeb_intermittent.rd, 1, 4999, "time") %>%
  inspect() %>%
  calc_rate.bg() %>%
  print()

# Calculate background rate at end of experiment
bg_end <- subset_data(zeb_intermittent.rd, 75140, 79251, "time") %>%
  inspect() %>%
  calc_rate.bg() %>%
  print()

# Perform a dynamic linear adjustment
adjust_rate(zeb_rate, by = bg_start, by2 = bg_end,
            method = "linear") %>%
  summary()

# Note the adjustment values applied are somewhere between the
# start and end background rate values

januarharianto/respR documentation built on April 20, 2024, 4:34 p.m.