It performs the whole process of the VO2 kinetics data analysis, which includes:
data cleaning (`detect_outliers()`

); outliers removal, interpolation, ensemble-averaging transitions and bin-avering final dataset (`process_data()`

),
and modelling VO2 kinetics (`perform_kinetics()`

). This function is a general function that will call these separate functions.
You can also call each one of them separately if you want.

## Usage

```
vo2_kinetics(
.data,
intensity_domain = c("moderate", "heavy", "severe"),
vo2_column = "VO2",
protocol_n_transitions,
protocol_baseline_length,
protocol_transition_length,
cleaning_level = 0.95,
cleaning_baseline_fit,
fit_level = 0.95,
fit_bin_average,
fit_phase_1_length,
fit_baseline_length,
fit_transition_length,
verbose = TRUE,
...
)
```

## Arguments

- .data
Data retrieved from

`read_data()`

.- intensity_domain
The exercise-intensity domain that the test was performed. Either

*moderate*,*heavy*, or*severe*.- vo2_column
The name (quoted) of the column containing the absolute oxygen uptake (VO2) data. Default to

`"VO2"`

.- protocol_n_transitions
Number of transitions performed.

- protocol_baseline_length
The length of the baseline (in seconds).

- protocol_transition_length
The length of the transition (in seconds).

- cleaning_level
A numeric scalar between 0 and 1 giving the confidence level for the intervals to be calculated during the data cleaning process. Breaths lying outside the prediction bands will be excluded. Default to

`0.95`

.- cleaning_baseline_fit
A vector of the same length as the number in

`protocol_n_transitions`

, indicating what kind of fit to perform for each baseline. Either*linear*or*exponential*.- fit_level
A numeric scalar between 0 and 1 giving the confidence level for the parameter estimates in the final VO2 kinetics fit. Default to

`0.95`

.- fit_bin_average
The bin average to be performed for the final fit.

- fit_phase_1_length
The length of the phase I that you wish to exclude from the final exponential fit, in seconds. See

`VO2 kinetics`

section for more details.- fit_baseline_length
The length the baseline to perform the final linear fit, in seconds. See

`VO2 kinetics`

section for more details.- fit_transition_length
The length of the transition to perform the final exponential fit, in seconds. See

`VO2 kinetics`

section for more details.- verbose
A boolean indicating whether messages should be printed in the console. Default to

`TRUE`

.- ...
Additional arguments passed to

`perform_kinetics()`

when fitting VO2 kinetics in the heavy- or severe-intensity domains. See`?perform_kinetics`

for more details.

## Value

a tibble containing one row and the nested columns:

- data_outliers
The raw data containing additional columns that identify breaths as outliers.

- plot_outliers
A

`patchwork`

object to display outliers from every transition.- data_processed
The processed data (time-aligned, ensembled-averaged, and bin-averaged).

- data_fitted
The data containing the time and VO2 columns, as well as the fitted data and its residuals for each data point.

- model
A

`nls`

object. The model used in the VO2 kinetics fitting.- model_summary
The tidied summary of the

`model`

.- model_residuals
The residuals of the

`model`

.- plot_model
The final plot of the fitted

`model`

.- plot_residuals
The residuals plot for the

`model`

diagnostics.

## Details

The function is a wrapper of smaller functions and has important arguments:

**protocol_**= sets arguments related to the protocol used.**cleaning_**= sets arguments related to data cleaning.**fit_**= sets arguments related to VO2 kinetics fitting.

The function works like the following sequence:

** vo2_kinetics( )**:

`detect_outliers( )`

= separates the data into the number of transitions indicated, and fits each baseline and transition phase indiviudally, retrieving the predictions bands for the level indicated. Then it recognizes breaths lying outside the prediciton bands and flag them as outliers.`plot_outliers( )`

= plots each transition identifying outliers.`process_data( )`

= It removes the outliers detected through`detect_outliers()`

, interpolates each transition, ensemble-averages all the transitions into one, performs a bin-average, and normalizes the time column (time zero will indicate the end of baseline and the start of the transition phase).`perform_kinetics( )`

= performs the VO2 kinetics fitting based on the**fit_**parameters given. It also calculates the residuals, and plots the final fit as well as residuals for model diagnostics.

## VO2 kinetics

VO2 kinetics, described as the rate of adjustment of the oxidative energy system to an instantaneous increase in the energy demand, is exponential in nature, and it is described by the oxygen uptake (VO2) time-constant (\(\tau\)VO2) (Murias, Spencer and Paterson (2014); Poole and Jones (2011)).

VO2 kinetics analysis provides understanding of the mechanisms that regulate the rate at which oxidative
phosphorylation adapts to step changes in exercise intensities and ATP requirement. This is usually accomplished
by performing step transitions from a baseline intensity to a higher work rate in either the **moderate-**, **heavy-**, or
**severe-intensity domain** (Murias et al., 2011).

Three distinct phases may be observed in the VO2 response during on-transient exercise:

**Phase I**: also termed as the cardiodynamic phase, it represents the circulatory transit delay
on the VO2 response as a result of the increase in the pulmonary blood flow that does not reflect the increase
in oxygen extraction in the active muscles. The time-window of the Phase I is determined in the ** fit_phase_1_length** argument, which will be internally passed into the

`perform_kinetics()`

function.**Phase II**: also termed as the primary component, represents the exponential increase in VO2
related to the continued increase in pulmonary and muscle blood flow. The Phase II is described by the time-constant parameter (\(\tau\))
in the mono-exponential model (see below), and it is defined as the duration of time (in seconds) for the VO2 response
to increase to 63% of the required steady-state.

