---
title: "Examples in 3D: part I"
output:
  prettydoc::html_pretty:
    theme: tactile
    highlight: vignette
vignette: >
  %\VignetteIndexEntry{Examples in 3D: part I}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\VignetteDepends{rgl}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "100%",
  fig.asp = 0.4,
  fig.width = 8.766
)
```

This vignette contains part I of a set of examples on how to use `clugenr` in
3D. Examples require the following setup code:

```{r setup, message=FALSE, warning=FALSE}
library(clugenr)    # The clugenr library
options(rgl.useNULL = TRUE)  # Create RGL plots in systems without displays (CI)
library(rgl)
setupKnitr(autoprint = TRUE) # Render RGL plots directly on generated page

# Load helper functions for plotting examples
source("plot_examples_3d.R", local = knitr::knit_global())

# Keep examples reproducible in newer R versions
RNGversion("3.6.0")
```

The 3D examples were plotted with the `plot_examples_3d()` function available
[here](https://github.com/clugen/clugenr/blob/main/vignettes/plot_examples_3d.R).

## Manipulating the direction of cluster-supporting lines

### Using the `direction` parameter

```{r}
seed <- 123
```

```{r}
e043 <- clugen(3, 4, 300, c(1, 0, 0), 0, c(10, 10, 10), 15, 1.5, 0.5, seed = seed)
e044 <- clugen(3, 4, 300, c(1, 1, 1), 0, c(10, 10, 10), 15, 1.5, 0.5, seed = seed)
e045 <- clugen(3, 4, 300, c(0, 0, 1), 0, c(10, 10, 10), 15, 1.5, 0.5, seed = seed)
```

```{r}
plot_examples_3d(list(e = e043, t = "e043: direction = [1, 0, 0]"),
                 list(e = e044, t = "e044: direction = [1, 1, 1]"),
                 list(e = e045, t = "e045: direction = [0, 0, 1]"))
```

### Changing the `angle_disp` parameter and using a custom `angle_deltas_fn` function

```{r}
seed <- 123
```

```{r}
# Custom angle_deltas function: arbitrarily rotate some clusters by 90 degrees
angdel_90 <- function(nclu, astd) sample(c(0, pi / 2), nclu, replace = TRUE)
```

```{r}
e046 <- clugen(3, 6, 300, c(1, 0, 0), 0, c(10, 10, 10), 15, 1.5, 0.5, seed = seed)
e047 <- clugen(3, 6, 300, c(1, 0, 0), pi / 8, c(10, 10, 10), 15, 1.5, 0.5, seed = seed)
e048 <- clugen(3, 6, 300, c(1, 0, 0), 0, c(10, 10, 10), 15, 1.5, 0.5, seed = seed,
               angle_deltas_fn = angdel_90)
```

```{r}
plot_examples_3d(list(e = e046, t = "e046: angle_disp = 0"),
                 list(e = e047, t = "e047: angle_disp = π / 8"),
                 list(e = e048, t = "e048: custom angle_deltas function"))
```

### Specifying a main `direction` for each cluster and changing `angle_disp`

```{r}
seed <- 123
```

```{r}
# Define a main direction for each cluster
dirs <- matrix(c(1, 1, 1,
                 0, 0, 1,
                 1, 0, 0,
                 0, 1, 0,
                 -1, 1, 1),
               nrow = 5, byrow = TRUE)
```

```{r}
e049 <- clugen(3, 5, 400, dirs, 0, rep.int(0, 3), 20, 0, 0.25, seed = seed)
e050 <- clugen(3, 5, 400, dirs, pi / 12, rep.int(0, 3), 20, 0, 0.25, seed = seed)
e051 <- clugen(3, 5, 400, dirs, pi / 4, rep.int(0, 3), 20, 0, 0.25, seed = seed)
```

```{r}
plot_examples_3d(list(e = e049, t = "e049: angle_disp = 0"),
                 list(e = e050, t = "e050: angle_disp = π / 12"),
                 list(e = e051, t = "e051: angle_disp = π / 4"))
