Fixing documentation and vignettes

Author: Keith Goldfeld

man/defData.Rd

@@ -45,11 +45,13 @@ ggtheme <- function(panelback = "white") {
 
 ```
 
-Custom distributions can be specified in `defData` and `defDataAdd` by using the specifying "custom" for the argument *dist*. The name of the user-defined function is specified as a string in the *formula* argument. The arguments of the custom function are specified in the *variance* argument, as a comma delimited string. One important feature of the custom function is that the parameter list used to define the function must include "**n = n**", but this will not be included in the data definition.
+Custom distributions can be specified in `defData` and `defDataAdd` by setting the argument *dist* to "custom". When defining a custom distribution, you provide the name of the user-defined function as a string in the *formula* argument. The arguments of the custom function are listed in the *variance* argument, separated by commas and formatted as "**arg_1 = val_form_1, arg_2 = val_form_2, $\dots$, arg_K = val_form_K**".
+
+Here, the *arg_k's* represent the names of the arguments passed to the customized function, where $k$ ranges from $1$ to $K$. You can use values or formulas for each *val_form_k*. If formulas are used, ensure that the variables have been previously generated. Double dot notation is available in specifying *value_formula_k*. One important requirement of the custom function is that the parameter list used to define the function must include an argument"**n = n**", but do not include $n$ in the definition as part of `defData` or `defDataAdd`.
 
 ### Example 1
 
-Here is an example where we would like to generate data from a zero-inflated beta distribution. In this case, there is a user-defined function `zeroBeta` that takes on shape parameters $a$ and $b$, as well as $p_0$, the proportion of the sample that is zero:
+Here is an example where we would like to generate data from a zero-inflated beta distribution. In this case, there is a user-defined function `zeroBeta` that takes on shape parameters $a$ and $b$, as well as $p_0$, the proportion of the sample that is zero. Note that the function also takes an argument $n$ that will not to be be specified in the data definition; $n$ will represent the number of observations being generated:
 
 ```{r}
 zeroBeta <- function(n, a, b, p0) {
@@ -59,7 +61,7 @@ zeroBeta <- function(n, a, b, p0) {
 }
 ```
 
-The data definition specifies a new variable $zb$ that will sets $a$ and $b$ to 0.75, and $p_0 = 0.02$:
+The data definition specifies a new variable $zb$ that sets $a$ and $b$ to 0.75, and $p_0 = 0.02$:
 
 ```{r}
 def <- defData(
@@ -91,10 +93,10 @@ ggplot(data = dd, aes(x = zb)) +
 
 ### Example 2
 
-In this case, we are generating a mixture of truncated distributions, where the limits of the truncation vary across three different groups. `rnormt` is a customized (user-defined) function that generates truncated data from a Gaussian distribution. The function requires up to four arguments (the left truncation value, the right truncation value, the distribution average and the standard deviation).
+In this second example, we are generating sets of truncated Gaussian distributions with means ranging from $-1$ to $1$. The limits of the truncation vary across three different groups. `rnormt` is a customized (user-defined) function that generates the truncated Gaussiandata. The function requires four arguments (the left truncation value, the right truncation value, the distribution average and the standard deviation).
 
 ```{r}
-rnormt <- function(n, min, max, mu = 0, s = 1.5) {
+rnormt <- function(n, min, max, mu, s) {
   
   F.a <- pnorm(min, mean = mu, sd = s)
   F.b <- pnorm(max, mean = mu, sd = s)
@@ -105,7 +107,8 @@ rnormt <- function(n, min, max, mu = 0, s = 1.5) {
 }
 ```
 
-In this example, the truncation limits vary by group membership. There are three groups.  We only pass three parameters (the limits and the mean), using the default standard deviation.
+
+In this example, truncation limits vary based on group membership. Initially, three groups are created, followed by the generation of truncated values. For Group 1, truncation occurs within the range of $-1$ to $1$, for Group 2, it's $-2$ to $2$ and for Group 3, it's $-3$ to $3$. We'll generate three data sets, each with a distinct mean denoted by M, using the double-dot notation to implement these different means.
 
 ```{r}
 def <-
@@ -117,26 +120,40 @@ def <-
   defData(
     varname = "tn", 
     formula = "rnormt", 
-    variance = "min = -limit, max = limit, mu = 0.5",
+    variance = "min = -limit, max = limit, mu = ..M, s = 1.5",
     dist = "custom"
   )
+```
 
-dd <- genData(100000, def)
+The data generation requires three calls to `genData`. The output is a list of three data sets:
+
+```{r}
+mus <- c(-1, 0, 1)
+dd <-lapply(mus, function(M) genData(100000, def))
 ```
 
+Here are the first six observations from each of the three data sets:
+
 ```{r, echo=FALSE}
-dd
+lapply(dd, function(D) head(D))
 ```
 
 A plot highlights the group differences.
 
-```{r, fig.width = 8, fig.height = 3, echo = FALSE}
-ggplot(data = dd, aes(x = tn)) +
-  geom_histogram(aes(fill = factor(limit)), binwidth = 0.05, boundary = 0, alpha = .8) +
-  facet_grid( ~ limit) +
-  theme(panel.grid = element_blank(),
-        legend.position = "none") +
-  scale_fill_manual(values = plotcolors) +
-  scale_x_continuous(breaks = seq(-3, 3, by =1))
+```{r, fig.width = 8, fig.height = 6, echo = FALSE}
+pfunc <- function(dx, i) {
+  ggplot(data = dx, aes(x = tn)) +
+    geom_histogram(aes(fill = factor(limit)), binwidth = 0.05, boundary = 0, alpha = .8) +
+    facet_grid( ~ limit) +
+    theme(panel.grid = element_blank(),
+          legend.position = "none") +
+    scale_fill_manual(values = plotcolors) +
+    scale_x_continuous(breaks = seq(-3, 3, by =1)) +
+    scale_y_continuous(limits = c(0, 1000)) +
+    ggtitle(paste("mu =", mus[i]))
+}
+
+plist <- lapply(seq_along(dd), function(a) pfunc(dd[[a]], a))
+grid.arrange(grobs = plist, nrow = 3)
 ```
 

vignettes/customdist.Rmd

@@ -231,7 +231,7 @@ The *clusterSize* distribution allocates a total sample size *N* (specified in t
 
 #### custom
 
-The *custom* distribution facilitates data generation for a user-defined distribution. The name of the user-defined function is specified as a string in the *formula* argument. The arguments of the function are specified in the *variance* argument, as a comma delimited string, such as "**name_arg_1 = value/formula_1, name_arg_2 = value/formula_2, ..., name_arg_K = value/formula_K**". The *name_arg_k*, $x \in \{1,2,...,K\}$, are required to create the $K$ arguments that are passed to the customized function. The *val/form_k* represent either values or a formula that is used to generate the values for the argument; if formulas are used, variables in the formulas must have been generated previously. Double dot notation is available in specifying the *value/formula_k*. One important feature of the custom function is that the parameter list used to define the function must include "**n = n**", but this will not be included in the data definition.
+Custom distributions can be specified in `defData` and `defDataAdd` by setting the argument *dist* to "custom". When defining a custom distribution, provide the name of the user-defined function as a string in the *formula* argument. The arguments of the custom function are listed in the *variance* argument, separated by commas and formatted as "**arg_1 = val_form_1, arg_2 = val_form_2, $\dots$, arg_K = val_form_K**". The *arg_k's* represent the names of the arguments passed to the customized function, where $k$ ranges from $1$ to $K$. Values or formulas can be used for each *val_form_k*. If formulas are used, ensure that the variables have been previously generated. Double dot notation is available in specifying *value_formula_k*. One important requirement of the custom function is that the parameter list used to define the function must include an argument"**n = n**", but do not include $n$ in the definition as part of `defData` or `defDataAdd`.
 
 #### exponential