More docs

R/dsl.R

@@ -24,7 +24,7 @@
 ##'   function.
 ##'
 ##' @param fixed An optional list of values that can be used within
-##'   the dsl code.  Anything you provide here is available for your
+##'   the DSL code.  Anything you provide here is available for your
 ##'   calculations.  In the interest of future compatibility, we check
 ##'   currently that all elements are scalars.  In future this may
 ##'   become more flexible and allow passing environments, etc.  Once

vignettes/dsl.Rmd

@@ -67,3 +67,55 @@ The computed properties for the model are:
 ```{r}
 prior$properties
 ```
+
+# Calculations in the DSL
+
+Sometimes it will be useful to perform calculations in the code; you can do this with assignments.  Most trivially, giving names to numbers may help make code more understandable:
+
+```{r}
+m <- monty_dsl({
+  mu <- 10
+  sd <- 2
+  a ~ Normal(mu, sd)
+})
+```
+
+You can also use this to do things like:
+
+```{r}
+m <- monty_dsl({
+  a ~ Normal(0, 1)
+  b ~ Normal(0, 1)
+  mu <- (a + b) / 2
+  c ~ Normal(mu, 1)
+})
+```
+
+Where `c` is drawn from a normal distribution with a mean that is the average of `a` and `b`.
+
+# Pass in fixed data
+
+You can also pass in a list of data with values that should be available in the DSL code.  For example, our first example:
+
+```{r}
+prior <- monty_dsl({
+  alpha ~ Normal(178, 20)
+  beta ~ Normal(0, 10)
+  sigma ~ Uniform(0, 50)
+})
+```
+
+Might be written as
+
+```{r}
+fixed <- list(alpha_mean = 170, alpha_sd = 20,
+              beta_mean = 0, beta_sd = 10,
+              sigma_max = 50)
+prior <- monty_dsl({
+  alpha ~ Normal(alpha_mean, alpha_sd)
+  beta ~ Normal(beta_mean, beta_sd)
+  sigma ~ Uniform(0, sigma_max)
+}, fixed = fixed)
+```
+
+Values you pass in this way are **fixed** (hence the name!) and cannot be modified after the model object is created.