```

## Manipulating the length of cluster-supporting lines

```{r}
seed <- 123
```

### Using the `llength` parameter

```{r}
e052 <- clugen(3, 5, 300, c(1, 0, 0), pi / 10, c(10, 10, 10), 0, 0, 0.5,
               seed = seed, point_dist_fn = "n")
e053 <- clugen(3, 5, 300, c(1, 0, 0), pi / 10, c(10, 10, 10), 10, 0, 0.5,
               seed = seed, point_dist_fn = "n")
e054 <- clugen(3, 5, 300, c(1, 0, 0), pi / 10, c(10, 10, 10), 30, 0, 0.5,
               seed = seed, point_dist_fn = "n")
```

```{r}
plot_examples_3d(list(e = e052, t = "e052: llength = 0"),
                 list(e = e053, t = "e053: llength = 10"),
                 list(e = e054, t = "e054: llength = 30"))
```

### Changing the `llength_disp` parameter and using a custom `llengths_fn` function

```{r}
# Custom llengths function: line lengths tend to grow for each new cluster
llen_grow <- function(nclu, llen, llenstd) {
  llen * (0:(nclu - 1) + rnorm(nclu, sd = llenstd))
}
```

```{r}
e055 <- clugen(3, 5, 300, c(1, 0, 0), pi / 10, c(10, 10, 10), 15,  0.0, 0.5,
               seed = seed, point_dist_fn = "n")
e056 <- clugen(3, 5, 300, c(1, 0, 0), pi / 10, c(10, 10, 10), 15, 10.0, 0.5,
               seed = seed, point_dist_fn = "n")
e057 <- clugen(3, 5, 300, c(1, 0, 0), pi / 10, c(10, 10, 10), 10,  0.1, 0.5,
               seed = seed, point_dist_fn = "n", llengths_fn = llen_grow)
```

```{r}
plot_examples_3d(list(e = e055, t = "e055: llength_disp = 0.0"),
                 list(e = e056, t = "e056: llength_disp = 10.0"),
                 list(e = e057, t = "e057: custom llengths function"))
```

## Manipulating relative cluster positions

### Using the `cluster_sep` parameter

```{r}
seed <- 321
```

```{r}
e058 <- clugen(3, 8, 300, c(1, 1, 1), pi / 4, c(30, 10, 10), 25, 4, 3, seed = seed)
e059 <- clugen(3, 8, 300, c(1, 1, 1), pi / 4, c(10, 30, 10), 25, 4, 3, seed = seed)
e060 <- clugen(3, 8, 300, c(1, 1, 1), pi / 4, c(10, 10, 30), 25, 4, 3, seed = seed)
```

```{r}
plot_examples_3d(list(e = e058, t = "e058: cluster_sep = [30, 10, 10]"),
                 list(e = e059, t = "e059: cluster_sep = [10, 30, 10]"),
                 list(e = e060, t = "e060: cluster_sep = [10, 10, 30]"))
```

### Changing the `cluster_offset` parameter and using a custom `clucenters_fn` function

```{r}
seed <- 321
```

```{r}
# Custom clucenters function: places clusters in a diagonal
centers_diag <- function(nclu, csep, coff) {
  matrix(1, nrow = nclu, ncol = length(csep)) * (1:nclu * max(csep)) +
    rep(coff, each = nclu)
}
```

```{r}
e061 <- clugen(3, 8, 300, c(1, 1, 1), pi / 4, c(10, 10, 10), 12, 3, 2.5, seed = seed)
e062 <- clugen(3, 8, 300, c(1, 1, 1), pi / 4, c(10, 10, 10), 12, 3, 2.5, seed = seed,
               cluster_offset = c(20, -20, 20))
e063 <- clugen(3, 8, 300, c(1, 1, 1), pi / 4, c(10, 10, 10), 12, 3, 2.5, seed = seed,
               cluster_offset = c(-50, -50, -50), clucenters_fn = centers_diag)
```

```{r}
plot_examples_3d(list(e = e061, t = "e061: default"),
                 list(e = e062, t = "e062: cluster_offset = [20, -20, 20]"),
                 list(e = e063, t = "e063: custom clucenters function"))
```