From 8216112166b3cc0cd7a493553cc804cd9b16ad43 Mon Sep 17 00:00:00 2001
From: samuelsmock <smock.samuel@gmail.com>
Date: Sun, 11 Feb 2024 14:45:53 -0600
Subject: [PATCH] SE_Drive Vignette is visible
---
.Rbuildignore | 2 +
.gitignore | 2 +
man/sim_all.Rd | 4 +-
vignettes/SE_drive-vignette.Rmd | 130 ++++++++++++++++++++++++++++++++
vignettes/vignette_SE_Drive.Rmd | 19 -----
5 files changed, 136 insertions(+), 21 deletions(-)
create mode 100644 vignettes/SE_drive-vignette.Rmd
delete mode 100644 vignettes/vignette_SE_Drive.Rmd
diff --git a/.Rbuildignore b/.Rbuildignore
index fc17ab1..70967c0 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -3,3 +3,5 @@
^LICENSE\.md$
^data-raw$
^README\.Rmd$
+^doc$
+^Meta$
diff --git a/.gitignore b/.gitignore
index 9b4ef08..6e753d3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@
.Rhistory
inst/doc
+/doc/
+/Meta/
diff --git a/man/sim_all.Rd b/man/sim_all.Rd
index 4b5e893..d0c7086 100644
--- a/man/sim_all.Rd
+++ b/man/sim_all.Rd
@@ -16,9 +16,9 @@ sim_all(nosim = 2, resps, destype = "ngene", designpath, u, bcoeff)
\item{designpath}{The path to the folder where the designs are stored. For example "c:/myfancydec/Designs"}
-\item{u}{A list with utility functions. The list can incorporate as many decision rule groups as you want. However, each group must be in a list in this list. If you just use one group (the normal), this group still has to be in a list in the u list.}
+\item{u}{A list with utility functions. The list can incorporate as many decision rule groups as you want. However, each group must be in a list in this list. If you just use one group (the normal), this group still has to be in a list in the u list. As a convention name beta coefficients starting with a lower case "b"}
-\item{bcoefficients}{List of coefficients for the utility function. List content/length can vary based on application, but item names should be in namespace: {bsq, bredkite, bdistance, bcost, bfarm2, bfarm3, bheight2, bheight3}}
+\item{bcoefficients}{List of initial coefficients for the utility function. List content/length can vary based on application, but should all begin with b and be the same as those entered in the utility functions}
}
\value{
A list, with all information on the simulation. This list an be easily processed by the user and in the rmarkdown template.
diff --git a/vignettes/SE_drive-vignette.Rmd b/vignettes/SE_drive-vignette.Rmd
new file mode 100644
index 0000000..c1c1b61
--- /dev/null
+++ b/vignettes/SE_drive-vignette.Rmd
@@ -0,0 +1,130 @@
+---
+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 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)
+
+rm(list=ls())
+devtools::load_all()
+
+
+library(rlang)
+```
+
+# 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 cooresponding beta coefficients representing the weight of each term must be declared in R like so:
+
+```{r initialize}
+
+decisiongroups=c(0,0.7,1)
+
+# 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)
+
+)
+
+```
+# Other parameters
+
+Besides these arguments the user must also specify the number of respondents in there 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 variable.
+
+```{r output}
+ sedrive <- sim_all(nosim = nosim, resps=resps, destype = destype,
+ designpath = designpath, u=ul, bcoeff = bcoeff)
+
+
+
+```
+
+# 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)
+```
+
+
diff --git a/vignettes/vignette_SE_Drive.Rmd b/vignettes/vignette_SE_Drive.Rmd
deleted file mode 100644
index 51c9d6e..0000000
--- a/vignettes/vignette_SE_Drive.Rmd
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "vignette_SE_Drive"
-output: rmarkdown::html_vignette
-vignette: >
- %\VignetteIndexEntry{vignette_SE_Drive}
- %\VignetteEngine{knitr::rmarkdown}
- %\VignetteEncoding{UTF-8}
----
-
-```{r, include = FALSE}
-knitr::opts_chunk$set(
- collapse = TRUE,
- comment = "#>"
-)
-```
-
-```{r setup}
-library(simulateDCE)
-```
--
GitLab