calc_rate.ft: Calculate rate of change in oxygen from flowthrough...

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

Calculate rate of change in oxygen from flowthrough respirometry data

Description

Calculates rate of oxygen uptake or production in flowthrough respirometry data given a flowrate and delta oxygen values, which can either be directly entered, or be calculated from inflow and outflow oxygen. The function returns a single rate value from the whole dataset or a subset of it, by averaging delta oxygen values. Alternatively, multiple rate values can be returned from different regions of continuous data, or a rolling rate of a specific window size performed across the whole dataset.

Usage

calc_rate.ft(
  x = NULL,
  flowrate = NULL,
  from = NULL,
  to = NULL,
  by = NULL,
  width = NULL,
  plot = TRUE,
  ...
)

Arguments

x	numeric value or vector of delta oxygen values, a 2-column data.frame of outflow (col 1) and inflow (col 2) oxygen values, or an object of class inspect.ft.
flowrate	numeric value. The flow rate through the respirometer in volume (ul,ml,L) per unit time (s,m,h,d). The units are not necessary here, but will be specified in convert_rate.ft.
from	numeric value or vector. Defaults to NULL. The start of the region(s) over which you want to calculate the rate in either time or row units. If a vector, each value must have a paired value in to. For use with inspect.ft inputs only.
to	numeric value or vector. Defaults to NULL. The end of the region(s) over which you want to calculate the rate in either time or row units. If a vector, each value must have a paired value in from. For use with inspect.ft inputs only.
by	"time" or "row". Defaults to "time". Specifies the units of the from and by, or width value. For use with inspect.ft inputs only.
width	numeric. Calculates a rolling rate across the whole dataset of the specified width in the units specified in by. For use with inspect.ft inputs only.
plot	logical. Defaults to TRUE. Plots the data.
...	Allows additional plotting controls to be passed such as pos, quiet = TRUE, legend = FALSE, and rate.rev = FALSE.

Details

calc_rate.ft calculates rates by averaging delta oxygen values across the whole dataset, or from specified subsets of the data. The flowrate is then used to convert these average delta values to rates. There are no units involved in calc_rate.ft. This is a deliberate decision. The units of oxygen concentration and flowrate will be specified later in convert_rate.ft() when rates are converted to specific output units.

For continuous data recordings, it is recommended a data.frame containing the data be prepared via inspect.ft(), and entered as the x input.

For data not prepared like this, x can be a 2-column data.frame containing numeric values of outflow (col 1) and inflow (col 2) oxygen concentrations in that order. Alternatively, if x is a numeric value or vector it is treated as delta oxygen values (outflow oxygen concentration minus inflow oxygen concentration in the same units). In both these cases, the from, to, and by inputs are are ignored, and all delta oxygen values whether as entered or calculated from the inflow and outflow oxygen columns are converted to rates.

Specifying regions

For calculating rates over specific regions of the data, the from and to inputs in the by units of "time" (the default) or "row" can be used for inspect.ft() inputs. All delta oxygen values within this region are converted to rates, and averaged to produce a overall rate for the region (⁠$rate⁠ in the output). Multiple regions can be examined within the same dataset by entering from and to as vectors of paired values to specify different regions. In this case, ⁠$rate⁠ in the output will be a vector of multiple rates with each result corresponding to the position of the paired from and to inputs. If from and to are NULL (the default), the rate is determined over the entire dataset.

Alternatively a width input can be specified, in which case a rolling rate is calculated using this window size (in the relevant by units) across the entire dataset, and returned as a vector of rate values in ⁠$rate⁠. See here for how this might be used.

Flowrate

In order to convert delta oxygen values to a oxygen uptake or production rate, the flowrate input is required. This must be in a volume (L, ml, or ul) per unit time (s,m,h,d), for example in L/s. The units are not required to be entered here; they will be specified in ⁠[convert_rate.ft()⁠] to convert rates to specific units of oxygen uptake or production.

Plot

For rates calculated from inspect.ft inputs, a plot is produced (provided plot = TRUE) showing the original data timeseries of inflow and outflow oxygen (if present, top plot), oxygen delta values (middle or top plot) with the region specified via the from and to inputs highlighted in orange, and a close-up of this region with calculated rate value (bottom plot). If multiple rates have been calculated, by default the first is plotted. Others can be plotted by changing the pos input, e.g. plot(object, pos = 2).

