convert_rate {respR}

Convert a unitless oxygen rate value to absolute, mass-specific or area-specific rate

Description

Converts a unitless rate derived from calc_rate(), calc_rate.int(), auto_rate(), auto_rate.int(), adjust_rate(), or calc_rate.bg() into an absolute rate (i.e. whole chamber or whole specimen), or mass-specific rate (i.e. normalised by specimen mass), or area-specific rate (i.e. normalised by specimen surface area) in any common unit.

Usage

convert_rate(
  x,
  oxy.unit = NULL,
  time.unit = NULL,
  output.unit = NULL,
  volume = NULL,
  mass = NULL,
  area = NULL,
  S = NULL,
  t = NULL,
  P = NULL,
  plot = FALSE,
  ...
)

Arguments

x

numeric value or vector, or object of class calc_rate, calc_rate.int, auto_rate, auto_rate.int, adjust_rate, or calc_rate.bg. Contains the rate(s) to be converted.

oxy.unit

string. The dissolved oxygen unit of the original raw data used to determine the rates in x.

time.unit

string. The time unit of the original raw data used to determine the rates in x.

output.unit

string. The output units to convert the input rates to. Should be in the correct order: "Oxygen/Time" or "Oxygen/Time/Mass" or "Oxygen/Time/Area".

volume

numeric. Volume of water in litres in the respirometer or respirometer loop.

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. Freshwater 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 converts the primary ⁠$rate⁠ element from calc_rate, calc_rate.int, auto_rate and , auto_rate.int objects, the ⁠$rate.adjusted⁠ from adjust_rate objects, and the ⁠$rate.bg⁠ from calc_rate.bg objects. Additionally, any numeric value or vector of rates can be input as x.

Respirometer volume

The volume of the respirometer is required and should be in litres (L). Note, the volume represents the effective volume of the respirometer, that is volume of water in the respirometry chamber. This is not necessarily the same as the volume of the respirometer. Typically, it is the volume of the respirometer minus the volume of the specimen. See here for help with calculating effective volumes. It also does not refer to the specimen volume.

Units

The oxy.unit of the original raw data used to calculate 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 (⁠%Air⁠) or oxygen (⁠%Oxy⁠) is supported, as are oxygen pressure units. See unit_args() for details.

The time.unit of the original raw data used to calculate the rate is also required (seconds, minutes, hours, or days).

An output.unit is also required and 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. 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.

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 entered. If not, the default value of 1.013253 bar (standard pressure at sea level) is used. In most locations which have a normal range of around 20 millibars (outside of extreme weather events), 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 function uses an internal database and 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 the rates (or a selection of them using pos), chosen using type. The default is plot = FALSE to prevent plots being produced for every single conversion.

type = "full" (the default) plots a grid of up to 20 plots with each rate highlighted on the full dataset, with the rate value in the title. Values on the axes - time (bottom), row (top), and oxygen (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 on the upper plot, and on the lower plot the output rate values in the chosen output units. Each rate is plotted against the middle of the region used to determine it. 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, and is particularly useful for results from the auto_rate linear method. The top plot is the entire data timeseries, the bottom plot the region of the data each rate regression has been fit over. 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 regression parameters, and data locations, adjustments if applied, units, and more. The ⁠$rep⁠ and ⁠$rank⁠ columns requires special notice depending on the type of experiment you have analysed or the function you used to determine the rates. For the ⁠$rank⁠ column if calc_rate was used, it is the order of rates as entered using from and to (if multiple rates were determined). For auto_rate it relates to the method input, for example it indicates kernel density ranking if the linear method was used, or ordering by rate value if lowest or highest were used. For intermittent-flow experiments analysed via calc_rate.int or auto_rate.int it indicates the ranking within each replicate as seen in the ⁠$rep⁠ column. Note that if select_rate has been used the rows in the summary table may have been reordered, including the ⁠$rep⁠ and ⁠$rank⁠ columns. The original rep and rank for each row is retained if reordering occurred.

• 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 of class convert_rate 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 regression parameters and data locations (depending on what class of object was entered), adjustments (if applied), units, and more. The ⁠$rep⁠ and ⁠$rank⁠ columns require special notice depending on the type of experiment you have analysed or the function you used to determine the rates. See the summary table description in S3 Generic Functions section above.

Examples

# Convert a single numeric rate to an absolute rate
convert_rate(0.09, oxy.unit = 'mg/l', time.unit = 's',
  output.unit = 'mg/min', volume = 1.2)

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

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

# Convert a single rate derived via calc_rate to mass-specific
x <- calc_rate(sardine.rd, from = 200, to = 1800, by = "time")
convert_rate(x, oxy.unit = '%Air', time.unit = 's',
  output.unit = 'mg/h/g', volume = 12.3, mass = 0.05,
  S =35, t = 15, P = 1.013)

# Convert multiple rates derived via auto_rate to area-specific
x <- auto_rate(sardine.rd)
rates <- convert_rate(x, oxy.unit = '%Air', time.unit = 's',
  output.unit = 'mg/h/cm2', volume = 12.3, area = 0.00005,
  S =35, t = 15, P = 1.013)
summary(rates)