`R/calc_rate.int.R`

`calc_rate.int.Rd`

`calc_rate.int`

allows you to extract an oxygen uptake or production rate
from multiple replicates in intermittent-flow respirometry. It allows you to
easily use consistent selection parameters to extract a single rate from each
replicate, for example a specific time range or row range.

```
calc_rate.int(
x,
starts = NULL,
wait = NULL,
measure = NULL,
by = "row",
plot = TRUE,
...
)
```

- x
Object of class

`inspect`

or`data.frame`

. This is the timeseries of paired values of oxygen against time containing multiple replicates from which to calculate rates.- starts
Integer(s). Row locations or times of the start of each replicate. A single value input indicates a regular interval in rows or time units starting at the first row of the data in

`x`

. If replicates do not cycle at a regular interval, a vector of the row or time of each replicate can be entered. The function assumes each replicate ends at the row preceding the start of the next replicate, or for the final replicate the final row of the dataset.- wait
Numeric. Rows or time period to exclude at the start of each replicate. Default is

`NULL`

in which case no wait phase is applied. See Details.- measure
Numeric. Rows or time period over which to calculate rate in each replicate. Applied directly after

`wait`

phase. Default is`NULL`

in which case the entire replicate is used. See Details.- by
String.

`"row"`

or`"time"`

. Defaults to`"row"`

. Method by which`starts`

,`wait`

and`measure`

are applied.- plot
Logical. Default is

`TRUE`

. Plots the results. See 'Plotting' section for details.- ...
Allows additional plotting controls to be passed, such as

`type`

,`pos`

,`legend`

, and`quiet`

.

Output is a `list`

object of class `calc_rate.int`

containing a
`calc_rate`

object for each replicate in `$results`

. The output also
contains a `$summary`

table which includes the full rate regression results
from each replicate with replicate number indicated by the `$rep`

column.
Output also contains a `$rate`

element which contains the rate values from
each replicate in order. The function call, inputs, and other metadata are
also included. Note, that if you have many replicates this object can be
rather large (several MB).

`calc_rate.int`

uses the `starts`

input to subset each replicate. The `wait`

and `measure`

inputs control which parts of each replicate data are excluded
and included from the rate calculation. It extracts a rate from each
replicate using these, and saves it and other data to a summary table.

The `x`

input should be an`inspect`

object. Alternatively, it can be a
two-column data frame containing paired values of time and oxygen from an
intermittent-flow experiment in columns 1 and 2 respectively (though we
always recommend processing such data in `inspect()`

first). If a multiple
column dataset is entered as `x`

the first two columns are selected by
default. If these are not the intended data use `inspect`

to select the
correct time and oxygen columns.

The `starts`

input specifies the locations of the start of each replicate in
the data in `x`

. This can be in one of two ways:

A single numeric value specifying how replicates are spaced starting from the data in the first row. This option should only be used when replicates cycle at regular intervals. This can be a regular row or time interval, as specified via the

`by`

input. If the first replicate does not start at row 1, the data should be subset so that it does (see`subset_data()`

) and example here.A numeric vector of row locations or times, as specified via the

`by`

input, of the start of each individual replicate. The first replicate does not have to start at the first row of the data, and all data after the last entry is assumed to be part of the final replicate. Regular`R`

syntax such as`seq()`

,`1:10`

, etc. is also accepted, so can be used to specify both regular and irregular replicate spacing.

For both methods it is assumed each replicate ends at the row preceding the start of the next replicate, or in the case of the last replicate the final row of the dataset.

The `wait`

and `measure`

inputs are used to specify the region from which to
extract a rate and exclude flush periods. They can be entered as row
intervals or time values in the units of the input data. The `wait`

phase
controls the amount of data at the start of each replicate to be ignored,
that is not used in rate calculations. The `measure`

phase determines the
region after this over which a rate is calculated. There is no `flush`

phase
input since this is assumed to be from the end of the `measure`

phase to the
end of the replicate.

Both `wait`

and `measure`

can be entered in one of two ways:

Single numeric values specifying a row width or a time period, as specified via the

`by`

input. Use this if you want to use the*same*`wait`

and`measure`

phases in every replicate, that is extract a rate from the same region of each.If

`starts`

is a vector of locations of the start of each replicate, these inputs can also be vectors of equal length of row lengths or time periods as specified via the`by`

input. This is only useful if you want to use*different*`wait`

and/or`measure`

phases in different replicates.

If `wait = NULL`

no wait phase is applied. If `measure = NULL`

the rate is
extracted from the start of the replicate or end of the `wait`

phase to the
last row of the replicate. This will typically include the flush period, so
is rarely what you would want. Similarly if any `measure`

input is beyond the
available values in the replicate the closest value (row or time) is used
instead, which again would typically be the last row of the replicate.

