---
title: "read and plot xvg file"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{xvg_files}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = FALSE
)
```

This document demonstrates how to use the **xvm** package and its functions with sample datasets and plots. It also shows how to read multiple xvg files and arrange their plots using ggpubr.
 

**Note**: Ensure dependency packages are installed:
```r
install.packages(c("ggplot2", "stringr", "ggpubr"))
```

### Load the xvm package and dependency packages
Load the xvm package:
```{r load_xvm}
# Load the xvm package
library(xvm)
```
Load other dependency packages:
```{r dependency_packages, message=FALSE, error=FALSE}
# Load dependency packages
library(ggplot2)
```
## Read a single xvg file and plot it.
### Get Example File Path
Retrieve the path to the example file included in the package:
```{r get_file_path}
# This example file is an xvg file containing RMSD data generated by GROMACS
rmsd_file_path <- system.file("extdata/rmsd.xvg", package = "xvm")
```


### Read the xvg file
```{r read_single_xvg_file}
# Read the xvg file using read_xvg() function
rmsd_data <- read_xvg(rmsd_file_path)

# The imported xvg file is stored as a list, with the list name corresponding to the file name.
names(rmsd_data)
```
The imported xvg file is stored as a list, so you can simply display the data using the `str()` function.
```{r show_xvg_content}
str(rmsd_data[[1]])
```
The list contains two elements, each storing different pieces of information:

`$data`: a data frame containing the xvg data.

`$metadata`: other detailed information about the xvg file, including:

- *title*: the main title.
- *subtitle*: the subtitle.
- *xaxis*: the label for the x-axis.
- *yaxis*: the label for the y-axis.
- *xaxis_formatted*: the x-axis label formatted to support subscripts and superscripts.
- *yaxis_formatted*: the y-axis label formatted to support subscripts and superscripts.
- *legends*: the legend labels.
- *legends_formatted*: the formatted legend labels.
- *file_path*: the path where the file is located.


### Plot the xvg data
```{r plot_single_xvg_file, dpi = 90, fig.width=5, fig.height=5}
# Plot the xvg data using plot_xvg() function
plot_xvg(rmsd_data)
```

## Read multiple xvg Files
The `read_xvg()` function can accept multiple xvg file paths as a character vector.
```{r read_multiple_xvg_files}
# Similarly, you can also read multiple types of xvg files. 
multi_file_path <- dir(system.file("extdata", package = "xvm"))

# Filter out xvg files using stringr package
library(stringr)
multi_file_path <- multi_file_path[str_detect(multi_file_path, ".xvg")]
print(multi_file_path)

# Set the full xvg file paths
multi_file_path <- file.path(system.file("extdata", package = "xvm"),
                             multi_file_path
                             )
```


### Batch read xvg files
```{r batch_read}
# Read multiple xvg files at once in batch:
multi_data <- read_xvg(multi_file_path)
names(multi_data)
```

### Inspect a single xvg file
You can view the information of a single xvg file by indexing the list:
```{r inspect_read}
# Check the first xvg file info via indexing
str(multi_data[[1]])
```

### Plot a single xvg file
```{r plot_a_single_xvg_file, dpi = 90, fig.width=5, fig.height=5}
# Plot one of the xvg files using the plot_xvg() function:
plot_xvg(multi_data[[1]])
```

### Plot multiple xvg files
Alternatively, use `lapply()` to generate plots for each xvg file:
```{r plot_multiple_xvg_file}
# Use lapply() to plot all the xvg files in batch
mutli_xvg_plots <- lapply(multi_data, plot_xvg)
```

### Arrange plots using ggpubr
Finally, arrange all plots into a single layout using the `ggarrange()` function from the ggpubr package:
```{r arrange_xvg_plots, dpi = 90, fig.width=8, fig.height=5, message=FALSE}
# Arrange the plots using ggpubr
library(ggpubr)
ggarrange(plotlist = mutli_xvg_plots)
```