---
title: "SE_drive-vignette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{SE_drive-vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- There is an issue when creating these vignettes using usethis::use_vignette and 
devtools::build_vignettes() where the compilied vignette HTML files are placed in /doc
rather than inst/doc

Best Practice is to follow these steps
1. Create vignette using usethis::use_vignette("my-vignette")
2. After making changes, then run devtools::build_vignettes()
3. Rebuild using devtools::install(build_vignettes = TRUE)
4. Check that it is in the vignette environment using browseVigettes()

If vignette does not appear in gitHub, it is possibly due to a file heirarchy problem where rendered files 
appear in /doc instead of /inst/doc

To avoid this run:
tools::buildVignettes(dir = ".", tangle=TRUE)
dir.create("inst/doc")
file.copy(dir("vignettes", full.names=TRUE), "inst/doc", overwrite=TRUE)

More info here: https://community.rstudio.com/t/browsevignettes-mypackage-saying-no-vignettes-found/68656/7
-->

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

This vignette demonstrates how to use the `simulateDCE` package to simulate discrete choice experiments (DCEs). We will use a sample dataset and utility functions to generate simulated data and analyze the results.

```{r setup}
library(simulateDCE)
library(rlang)
library(formula.tools)
```

# Inititalize Variables

sim_all is the highest level function in the package and will run simulations for all designs contained in the specified design folder. Accordingly, this is generally the function the user will want to call. To prepare for using this function, a hypothesized utility function with corresponding beta coefficients representing the weight of each term must be declared in R like so:

```{r initialize}
# pass beta coefficients as a list
bcoeff <- list(
  bpreis = -0.01,
  blade = -0.07,
  bwarte = 0.02
)

manipulations <- list(
  alt1.x2 = expr(alt1.x2 / 10),
  alt1.x3 = expr(alt1.x3 / 10),
  alt2.x2 = expr(alt2.x2 / 10),
  alt2.x3 = expr(alt2.x3 / 10)
)


# place your utility functions here
ul <- list(
  u1 =

    list(
      v1 = V.1 ~ bpreis * alt1.x1 + blade * alt1.x2 + bwarte * alt1.x3,
      v2 = V.2 ~ bpreis * alt2.x1 + blade * alt2.x2 + bwarte * alt2.x3
    ),
  u2 = list(
    v1 = V.1 ~ bpreis * alt1.x1,
    v2 = V.2 ~ bpreis * alt2.x1
  )
)
```
# Decision Groups

If the utility function set passed to sim all has more than 1 utility function group as is the case above (u1, u2 etc.) an additional variable, 'decision groups' must be given to tell the function what portion of respondents should be given each utility function.

```{r decision}
decisiongroups <- c(0, 0.7, 1)
```

# Other parameters

Besides these arguments the user must also specify the number of respondents in the simulated survey and the number of times to run the model. The number of respondents (resps) should be selected based on experimental design parameters, while the number of simulations (nosim) should be large enough to glean statistically significant data. It is best to use a small number for this while learning to use the package and a large number (at least 500) once the other parameters have been settled.

The simulation can be ran using spdesign or NGENE design files which will be contained in the design path. The design path and design type, must also be specified: 

```{r other}
designpath <- system.file("extdata", "SE_DRIVE", package = "simulateDCE")

resps <- 120 # number of respondents
nosim <- 2 # number of simulations to run (about 500 is minimum)


destype <- "ngene"
```

# Output

The sim_all function returns a multidimensional R list containing graphs, simulated observations and a dataframe containing sumaries of estimated b coefficients. In general these will be printed to the console, but the entire results can also be assigned to an r list object.

```{r output}
sedrive <- sim_all(
  nosim = nosim, resps = resps, designtype = destype,
  designpath = designpath, u = ul, bcoeff = bcoeff, decisiongroups = decisiongroups
)
```

# Accessing the Output in R

The beta cofficients for each simulation are contained in a dataframe called coeffs located within {result}->olddesign->coefs. and a summary table is contained in ->olddesign->summary

```{r accessOutput}
## nested results are hard coded, if the design changes this must aswell
simulationCoeff <- sedrive$olddesign$coefs
coeffSummary <- sedrive$olddesign$summary

print(simulationCoeff)
print(coeffSummary)
```