See examples below for actual code, but here is a simple example. An experiment comprises replicates which cycle at ten minute intervals with data recorded every second. Therefore each replicate will be 600 rows long. Flushes of the respirometer take 3 minutes at the end of each replicate. We want to exclude the first 2 minutes (120 rows) of data in each, and measure an oxygen uptake rate for five minutes (300 rows), leaving the three minutes of flushing (180 rows) excluded. The inputs for this would be:

`starts = 600, wait = 120, measure = 300, by = "row"`

Only a single rate can be extracted from each replicate. If for some reason
you need to extract multiple rates from single replicates use `subset_data()`

and `calc_rate()`

which accepts multiple `from`

and `to`

inputs. Similarly,
the `calc_rate`

method of `by = "oxygen"`

is not supported in
`calc_rate.int`

. See vignettes on the website for examples of alternative
ways of iterating `calc_rate`

across multiple replicates if you need to get
around these constraints.

If `plot = TRUE`

(the default), the result for each replicate is plotted on a
grid up to a maximum of 20. Which replicates are plotted can be selected
using the `pos`

input (default is 1:20), either in the main function call or
when calling `plot()`

on output objects.

There are three ways of plotting the results, which can be selected using the
`type`

input:

`type = "rep"`

: The default. Each individual replicate is plotted with the rate region (i.e.`measure`

phase) highlighted in yellow. The`wait`

and`measure`

phases are also highlighted with red and green backgrounds respectively. These are also labelled if`legend = TRUE`

.`type = "full"`

: Each replicate rate (i.e.`measure`

phase) is highlighted in the context of the whole dataset. May be quite difficult to interpret if dataset is large.`type = "cr"`

: Plots individual replicate results as`calc_rate`

objects.

For all types `pos`

can be used to select which replicate(s) to plot.

Saved output objects can be used in the generic S3 functions `plot()`

,
`print()`

, `summary()`

, and `mean()`

.

`plot()`

: plots the result. See Plot section above.`print()`

: prints the result of a single replicate, by default the first. 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 the rows specified by the`pos`

input. e.g.`summary(x, pos = 1:5)`

. The`$rep`

column indicates the replicate number. The summary table can be exported as a separate data frame by passing`export = TRUE`

.`mean()`

: calculates the mean of the rates from every replicate, or the rows specified by the`pos`

input. e.g.`mean(x, pos = 1:5)`

The mean can be exported as a numeric value by passing`export = TRUE`

.

For additional help, documentation, vignettes, and more visit the `respR`

website at https://januarharianto.github.io/respR/

