convert_rate.ft: Convert a unitless oxygen rate value from flowthrough...

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

Convert a unitless oxygen rate value from flowthrough respirometry to absolute, mass-specific or area-specific rates

Description

convert_rate.ft converts a unitless rate derived from calc_rate.ft() or adjust_rate.ft() into an absolute rate (i.e. whole specimen or whole chamber), mass-specific rate (i.e. normalised by specimen mass), or area-specific rate (i.e. normalised by specimen surface area) in any common unit. These should be rates calculated as an oxygen delta (inflow minus outflow oxygen) multiplied by the flowrate.

Usage

convert_rate.ft(
  x,
  oxy.unit = NULL,
  flowrate.unit = NULL,
  output.unit = NULL,
  mass = NULL,
  area = NULL,
  S = NULL,
  t = NULL,
  P = 1.013253,
  plot = FALSE,
  ...
)

Arguments

x	numeric value or vector, or object of class calc_rate.ft() or adjust_rate.ft(). Contains the rate(s) to be converted.
oxy.unit	string. The dissolved oxygen units of the original raw data used to determine the rate in x.
flowrate.unit	string. The units of the flowrate through the respirometer. See Details.
output.unit	string. The output unit to convert the input rate to. Should be in the correct order: "Oxygen/Time" or "Oxygen/Time/Mass" or "Oxygen/Time/Area".
mass	numeric. Mass/weight in kg. This is the mass of the specimen if you wish to calculate mass-specific rates.
area	numeric. Surface area in m^2. This is the surface area of the specimen if you wish to calculate surface area-specific rates.
S	numeric. Salinity (ppt). Defaults to NULL. Used in conversion of some oxygen units. Fresh water should be entered as S = 0.
t	numeric. Temperature(°C). Defaults to NULL. Used in conversion of some oxygen units.
P	numeric. Pressure (bar). Used in conversion of some oxygen units. Defaults to a standard value of 1.013253 bar.
plot	logical. Default is FALSE. Controls if a plot is produced. See Plot section.
...	Allows additional plotting controls to be passed. See Plot section.

Details

By default, convert_rate.ft converts the ⁠$rate⁠ element from calc_rate.ft objects, or the ⁠$rate.adjusted⁠ element from adjust_rate.ft objects if these are entered as the x input. Alternatively, a numeric value or vector of rates can be input as x.

Units

The oxy.unit of the original raw data used to calculated the rate is required. Concentration units should use only SI units (L or kg) for the denominator, e.g. "mg/L", "mmol/kg". Percentage saturation of air or oxygen is accepted, as are oxygen pressure units. See unit_args() for details.

An output.unit is also required. If left NULL, The default of "mgO2/h" is used, or "mgO2/h/kg" or "mgO2/h/m2" if a mass or area respectively has been entered. The output.unit must be in the sequence Oxygen-Time (e.g. "mg/h") for absolute rates, Oxygen-Time-Mass (e.g. "mg/h/kg") for mass-specific rates, and Oxygen-Time-Area (e.g. "mg/h/cm2") for surface area-specific rates.

Note, some oxygen input or output units require temperature (t) and salinity (S) to perform conversions. For freshwater experiments, salinity should be entered as zero (i.e. S = 0).

Strictly speaking the atmospheric pressure (P) should also be supplied. If not, the default value of 1.013253 bar (standard pressure at sea level) is used. In most locations which have a normal range (outside extreme weather events) of around 20 millibars, any variability in pressure will have a relatively minor effect on dissolved oxygen, and even less on calculated rates. However, we would encourage users to enter the actual value if they know it, or use historical weather data to find out what it was on the day. See unit_args() for details.

The flowrate.unit is required and should be the units of the flowrate used in calc_rate.ft to calculate the rate, and should be in the form of volume (L, ml, or ul) per unit time (s,m,h,d), for example in "L/s". Note, the volume component does NOT represent the volume of the respirometer, and the time component does NOT represent the units or recording interval of the original raw data.

The function uses a fuzzy string matching algorithm to accept various unit formatting styles. For example, "mg/l", "mg/L", "mgL-1", "mg l-1", "mg.l-1" are all parsed the same. See unit_args() for details of accepted units and their formatting. See also convert_val() for simple conversion between non-oxygen units.

Plot

