# Examples in 2D

This vignette contains a number of examples on how to use `clugenr` in 2D. Examples require the following setup code:

``````# Load the clugenr library
library(clugenr)

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

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

The 2D examples were plotted with the `plot_examples_2d()` function available here.

## Manipulating the direction of cluster-supporting lines

### Using the `direction` parameter

``seed <- 123``
``````e001 <- clugen(2, 4, 200, c(1, 0), 0, c(10, 10), 10, 1.5, 0.5, seed = seed)
e002 <- clugen(2, 4, 200, c(1, 1), 0, c(10, 10), 10, 1.5, 0.5, seed = seed)
e003 <- clugen(2, 4, 200, c(0, 1), 0, c(10, 10), 10, 1.5, 0.5, seed = seed)``````
``````plot_examples_2d(list(e = e001, t = "e001: direction = [1, 0]"),
list(e = e002, t = "e002: direction = [1, 1]"),
list(e = e003, t = "e003: direction = [0, 1]"))``````

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

``seed <- 123``
``````# Custom angle_deltas function: arbitrarily rotate some clusters by 90 degrees
angdel_90_fn <- function(nclu, astd) sample(c(0, pi / 2), nclu, replace = TRUE)``````
``````e004 <- clugen(2, 6, 500, c(1, 0), 0, c(10, 10), 10, 1.5, 0.5, seed = seed)
e005 <- clugen(2, 6, 500, c(1, 0), pi / 8, c(10, 10), 10, 1.5, 0.5, seed = seed)
e006 <- clugen(2, 6, 500, c(1, 0), 0, c(10, 10), 10, 1.5, 0.5, seed = seed,
angle_deltas_fn = angdel_90_fn)``````
``````plot_examples_2d(list(e = e004, t = "e004: angle_disp = 0"),
list(e = e005, t = "e005: angle_disp = Ï€/8"),
list(e = e006, t = "e006: custom angle_deltas function"))``````

## Manipulating the length of cluster-supporting lines

### Using the `llength` parameter

``seed <- 321``
``````e007 <- clugen(2, 5, 800, c(1, 0), pi / 10, c(10, 10), 0, 0, 0.5, seed = seed,
point_dist_fn = "n")
e008 <- clugen(2, 5, 800, c(1, 0), pi / 10, c(10, 10), 10, 0, 0.5, seed = seed,
point_dist_fn = "n")
e009 <- clugen(2, 5, 800, c(1, 0), pi / 10, c(10, 10), 30, 0, 0.5, seed = seed,
point_dist_fn = "n")``````
``````plot_examples_2d(list(e = e007, t = "e007: llength = 0"),
list(e = e008, t = "e008: llength = 10"),
list(e = e009, t = "e009: llength = 30"))``````

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

``seed <- 765``
``````# Custom llengths function: line lengths grow for each new cluster
llen_grow_fn <- function(nclu, llen, llenstd) {
llen * 0:(nclu - 1) + rnorm(nclu, sd = llenstd)
}``````
``````e010 <- clugen(2, 5, 800, c(1, 0), pi / 10, c(10, 10), 15,  0.0, 0.5,
seed = seed, point_dist_fn = "n")
e011 <- clugen(2, 5, 800, c(1, 0), pi / 10, c(10, 10), 15, 10.0, 0.5,
seed = seed, point_dist_fn = "n")
e012 <- clugen(2, 5, 800, c(1, 0), pi / 10, c(10, 10), 10,  0.1, 0.5,
seed = seed, llengths_fn = llen_grow_fn, point_dist_fn = "n")``````
``````plot_examples_2d(list(e = e010, t = "e010: llength_disp = 0.0"),
list(e = e011, t = "e011: llength_disp = 5.0"),
list(e = e012, t = "e012: custom llengths function"))``````

## Manipulating relative cluster positions

### Using the `cluster_sep` parameter

``seed <- 222``
``````e013 <- clugen(2, 8, 1000, c(1, 1), pi / 4, c(10, 10), 15, 2, 4, seed = seed)
e014 <- clugen(2, 8, 1000, c(1, 1), pi / 4, c(30, 10), 15, 2, 4, seed = seed)
e015 <- clugen(2, 8, 1000, c(1, 1), pi / 4, c(10, 30), 15, 2, 4, seed = seed)``````
``````plot_examples_2d(list(e = e013, t = "e013: cluster_sep = [10, 10]"),
list(e = e014, t = "e014: cluster_sep = [30, 10]"),
list(e = e015, t = "e015: cluster_sep = [10, 30]"))``````

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

