---
title: "Summarizing & Plotting"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Summarizing & Plotting}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r options, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "90%",
  fig.width = 6,
  fig.asp = 0.618,
  fig.align = "center",
  dpi = 300
)
```

Different measuring devices and analysis software lead to opaque results in measuring gas exchange parameters. To make exercise science more transparent and reproducible, the `spiro` package offers a standardized workflow for data from metabolic carts.

This vignette provides you information on how to summarize and plot data [previously imported and processed](https://docs.ropensci.org/spiro/articles/import_processing.html) by `spiro()`.

#### Load the data

```{r setup}
library(spiro)

# import and process example data
file <- spiro_example("zan_gxt")
gxt_data <- spiro(file)
gxt_data

```

## Stepwise summary with `spiro_summary()`

In the analysis of gas exchange data, often mean parameters for each performed load step are of interest. To ensure the presence of a metabolic steady state, the end of each step is used for calculations.

```{r spiro_summary}
spiro_summary(gxt_data, interval = 120)
```

The length of the computational interval (in seconds) can be modified with the `interval` argument. If the interval exceeds the length of any step, it will be shortened for these steps displaying a note. You can turn such messages off with setting the argument `quiet = TRUE`.

## Maximal parameter values with `spiro_max()`

For some types of exercise tests it may be preferable to get maximal values of the measured parameters (e.g., the maximum oxygen uptake VO~2max~). `spiro_max()` calculates these after smoothing the data.

```{r spiro_max}
spiro_max(gxt_data, smooth = 30)
```
The `smooth` argument controls the interval and method for the data smoothing. Different smoothing methods are available: Moving averages over fixed time intervals (e.g. `smooth = 30` for 30 seconds), moving averages over a fixed number of breaths (e.g. `smooth = "30b"` for 30 breaths) or digital filters (e.g. `smooth = "0.04fz3"` for a third-order zero-phase low-pass Butterworth filter with a cut-off frequency of 0.04 Hz). Per default the smoothing will not apply to the heart rate values, but you can enable this behavior with `hr_smooth = TRUE`.

## Plotting the data

The `spiro` package lets you visualize data from cardiopulmonary exercise testing: With `spiro_plot()` you can display the traditional Wasserman 9-Panel Plot.

```{r spiro_plot, fig.width = 10, fig.height = 8, message = FALSE}
# load example data
data <- spiro(spiro_example("zan_ramp"), hr_file = spiro_example("hr_ramp.tcx"))

spiro_plot(data)
```

You can individually select and combine panels of the 9-Panel Plot by setting the `which` argument.

```{r spiro_plot-select, fig.width = 7, fig.height = 4}
# Plot only V-Slope (Panel 5) and VO2/VCO2 over time (Panel 3)
spiro_plot(data, which = c(5,3))
```

Data over time (Panel 1,2,3,6,8,9) will be displayed smoothed, as determined via the `smooth` argument. The other panels (4,5,7) use the raw breath-by-breath data for visualization. 

You can control the appearance of the plots in `spiro_plot()`. Use the `style_args` argument to control the size and color of points and lines.

```{r spiro_plot-style-1, fig.width = 10, fig.height = 8, message = FALSE}
# Change size of points, width of lines and color of VO2 points/lines
spiro_plot(
  data, 
  style_args = list(
    size = 1,
    linewidth = 2,
    color_VO2 = "black"
  )
)
```

Use the `base_size` argument to change the plot base size. You can pass other style arguments to `ggplot::theme()` via the `style_args` argument for further customization.

```{r spiro_plot-style-2, fig.width = 10, fig.height = 8, message = FALSE}
# Change base size and axis label font
spiro_plot(
  data, 
  base_size = 9, 
  style_args = list(
    axis.title = ggplot2::element_text(face = "italic", colour = "blue")
  )
)
```