Plotting provides three ways of visualising converted rates (or a selection of them using pos), chosen using type. This is mostly useful only if you have extracted multiple rates (see calc_rate.ft()). The default is plot = FALSE to prevent plots being produced for every single conversion. convert_rate.ft objects can only be plotted if and inspect.ft object was used as the input in calc_rate.ft. In other words, converted rates from numeric inputs cannot be plotted.

type = "full" (the default) plots a grid of up to 20 plots with each rate (i.e. region of averaged delta values) highlighted on a plot of delta oxygen values, with the converted rate value in the title. Values on the axes - time (bottom), row (top), and oxygen delta (left) - are in the units of the original raw data. Rates are plotted in order of how they appear in the summary table up to the first 20 rows, unless different rows have been specified via pos.

type = "rate" plots the entire data timeseries, that is the outflow and inflow oxygen (if used) on the upper plot, with delta oxygen on the middle plot or as the upper plot if delta oxygen values have been entered in inspect.ft. The lower plot is the output rate values in the chosen output units. Each rate is plotted against the middle of the region used to determine it (i.e. region of averaged delta values). pos can be used to select a range of rates (i.e. summary table rows) to show in the lower plot (default is all).

type = "overlap" visualises where regression results in the summary table occur in relation to the original dataset to help understand how they are distributed or may overlap. The top plot is the entire data timeseries, that is the outflow and inflow oxygen (if used) on the upper plot, with delta oxygen on the middle plot or as the upper plot if delta oxygen values have been entered in inspect.ft. The bottom plot is the region of the data each rate has been calculated over (i.e. region of averaged delta values). The y-axis represents the position (i.e. row) of each in the summary table descending from top to bottom. If no reordering or selection has been performed, this will usually be equivalent to the ⁠$rank⁠ column, but note as reordering or selection is performed rank and summary table position will not necessarily be equivalent. One result (summary table row) can be highlighted, the default being highlight = 1. pos can be used to select a range of summary rows to plot in the lower overlap plot.

Other options:

legend = FALSE will suppress plot labels, pos selects summary rates to plot, quiet suppresses console messages.

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 converted rate. Others can be printed by passing the pos input. e.g. print(x, pos = 2)

• summary(): prints the output ⁠$summary⁠ table of converted rates and metadata. Specific rows can be specified with the pos input. e.g. summary(x, pos = 1:5). This can be exported as a separate data frame by passing export = TRUE, and includes all rate parameters, data locations, adjustments if applied, units, and more. 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, slope represents the stability of the data region, in that the closer the slope is to zero, the less the delta oxygen values in that region vary, which is an indication of a region of stable rates. They are included to enable possible future functionality where stable regions may be automatically identified, and should generally be ignored. However, advanced users can use regular R syntax to explore and subset the results using these if they wish.

• mean(): calculates the mean of all converted 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 containing the ⁠$rate.input⁠, and converted rate(s) in ⁠$rate.output⁠ in the ⁠$output.unit⁠, as well as inputs and summary elements. Note, ⁠$rate.abs⁠ is the absolute rate in the output unit minus the mass- or area-specific component. The ⁠$summary⁠ table element contains all rate parameters and data locations (depending on what class of object was entered), adjustments (if applied), units, and more.

Examples

# Convert a single numeric rate to an absolute rate
convert_rate.ft(-0.09, oxy.unit = 'mg/l', flowrate.unit = 'L/s',
                output.unit = 'mg/min')

# Convert a single numeric rate to a mass-specific rate
convert_rate.ft(-0.09, oxy.unit = 'mg/l', flowrate.unit = 'L/s',
                output.unit = 'mg/min/kg', mass = 0.5)

# Convert a single numeric rate to an area-specific rate
convert_rate.ft(-0.09, oxy.unit = 'mg/l', flowrate.unit = 'L/s',
                output.unit = 'mg/min/cm2', area = 0.0002)

# Full object-oriented workflow
# Inspect, calculate rate, adjust rate, and convert
# to a final mass-specific rate
inspect.ft(flowthrough_mult.rd,
           time = 1,
           out.oxy = 2,
           in.oxy = 6) %>%
  calc_rate.ft(flowrate = 0.1,
               from = 30,
               to = 60,
               by = "time") %>%
  adjust_rate.ft(by = -0.032) %>%
  convert_rate.ft(oxy.unit = '%Air',
                  flowrate.unit = 'L/min',
                  output.unit = 'mg/h/g',
                  mass = 0.05,
                  S =35, t = 15, P = 1.013)

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