Automatically determine rate of change in oxygen concentration over time

Source: R/auto_rate.R

auto_rate automatically performs a rolling regression on a data frame to determine the most linear, maximum, minimum, or interval rate of change in oxygen concentration over time. First, a rolling regression of specified width is performed on the entire dataset to obtain all possible values. The computations are then ranked (or, arranged), based on the "method" argument, and the output is summarised.

auto_rate(df, width = NULL, by = "row", method = "linear", plot = TRUE)

Arguments

df

data frame, or object of class adjust_rate. This is the data to process.
width

numeric. Width of the rolling regression. Defaults to floor(0.2*length of data) if NULL. The length of data can either be time or row, as defined by the by argument. If a number is supplied and it is less than 1, the function automatically applies the equation floor(width * length of data. Otherwise it will simply use the number as the width.
by

string. "row" or "time". Defaults to "row". However, if the function detects an irregular time series, a warning will be issued to recommend changing this argument to "time". In most cases "row" is used by default as it is efficient. Switching to "time" causes the function to perform checks for irregular time at every iteration of the rolling regression, even if time is evenly spaced, which adds to computation time.
method

string. "linear", "max", "min" or "interval". Defaults to linear. Note that if "linear" is selected, the argument width will be set to default.
plot

logical. Defaults to TRUE. Plot the results.

Value

A list object of class auto_rate.

Details

Units

There are no units of measurement involved in auto_rate(). This is a deliberate decision. Units are called in a later function when absolute and/or mass-specific rates of oxygen use are computed in convert_rate() and convert_DO().

Ranking algorithms

At present, auto_rate() contains four ranking algorithms that can be called with the argument method:

  • linear: Uses kernel density estimation (KDE) to detect the "most linear" sections of the timeseries. This is achieved by using the smoothing bandwidth of the KDE to re-sample the "peaks" in the KDE to determine linear regions in the data.

  • max: regressions are arranged from highest values, to the lowest.

  • min: regressions are arranged from lowest values, to the highest.

  • interval: non-overlapping regressions are extracted from the rolled regrssions. They are not ranked.

Examples

# most linear section of the entire data
data("flowthrough.rd")

#> Warning: data set ‘flowthrough.rd’ not found
auto_rate(flowthrough.rd)

#> Error in auto_rate(flowthrough.rd): could not find function "auto_rate"

# LONG EXAMPLES
if (FALSE) {
data("sardine.rd")
# what is the lowest rate over a 10 minute (600s) period?
auto_rate(sardine.rd, method = "min", width = 600, by = "time")
# what is the highest rate over a 10 minute (600s) period?
auto_rate(sardine.rd, method = "max", width = 600, by = "time")
}