---
title: "2. Construct the potential landscapes from simulation results"
author: "Jingmeng Cui"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{2. Construct the potential landscapes from simulation results}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(simlandr)
```

# Introduction

Here comes the central purpose of `simlandr`: constructing the potential landscapes from simulation results. 

The landscape function is calculated based on the steady-state distribution of the system:

$$U = -\ln P_\textrm{SS}$$

My colleagues and I are writing a paper about the detail of this method. I will put the link here as soon as we finish that.

`simlandr` provides a set of tools to construct 2d, 3d, and 4d landscapes from single or multiple simulation results. These methods will be illustrated in the following sections.

------

Frequently used parameters for the family of landscape functions:

`x`,`y`,`z`,`rols`,`cols`,`fr`: the variable names for plot dimensions;
`from`,`to` (for 2d landscapes), `lims` (for 3d and 4d landscapes): the range of axes;
`adjust` (for 2d landscapes), `h` (for 3d and 4d landscapes): the level of smoothness;
`Umax`: the maximum displayed value of potential.

------


# Single simulation landscape

The landscapes in this section are only from a single simulation. We first make a simulation series for illustration.

```{r}
single_test <- sim_fun_test(
  par1 = list(var1 = 1),
  par2 = list(var2 = 1, var3 = 0)
)
```

The result of the landscape functions is a `landscape` object, which contains the landscape plot as well as the smooth distributions that are used to calculate the landscapes. Plots without z-axis are built with `ggplot2` package, while plots with z-axis are built with `plotly` package. These plots can also be modified using `ggplot2` or `plotly` functions. 

You can use `plot(l)` to access those plots. For some types of `landscape`s, there are multiple types of plots available. Use `plot(l, index = 2)` or `plot(l, index = 3)`, etc. to access those plots.

Below are the examples of available plots. The meaning of the parameters can be found on the helping page of each function.

## 2d (x, y) plot

```{r}
l_single_2d <- make_2d_density(single_test, x = "out1", from = -2, to = 2, adjust = 1)
plot(l_single_2d)
```

## 3d (x, y, z) or (x, y, color) plot 

```{r}
l_single_3d <- make_3d_static(single_test, x = "out1", y = "out2", lims = c(-3, 3, -3, 3), h = 0.01, kde_fun = "ks")

plot(l_single_3d, 1)

plot(l_single_3d, 2)
```


## 4d (x, y, z, color) plot

```{r}
l_single_4d <- make_4d_static(single_test, x = "out1", y = "out2", z = "out3", lims = c(-3, 3, -3, 3, -3, 3), h = 0.01)
plot(l_single_4d) %>% plotly::layout(scene = list(zaxis = list(range = c(-3, 3))))
```


# Multiple simulation landscape

The landscapes in the section are built from batch simulation results. The following two data sets will be used to illustrate the functions. The difference is that `batch_test_result` only contains one varying parameter, whereas `batch_test_result2` contains two.

```{r}
batch_test <- new_var_set()

batch_test <- batch_test %>%
  add_var("par2", "var3", 0, 0.5, 0.1)

batch_test_grid <- make_var_grid(batch_test)

batch_test_result <- batch_simulation(batch_test_grid, sim_fun_test,
  default_list = list(
    par1 = list(var1 = 0),
    par2 = list(var2 = 0, var3 = 0)
  ),
  bigmemory = FALSE
)
batch_test_result

batch_test2 <- new_var_set()
batch_test2 <- batch_test2 %>%
  add_var("par1", "var1", -0.2, 0.2, 0.2) %>%
  add_var("par2", "var2", -0.2, 0.2, 0.2)
batch_test_grid2 <- make_var_grid(batch_test2)

batch_test_result2 <- batch_simulation(batch_test_grid2, sim_fun_test,
  default_list = list(
    par1 = list(var1 = 0),
    par2 = list(var2 = 0, var3 = 0)
  ),
  bigmemory = FALSE
)
batch_test_result2
```

Below are the examples of available plots.

## 2d (x, y) plot series with one varying parameter or plot matrix with two varying parameters

```{r}
l_batch_2d_m1 <- make_2d_matrix(batch_test_result, x = "out1", cols = "var3", from = -3, to = 3, adjust = 0.1)
plot(l_batch_2d_m1)

l_batch_2d_m2 <- make_2d_matrix(batch_test_result2, x = "out1", rows = "var1", cols = "var2", from = -1, to = 1, adjust = 0.1)
plot(l_batch_2d_m2)
```


## 3d (x, y, color) plot series with one varying parameter or plot matrix with two varying parameters

```{r}
l_batch_3d_m1 <- make_3d_matrix(batch_test_result, x = "out1", y = "out2", cols = "var3", lims = c(-3, 3, -3, 3), h = 0.001, kde_fun = "ks", Umax = 10)
plot(l_batch_3d_m1)

l_batch_3d_m2 <- make_3d_matrix(batch_test_result2, x = "out1", y = "out2", rows = "var1", cols = "var2", lims = c(-3, 3, -3, 3), h = 0.001, kde_fun = "ks", Umax = 10)
plot(l_batch_3d_m2)
```

## 3d (x, y, z) or (x, y, color) animation and 3d (x, y, color) plot series with one varying parameter

*This part is computational and storage expensive thus not evaluated in the released vignette. You can run it on your device to see how the function produces animations. `gifski` package is needed to show the 3d (x, y, color) animation.*
```{r eval = FALSE}
l_batch_3d_a <- make_3d_animation(batch_test_result, x = "out1", y = "out2", fr = "var3", Umax = 20, lims = c(-3, 3, -3, 3), h = 0.002)

plot(l_batch_3d_a, 1)
plot(l_batch_3d_a, 2)
plot(l_batch_3d_a, 3)
```