Important: Since respR is primarily used to examine oxygen consumption, the delta oxygen and rate plots are by default plotted on a reverse y-axis. In respR oxygen uptake rates are negative since they represent a negative slope of oxygen against time. In these plots the axis is reversed so that higher uptake rates (i.e. more negative rates) will be higher on these plots. If you are interested instead in oxygen production rates, which are positive, the rate.rev = FALSE input can be passed in either the inspect.ft call, or when using plot() on the output object. In this case, the delta and rate values will be plotted numerically, with higher oxygen production rates higher on the plot.

Additional plotting options

If the legend or labels obscure part of the plot, they can be suppressed via legend = FALSE in either the inspect.ft call, or when using plot() on the output object. Console output messages can be suppressed using quiet = TRUE. Console output messages can be suppressed using quiet = TRUE. If axis labels or other text boxes obscure parts of the plot they can be suppressed using legend = FALSE. If axis labels (particularly y-axis) are difficult to read, las = 2 can be passed to make axis labels horizontal, andoma (outer margins, default oma = c(0.4, 1, 1.5, 0.4)), and mai (inner margins, default mai = c(0.3, 0.15, 0.35, 0.15)) used to adjust plot margins.

Background control or "blank" experiments

calc_rate.ft can also be used to determine background rates from empty control experiments in the same way specimen rates are determined. The saved objects can be used as the by input in adjust_rate.ft(). For experiments in which the specimen data is to be corrected by a concurrently-run control experiment, best option is to use this as the in.oxy input in inspect.ft(). See help file for that function, or the vignettes on the website for examples.

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 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 data frame by passing export = TRUE.

• mean(): calculates the mean of all 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 calc_rate.ft containing input parameters and data, various summary data, metadata, and the primary output of interest ⁠$rate⁠, which can be background adjusted in adjust_rate.ft or converted to units in convert_rate.ft. Note the ⁠$summary⁠ table contains linear regression coefficients alongside other metadata. These should not be confused with those in other functions such as calc_rate where slopes represent rates and coefficients such as a high r-squared are important. Here, they represent the stability of the data region, in that the closer the slope is to zero the less the delta oxygen values, and therefore rates, in that region vary. These are included to enable possible future functionality where stable regions may be automatically identified.

Examples

# Single numeric delta oxygen value. The delta oxygen is the difference
# between inflow and outflow oxygen.
calc_rate.ft(-0.8, flowrate = 1.6)

# Numeric vector of multiple delta oxygen values
ft_rates <- calc_rate.ft(c(-0.8, -0.88, -0.9, -0.76), flowrate = 1.6)
print(ft_rates)
summary(ft_rates)

# Calculate rate from entire dataset
inspect.ft(flowthrough.rd, time = 1, out.oxy = 2, in.oxy = 3, ) %>%
  calc_rate.ft(flowrate = 2.34)

# Calculate rate from a region based on time
inspect.ft(flowthrough.rd, time = 1, out.oxy = 2, in.oxy = 3, ) %>%
  calc_rate.ft(flowrate = 2.34, from = 200, to = 400, by = "time")

# Calculate rate from multiple regions
inspect.ft(flowthrough.rd, time = 1, out.oxy = 2, in.oxy = 3, ) %>%
  calc_rate.ft(flowrate = 2.34,
               from = c(200, 400, 600),
               to = c(300, 500, 700),
               by = "row") %>%
  summary()

# Calculate rate from existing delta oxygen values
inspect.ft(flowthrough.rd, time = 1, delta.oxy = 4) %>%
  calc_rate.ft(flowrate = 2.34, from = 200, to = 400, by = "time")

# Calculate rate from a background recording
inspect.ft(flowthrough_mult.rd,
           time = 1,
           out.oxy = 5,
           in.oxy = 9) %>%
  calc_rate.ft(flowrate = 0.1, from = 20, to = 40, by = "time") %>%
  summary()

# Calculate a rolling rate
inspect.ft(flowthrough_mult.rd,
           time = 1,
           out.oxy = 2,
           in.oxy = 6) %>%
  calc_rate.ft(flowrate = 0.1, width = 500, by = "row") %>%
  summary()

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