---
title: "read and plot xpm file"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{xpm_file}
  %\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 xpm files and arrange their plots using ggpubr.

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

### 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 xpm 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 xpm file containing (free energy landscape, FEL) data generated by GROMACS
gibbs_file_path <- system.file("extdata/gibbs.xpm", package = "xvm")
```
### Read the xpm file
```{r read_single_xpm_file}
# Read the xpm file using read_xpm() function
gibbs_data <- read_xpm(gibbs_file_path)

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

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

`$title`: the main title.

`$legend`: the legend labels.

`$x_label`: the label for the x-axis.

`$y_label`: the label for the y-axis.

`$color_map`: other detailed information about the xpm file, including:

`$color_values`: other detailed information about the xpm file, including:


### Plot the xpm data
```{r plot_single_xpm_file, dpi = 90, fig.width=5, fig.height=5}
# Plot the xpm data using plot_xpm() function
plot_xpm(gibbs_data)
```

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

# Filter out xpm files using stringr package
library(stringr)
multi_file_path <- multi_file_path[str_detect(multi_file_path, ".xpm")]
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 xpm files
```{r batch_read}
# Read multiple xpm files at once in batch:
multi_data <- read_xpm(multi_file_path)
names(multi_data)
```

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

### Plot multiple xpm files
Alternatively, use `lapply()` to generate plots for each xpm file:
```{r plot_multiple_xpm_File}
# Use lapply() to plot all the xpm files in batch
mutli_xpm_plots <- lapply(multi_data, plot_xpm)
```

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

### Plot pseudo-3D from xpm file
For xpm files representing free energy landscapes, xvm also provides a pseudo-3D plotting function `plot_xpm_facet()`.

The upper plot has PC1 on the x axis, G (kJ/mol) on the y axis, and the color indicates the distance in PC2.

The lower plot has PC2 on the x axis, G (kJ/mol) on the y axis, and the color represents the distance in PC1.
```{r plot_pseudo_3D, dpi = 90, fig.width=5, fig.height=5}
# Usage is similar to the plot_xpm() function
plot_xpm_facet(gibbs_data)
```

### Plot 3D scatter plot from xpm file
xvm also provides a 3D plotting function `plot_xpm_3d()` using `plotly` package.
```{r plot_3D_scatter, dpi = 90, fig.width=5, fig.height=5}
# Usage is similar to the plot_xpm() function
plot_xpm_3d(gibbs_data)
```