monty-dsl.qmd

# The monty DSL {#sec-monty-dsl}

```{r}
#| include: false
source("common.R")
```

The `monty` DSL provides a more intuitive way to define statistical models with `monty`. It is currently relatively basic and focuses on providing support for defining priors in Bayesian models. It fully support differentiability allowing to use gradient based samplers on these models.

```{r}
library(monty)
```

## A simple example

In chapter 4 of [Statistical Rethinking](https://xcelab.net/rm/), we build a regression model of height with parameters $\alpha$, $\beta$ and $\sigma$.  We can define the model for the prior probability of this model in monty by running

```{r}
prior <- monty_dsl({
  alpha ~ Normal(178, 20)
  beta ~ Normal(0, 10)
  sigma ~ Uniform(0, 50)
})
```

This will define a new `monty_model()` object that represents the prior, but with all the bits that we might need depending on how we want to use it:

We have model parameters

```{r}
prior$parameters
```

These are defined in the order that they appear in your definition (so `alpha` is first and `sigma` is last)

We can compute the domain for your model:

```{r}
prior$domain
```

We can draw samples from the model if we provide a `monty_rng` object

```{r}
rng <- monty_rng_create()
theta <- monty_model_direct_sample(prior, rng)
theta
```

We can compute the (log) density at a point in parameter space

```{r}
prior$density(theta)
```

The computed properties for the model are:

```{r}
prior$properties
```

## Distribution functions

In the above example we use distribution functions for the normal and uniform distributions. The distribution functions available for the `monty` DSL are the same as those for the `odin` DSL, the full list of which can be found [here](https://mrc-ide.github.io/odin2/articles/functions.html#distribution-functions).

## Dependent distributions

It is possible within the DSL to have the distribution of parameters to depend upon the value of other parameters:

```{r}
m <- monty_dsl({
    a ~ Normal(0, 1)
    b ~ Normal(a, 1)
})
```

This is particularly useful for the implementation of [hyperpriors](https://en.wikipedia.org/wiki/Hyperprior) when using the DSL to define priors.

Order of equations is important when using dependent distributions in the `monty` DSL! You cannot have the distribution of a parameter depend upon a parameter that is defined later. Thus rewriting the above example as

```
m <- monty_dsl({
    b ~ Normal(a, 1)
    a ~ Normal(0, 1)
})
```
would produce an error.

## 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.