**Phase III**: represents the steady-state phase of the VO2 response
during moderate-intensity exercise.

### Moderate-intensity domain

The on-transient response from baseline to a transition within the **moderate-intensity domain**
is analyzed using a **mono-exponential model**:
$$VO_{2\left(t\right)}=baseline+amplitude\cdot\left(1-e^{^{-\frac{\left(t-TD\right)}{tau}}}\right)$$

where:

`VO2(t)`

= the oxygen uptake at any given time.`baseline`

= the oxygen uptake associated with the baseline phase.`amplitude`

= the steady-state increase increase in oxygen uptake above`baseline`

.`TD`

= the time delay.\(\tau\) = the time constant defined as the duration of time for the oxygen uptake to increase to 63% of the steady-state increase.

The baseline value in the mono-exponential model is a **fixed** value and pre-determined
as the mean of the VO2 response (i.e., linear model with the slope set as zero) during the baseline phase.
The time window of the baseline period is determined in the ** fit_baseline_length** argument, which will be internally passed into the

`perform_kinetics()`

function.Diverse exercise protocols exist to determine VO2 kinetics in the moderate-intensity domain. Usually, the protocol consists of multiple transitions (typically 3 or 4) from a baseline exercise-intensity to an exercise-intensity below the gas exchange threshold (typically the power output associated with 90% of the gas exchange threshold). Bbaseline and transition phases are usually performed for 6 minutes each. The reason that 6 minutes is done for each phase is to give enough time for both to reach a steady-state response:

For example, for each multiple of the time-constant (\(\tau\)), VO2 increases by 63% of the difference between the previous \(\tau\) and the required steady-state. This means:

`1`

\(\tau\)`= 63%`

\(\Delta\).`2`

\(\tau\)`= 86%`

\(\Delta\)`[100% - 63% = 37%; (37% x 63%) + 63% = 86%]`

.`3`

\(\tau\)`= 95%`

\(\Delta\)`[100% - 86% = 14%; (14% x 63%) + 86% = 95%]`

.`4`

\(\tau\)`= 98%`

\(\Delta\)`[100% - 95% = 5%; (5% x 63%) + 95% = 98%]`

.

In practical terms, let's imagine that a given participant has a **\(\tau\) = 60 seconds**. This means that this person
would need **240 seconds** (`4 x 60`

) to reach **steady-state** (98% of the response) in the **moderate-intensity domain**. This would leave other
120 seconds (2 minutes) of transition, so the protocol of performing 6-min transitions makes sure enough time is given.

Now let's imagine that another person has a **\(\tau\) = 20 seconds**. This means that this person
would need **80 seconds** (`4 x 20`

) to reach **steady-state** (98% of the response) in the **moderate-intensity domain**.

Given that there is enough time to reach a VO2 steady-state response with 6 minutes of transition, that means that for the final fit
(when the transitions were cleaned, ensembled-averaged, and bin-averaged) there is no need to include the whole 6 minutes of the transition.
This strategy avoids superfluous sections of the steady‐state data, thus maximizing the quality of the fit during the exercise on‐transient (Bell et al., 2001).
This may be specified through the ** fit_transition_length** argument, which will be internally passed into the

`perform_kinetics()`

function.As for bin-averages in the final fit, usually the data are averaged into 5-s or 10-s bins, 5-s being the most common (Keir et al., 2014).
This may be specified through the ** fit_bin_average** argument, which will be internally passed into the

`process_data()`

function.## References

Bell, C., Paterson, D. H., Kowalchuk, J. M., Padilla, J., & Cunningham, D. A. (2001). A comparison of modelling techniques used to characterise oxygen uptake kinetics during the on-transient of exercise. Experimental Physiology, 86(5), 667-676.

Keir, D. A., Murias, J. M., Paterson, D. H., & Kowalchuk, J. M. (2014). Breath‐by‐breath pulmonary O2 uptake kinetics: effect of data processing on confidence in estimating model parameters. Experimental physiology, 99(11), 1511-1522.

Murias, J. M., Spencer, M. D., & Paterson, D. H. (2014). The critical role of O2 provision in the dynamic adjustment of oxidative phosphorylation. Exercise and sport sciences reviews, 42(1), 4-11.

Murias, J. M., Spencer, M. D., Kowalchuk, J. M., & Paterson, D. H. (2011). Influence of phase I duration on phase II VO2 kinetics parameter estimates in older and young adults. American Journal of Physiology-regulatory, integrative and comparative physiology, 301(1), R218-R224.

Poole, D. C., & Jones, A. M. (2011). Oxygen uptake kinetics. Comprehensive Physiology, 2(2), 933-996.

## Examples

```
if (FALSE) {
## get file path from example data
path_example <- system.file("example_cosmed.xlsx", package = "whippr")
## read data
df <- read_data(path = path_example, metabolic_cart = "cosmed", time_column = "t")
## VO2 kinetics analysis
results_kinetics <- vo2_kinetics(
.data = df,
intensity_domain = "moderate",
vo2_column = "VO2",
protocol_n_transitions = 3,
protocol_baseline_length = 360,
protocol_transition_length = 360,
cleaning_level = 0.95,
cleaning_baseline_fit = c("linear", "exponential", "exponential"),
fit_level = 0.95,
fit_bin_average = 5,
fit_phase_1_length = 20,
fit_baseline_length = 120,
fit_transition_length = 240,
verbose = TRUE
)
}
```