
---
title: "Latin Hypercube Sampling"
---

```{r ch_opt, child="include/chunk_options.rmd", cache=FALSE}
```

```{r, echo = FALSE}
library(nlexperiment)
nl_netlogo_path("c:/Program Files/NetLogo 6.0.1/app") 
```

This example is using NetLogo Flocking model (Wilensky, 1998) to
demonstrate exploring parameter space with categorical evaluation
and Latin hypercube sampling (LHS).

<aside>
Wilensky, U. (1998). 
[NetLogo Flocking model](http://ccl.northwestern.edu/netlogo/models/Flocking). 
Center for Connected Learning and Computer-Based Modeling, 
Northwestern University, Evanston, IL.
</aside>

Like in [previous example](flocking_categorical.html) we are using
categorical evaluation criteria but
instead of exploring parameter space with (full) factorial design we use 
Latin hypercube sampling method from **lhs** package. 

```{r flockSampModel, title = "Define the experiment"}
experiment <- nl_experiment( 
  model_file = "models/Sample Models/Biology/Flocking.nlogo",
  setup_commands = c("setup", "repeat 100 [go]"),
  iterations = 5,

  param_values = nl_param_lhs(
    n = 100, 
    world_size = 50,
    population = 80,
    vision = 6,
    min_separation = c(0, 4),
    max_align_turn = c(0, 20)
  ),
  mapping = c(
    min_separation = "minimum-separation",
    max_align_turn = "max-align-turn"),

  step_measures = measures(
    converged = "1 - 
      (standard-deviation [dx] of turtles + 
       standard-deviation [dy] of turtles) / 2",
    mean_crowding = 
      "mean [count flockmates + 1] of turtles"
  ),
  eval_criteria = criteria(
    c_converged = mean(step$converged),
    c_mcrowding = mean(step$mean_crowding)
  ),

  repetitions = 10,                        # repeat simulations 10 times
  random_seed = 1:10,
  
  eval_aggregate_fun = mean                # aggregate over repetitions
)  
```

<aside>
Function `nl_param_lhs` is using `randomLHS` function from **lhs** package to create
  random parameter sets. Argument `n` defines the size of the LH sample.

Instead of `nl_param_lhs` one can use `nl_param_mc` to get simple Monte Carlo
 experiment or put any data frame in param_values.
 The columns of a data frame are interpreted as parameter names and rows as
 parameter value sets.
</aside>


```{r flockSampRun, title = "Run experiment", cache=TRUE}
result <- nl_run(experiment, parallel = TRUE)
```

```{r flockSampData, title = "Add categorical criteria"}
dat <- nl_get_criteria_result( 
  result,
  are_grouped = c_mcrowding >= 5 & c_mcrowding < 11,
  are_aligned = c_converged > 0.7
)
```
<aside>
See [previous example](flocking_categorical.html) for categorical criteria
definition.
</aside>


```{r flockSampPlot, title = "Plot the results", fig.cap='Categorical criteria "aligned" (red triangle) and "grouped" (blue cross). Black dots are parameter sets'}
library(ggplot2)
ggplot( dat, aes(x = min_separation, y = max_align_turn) ) +
  geom_point() +
  geom_point(data=subset(dat,are_aligned), color="red",size=5,shape=2) +
  geom_point(data=subset(dat,are_grouped), color="blue",size=5,shape=3) +
  coord_equal(ratio = 1/5) +
  theme_minimal()
```

## Related

Example [Random sampling](flocking_sens_lhs.html) explores 5-dimensional 
parameter space of NetLogo Flocking model
with random sampling and scatter plots.


[Best-fit Criterion](flocking_bestfit.html) shows how to define 
  single criterion evaluation expression 
  and evaluate parameter space with full-factor design.
  
[Random Search](flocking_random_search.html) demonstrate searching for optimal parameters
  using random search.  

<asideclose>
Get [rmarkdown source](`r knitr::current_input()`) of this page.
</asideclose>