``seed <- 222``
``````# 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)
}``````
``````e016 <- clugen(2, 8, 1000, c(1, 1), pi / 4, c(10, 10), 10, 2, 2.5, seed = seed)
e017 <- clugen(2, 8, 1000, c(1, 1), pi / 4, c(10, 10), 10, 2, 2.5, seed = seed,
cluster_offset = c(20, -20))
e018 <- clugen(2, 8, 1000, c(1, 1), pi / 4, c(10, 10), 10, 2, 2.5, seed = seed,
cluster_offset = c(-50, -50), clucenters_fn = centers_diag)``````
``````plot_examples_2d(list(e = e016, t = "e016: default"),
list(e = e017, t = "e017: cluster_offset = [20, -20]"),
list(e = e018, t = "e018: custom clucenters function"))``````

## Lateral dispersion and placement of point projections on the line

``seed <- 234``

### Normal projection placement (default): `proj_dist_fn = "norm"`

``````e019 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 0.0, seed = seed)
e020 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 1.0, seed = seed)
e021 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 3.0, seed = seed)``````
``````plot_examples_2d(list(e = e019, t = "e019: lateral_disp = 0"),
list(e = e020, t = "e020: lateral_disp = 1"),
list(e = e021, t = "e021: lateral_disp = 3"))``````

### Uniform projection placement: `proj_dist_fn = "unif"`

``````e022 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 0.0, seed = seed,
proj_dist_fn = "unif")
e023 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 1.0, seed = seed,
proj_dist_fn = "unif")
e024 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 3.0, seed = seed,
proj_dist_fn = "unif")``````
``````plot_examples_2d(list(e = e022, t = "e022: lateral_disp = 0"),
list(e = e023, t = "e023: lateral_disp = 1"),
list(e = e024, t = "e024: lateral_disp = 3"))``````

### Custom projection placement using the Beta distribution

``````# Custom proj_dist_fn: point projections placed using the Beta distribution
proj_beta <- function(len, n) len * rbeta(n, 0.1, 0.1) - len / 2``````
``````e025 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 0.0, seed = seed,
proj_dist_fn = proj_beta)
e026 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 1.0, seed = seed,
proj_dist_fn = proj_beta)
e027 <- clugen(2, 4, 1000, c(1, 0), pi / 2, c(20, 20), 13, 2, 3.0, seed = seed,
proj_dist_fn = proj_beta)``````
``````plot_examples_2d(list(e = e025, t = "e025: lateral_disp = 0"),
list(e = e026, t = "e026: lateral_disp = 1"),
list(e = e027, t = "e027: lateral_disp = 3"))``````

## Controlling final point positions from their projections on the cluster-supporting line

``seed <- 12321``
``````# Custom proj_dist_fn: point projections placed using the Beta distribution
proj_beta <- function(len, n) len * rbeta(n, 0.1, 0.1) - len / 2``````

### Points on hyperplane orthogonal to cluster-supporting line (default): `point_dist_fn = "n-1"`

``````e028 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed)
e029 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
proj_dist_fn = "unif")
e030 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
proj_dist_fn = proj_beta)``````
``````plot_examples_2d(list(e = e028, t = "e028: proj_dist_fn = 'norm' (default)"),
list(e = e029, t = "e029: proj_dist_fn = 'unif'"),
list(e = e030, t = "e030: custom proj_dist_fn (Beta dist.)"))``````

### Points around projection on cluster-supporting line: `point_dist_fn = "n"`

``````e031 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
point_dist_fn = "n")
e032 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
point_dist_fn = "n", proj_dist_fn = "unif")
e033 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
point_dist_fn = "n", proj_dist_fn = proj_beta)``````
``````plot_examples_2d(list(e = e031, t = "e031: proj_dist_fn = 'norm' (default)"),
list(e = e032, t = "e032: proj_dist_fn = 'unif'"),
list(e = e033, t = "e033: custom proj_dist_fn (Beta dist.)"))``````

### Custom point placement using the exponential distribution