```
# \donttest{
# Irregular replicate structure ------------------------------------------
# Prepare the data to use in examples
# Note in this dataset each replicate is a different length!
data <- intermittent.rd
# Convert time to minutes (to show different options below)
data[[1]] <- round(data[[1]]/60, 2)
# Inspect
urch_insp <- inspect(data)
#> inspect: Applying column default of 'time = 1'
#> inspect: Applying column default of 'oxygen = 2'
#> Warning: inspect: Time values are not evenly-spaced (numerically).
#> inspect: Data issues detected. For more information use print().
#>
#> # print.inspect # -----------------------
#> Time O2
#> numeric pass pass
#> Inf/-Inf pass pass
#> NA/NaN pass pass
#> sequential pass -
#> duplicated pass -
#> evenly-spaced WARN -
#>
#> Uneven Time data locations (first 20 shown) in column: Time
#> [1] 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
#> Minimum and Maximum intervals in uneven Time data:
#> [1] 0.01 0.02
#> -----------------------------------------
# Calculate rate across each entire replicate
# This leads to erroneous rates because the flush is included
calc_rate.int(urch_insp,
starts = c(1, 2101, 3901))
#> calc_rate.int: The `measure` input is NULL. Calculating rate to the end of the replicate.
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from all replicates ...
#> -----------------------------------------
#>
#> # print.calc_rate.int # -----------------
#> Replicate 1 of 3 :
#> Rate: -0.02226147
#>
#> To see other replicate results use 'pos' input.
#> To see full results use summary().
#> -----------------------------------------
# So instead we also specify a 'measure' phase
calc_rate.int(urch_insp,
starts = c(1, 2101, 3901),
measure = 1000)
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from all replicates ...
#> -----------------------------------------
#>
#> # print.calc_rate.int # -----------------
#> Replicate 1 of 3 :
#> Rate: -0.03718777
#>
#> To see other replicate results use 'pos' input.
#> To see full results use summary().
#> -----------------------------------------
# You can even specify different 'measure' phases in each rep
calc_rate.int(urch_insp,
starts = c(1, 2101, 3901),
measure = c(1500, 1200, 200))
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from all replicates ...
#> -----------------------------------------
#>
#> # print.calc_rate.int # -----------------
#> Replicate 1 of 3 :
#> Rate: -0.03582043
#>
#> To see other replicate results use 'pos' input.
#> To see full results use summary().
#> -----------------------------------------
# We usually don't want to use the start of a replicate just after the flush,
# so we specify a 'wait' phase. We can also specify 'starts', 'wait' and
# 'measure' in units of time instead of rows.
#
# By time
# (this time we save the result)
urch_res <- calc_rate.int(urch_insp,
starts = c(0, 35, 65), # start locations in minutes
wait = 2, # wait for 2 mins
measure = 10, # measure for 10 mins
by = "time")
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from all replicates ...
#> -----------------------------------------
# Regular replicate structure --------------------------------------------
# If replicates cycle at regular intervals, 'starts' can be used to specify
# the spacing in rows or time, starting at row 1. Therefore data must be
# subset first so that the first replicate starts at row 1.
#
# Subset and inspect data
zeb_insp <- zeb_intermittent.rd %>%
subset_data(from = 5840,
to = 75139,
by = "row",
quiet = TRUE) %>%
inspect()
#> inspect: Applying column default of 'time = 1'
#> inspect: Applying column default of 'oxygen = 2'
#> inspect: No issues detected while inspecting data frame.
#>
#> # print.inspect # -----------------------
#> Time Oxygen
#> numeric pass pass
#> Inf/-Inf pass pass
#> NA/NaN pass pass
#> sequential pass -
#> duplicated pass -
#> evenly-spaced pass -
#>
#> -----------------------------------------
# Calculate a rate from same 6-minute region in every replicate.
# Replicates cycle at every 660 rows.
zeb_res <- calc_rate.int(zeb_insp,
starts = 660,
wait = 120, # exclude first 2 mins
measure = 360, # rate from 6 mins after 'wait'
plot = TRUE)
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from all replicates ...
#> plot.calc_rate.int: Plotting first 20 selected reps only. To plot others modify 'pos' input.
#> -----------------------------------------
# S3 functions ------------------------------------------------------------
# Outputs can be used in print(), summary(), and mean().
# 'pos' can be used to select replicate ranges
summary(zeb_res)
#>
#> # summary.calc_rate.int # ---------------
#> Summary of all replicate results:
#>
#> rep rank intercept_b0 slope_b1 rsq row endrow time endtime oxy endoxy rate.2pt rate
#> 1: 1 1 53.19727 -0.007846955 0.997 121 480 5960 6319 6.454643 3.568881 -0.008038333 -0.007846955
#> 2: 2 1 51.92618 -0.006842426 0.975 781 1140 6620 6979 6.821486 4.408525 -0.006721341 -0.006842426
#> 3: 3 1 53.61471 -0.006405674 0.994 1441 1800 7280 7639 6.990787 4.641354 -0.006544383 -0.006405674
#> 4: 4 1 42.13680 -0.004417965 0.989 2101 2460 7940 8299 7.160439 5.446070 -0.004775401 -0.004417965
#> 5: 5 1 40.02087 -0.003815901 0.989 2761 3120 8600 8959 7.310690 5.884345 -0.003973104 -0.003815901
#> ---
#> 101: 101 1 169.32106 -0.002245371 0.982 66121 66480 71960 72319 7.806886 6.940578 -0.002413114 -0.002245371
#> 102: 102 1 178.05763 -0.002345255 0.984 66781 67140 72620 72979 7.774163 6.875611 -0.002502929 -0.002345255
#> 103: 103 1 173.60535 -0.002263366 0.982 67441 67800 73280 73639 7.762485 6.942057 -0.002285314 -0.002263366
#> 104: 104 1 183.48426 -0.002376847 0.984 68101 68460 73940 74299 7.752016 6.930697 -0.002287798 -0.002376847
#> 105: 105 1 175.92423 -0.002254646 0.980 68761 69120 74600 74959 7.763168 6.957930 -0.002243004 -0.002254646
#> -----------------------------------------
mean(zeb_res, pos = 1:5)
#>
#> # mean.calc_rate.int # ------------------
#> Mean of rate results from entered 'pos' replicates:
#>
#> Mean of 5 replicate rates:
#> [1] -0.005865784
#> -----------------------------------------
# There are three ways by which the results can be plotted.
# 'pos' can be used to select replicates to be plotted.
#
# type = "rep" - the default. Each replicate plotted on a grid with rate
# region highlighted (up to a maximum of 20).
plot(urch_res)
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from all replicates ...
#> -----------------------------------------
# type = "full" - each replicate rate region plotted on entire data series.
plot(urch_res, pos = 1:2, type = "full")
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from selected replicates...
#> To plot others modify 'pos' input.
#> -----------------------------------------
# Of limited utility when datset is large
plot(zeb_res, pos = 10, type = "full")
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from selected replicates...
#> To plot others modify 'pos' input.
#> -----------------------------------------
# type = "cr" - the 'calc_rate' object for selected replicates in 'pos' is plotted
plot(urch_res, pos = 2, type = "cr")
#>
#> # plot.calc_rate.int # ------------------
#> plot.calc_rate.int: Plotting rate from selected replicates...
#> To plot others modify 'pos' input.
#> -----------------------------------------
# See vignettes on website for how to adjust and convert rates from calc_rate.int
# }
```