---
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 = "#>"
)
is_pkgdown <- identical(Sys.getenv("IN_PKGDOWN"), "true")
```

```{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 recently wrote some papers about the theoretical background of this method. You can find them at https://doi.org/10.1080/00273171.2022.2119927 or https://osf.io/pzva3.

`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(
  arg1 = list(ele1 = 1),
  arg2 = list(ele2 = 1, ele3 = 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_static(single_test, x = "out1")
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")
```

```{r eval=is_pkgdown}
# This chunk will only run when building with pkgdown
plot(l_single_3d, 1)
```

```{r}
plot(l_single_3d, 2)
```


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

```{r eval=is_pkgdown}
# This chunk will only run when building with pkgdown
l_single_4d <- make_4d_static(single_test, x = "out1", y = "out2", z = "out3")
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_arg_set()

batch_test <- batch_test %>%
  add_arg_ele("arg2", "ele3", 0.2, 0.5, 0.1)

batch_test_grid <- make_arg_grid(batch_test)

batch_test_result <- batch_simulation(batch_test_grid, sim_fun_test,
  default_list = list(
    arg1 = list(ele1 = 0),
    arg2 = list(ele2 = 0, ele3 = 0)
  ),
  bigmemory = FALSE
)
batch_test_result

batch_test2 <- new_arg_set()
batch_test2 <- batch_test2 %>%
  add_arg_ele("arg1", "ele1", 0.2, 0.6, 0.2) %>%
  add_arg_ele("arg2", "ele2", 0.2, 0.6, 0.2)
batch_test_grid2 <- make_arg_grid(batch_test2)

batch_test_result2 <- batch_simulation(batch_test_grid2, sim_fun_test,
  default_list = list(
    arg1 = list(ele1 = 0),
    arg2 = list(ele2 = 0, ele3 = 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 = "ele3")
plot(l_batch_2d_m1)

l_batch_2d_m2 <- make_2d_matrix(batch_test_result2, x = "out1", rows = "ele1", cols = "ele2")
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 = "ele3")
plot(l_batch_3d_m1)

l_batch_3d_m2 <- make_3d_matrix(batch_test_result2, x = "out1", y = "out2", rows = "ele1", cols = "ele2")
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 = "ele3")

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