``````# Custom point_dist_fn: final points placed using the Exponential distribution
clupoints_n_1_exp <- function(projs, lat_std, len, clu_dir, clu_ctr) {
dist_exp <- function(npts, lstd) lstd * rexp(npts, rate = 2 / lstd)
clupoints_n_1_template(projs, lat_std, clu_dir, dist_exp)
}``````
``````e034 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
point_dist_fn = clupoints_n_1_exp)
e035 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
point_dist_fn = clupoints_n_1_exp, proj_dist_fn = "unif")
e036 <- clugen(2, 5, 1500, c(1, 0), pi / 4, c(20, 20), 14, 2, 2.0, seed = seed,
point_dist_fn = clupoints_n_1_exp, proj_dist_fn = proj_beta)``````
``````plot_examples_2d(list(e = e034, t = "e034: proj_dist_fn = 'norm' (default)"),
list(e = e035, t = "e035: proj_dist_fn = 'unif'"),
list(e = e036, t = "e036: custom proj_dist_fn (Beta dist.)"))``````

## Manipulating cluster sizes

``seed <- 87``
``````# Custom clucenters_fn (all): yields fixed positions for the clusters
centers_fixed <- function(nclu, csep, coff) {
matrix(c(-csep[1], -csep[2], csep[1], -csep[2], -csep[1], csep[2], csep[1], csep[2]),
nrow = nclu, byrow = TRUE)
}

# Custom clusizes_fn (e038): cluster sizes determined via the uniform distribution,
# no correction for total points
clusizes_unif <- function(nclu, npts, ae) sample(2 * npts / nclu, nclu, replace = TRUE)

# Custom clusizes_fn (e039): clusters all have the same size, no correction for
# total points
clusizes_equal <- function(nclu, npts, ae) npts %/% nclu * rep.int(1, nclu)``````
``````e037 <- clugen(2, 4, 1500, c(1, 1), pi, c(20, 20), 0, 0, 5, seed = seed,
clucenters_fn = centers_fixed, point_dist_fn = "n")
e038 <- clugen(2, 4, 1500, c(1, 1), pi, c(20, 20), 0, 0, 5, seed = seed,
clucenters_fn = centers_fixed, clusizes_fn = clusizes_unif,
point_dist_fn = "n")
e039 <- clugen(2, 4, 1500, c(1, 1), pi, c(20, 20), 0, 0, 5, seed = seed,
clucenters_fn = centers_fixed, clusizes_fn = clusizes_equal,
point_dist_fn = "n")``````
``````plot_examples_2d(list(e = e037, t = "e037: normal dist. (default)"),
list(e = e038, t = "e038: unif. dist. (custom)"),
list(e = e039, t = "e039: equal size (custom)"))``````

## Direct specification of optional parameters

``seed <- 9876``
``````e040 <- clugen(2, 4, 1000, c(-1, 1), 0, c(0, 0), 0, 0, 0.2, seed = seed,
proj_dist_fn = "unif", point_dist_fn = "n",
clusizes_fn = c(50, 200, 500, 2000), llengths_fn = c(0, 2, 4, 6),
clucenters_fn = matrix(c(-5, -5, -2.5, -2.5, 0, 0, 2.5, 2.5),
nrow = 4, byrow = TRUE))
e041 <- clugen(2, 5, 1000, matrix(c(1, 1, 1, 0, 1, 0, 0, 1, 0, 1),
nrow = 5, byrow = TRUE),
0, c(0, 0), 0, 0, 0.2, seed = seed,
proj_dist_fn = "unif", point_dist_fn = "n",
clusizes_fn = c(200, 500, 500, 500, 500),
llengths_fn = c(0, 5, 5, 5, 5),
clucenters_fn = matrix(c(0, 0, 0, 5, 0, -5, 5, 0, -5, 0),
nrow = 5, byrow = TRUE))
e042 <- clugen(2, 5, 1000, matrix(c(0, 1, 0.25, 0.75, 0.5, 0.5, 0.75, 0.25, 1, 0),
nrow = 5, byrow = TRUE),
0, c(0, 0), 5, 0, 0.2, seed = seed,
proj_dist_fn = "unif", point_dist_fn = "n",
clusizes_fn = c(500, 500, 500, 500, 500),
clucenters_fn = matrix(c(-5, 0, -3, -0.3, -1, -0.8, 1, -1.6, 3, -2.5),
nrow = 5, byrow = TRUE))``````
``````plot_examples_2d(list(e = e040, t = "e040: direct params 1"),
list(e = e041, t = "e041: direct params 2"),
list(e = e042, t = "e042: direct params 3"))``````