diff --git a/EpiAware/docs/src/getting-started/faq.md b/EpiAware/docs/src/getting-started/faq.md index ae2d7014a..5204c0ada 100644 --- a/EpiAware/docs/src/getting-started/faq.md +++ b/EpiAware/docs/src/getting-started/faq.md @@ -14,15 +14,37 @@ An entry point to running or developing this documentation is the `docs/pluto-sc ## Manipulating `EpiAware` model specifications -### Specifying models which are components +### Modular model construction -#### Modular model construction +One of the key features of `EpiAware` is the ability to specify models as components of a larger model. +This is useful for specifying models that are shared across multiple `EpiProblems` or for specifying models that are used in multiple methods. +You can see an examples of this approach in our [showcases](@ref showcase). -#### Remaking models +### Remaking models + +An alternative to modular model construction is to remake models with different parameters. This can be useful for comparing models with different parameters or for comparing models with different priors. +Whilst we don't have a built in function for this, we recommend the `Accessors.jl` package for this purpose. +For examples of how to use this package see the [documentation](https://juliaobjects.github.io/Accessors.jl/stable/getting_started/). ## Working with `Turing.jl` models -### Conditioning and fixing models +### `DynamicPPL.jl`](https://github.com/TuringLang/DynamicPPL.jl) + +Whilst `Turing.jl` is the front end of the `Turing.jl` ecosystem, it is not the only package that can be used to work with `Turing.jl` models. [`DynamicPPL.jl`](https://github.com/TuringLang/DynamicPPL.jl) is the part of the ecosytem that deals with defining, running, and manipulating models. + +#### Conditioning and deconditioning models + +`DynamicPPL` supports the `condition` (alased with `|`) to fix values as known *observations* in the model (i.e fixing values on the left hand side of `~` definitions). +This is useful for fixing parameters to known values or for conditioning the model on data. +The `decondition` function can be used to remove these conditions. +Internally this is what [`apply_method(::EpiProblem, ...)`](https://cdcgov.github.io/Rt-without-renewal/dev/lib/EpiAwareBase/public/#EpiAware.EpiAwareBase.apply_method-Tuple%7BEpiProblem,%20AbstractEpiMethod,%20Any%7D) does to condition the user supplied `EpiProblem` to data. See more [here](https://turinglang.org/DynamicPPL.jl/stable/tutorials/prob-interface/#Conditioning-and-Deconditioning). + +#### Fixing and unfixing models + +Similarly to conditioning and deconditioning models, `DynamicPPL` supports fixing and unfixing models via the `fix` and `unfix` functions. +Fixing is essentially saying that variables are constants (i.e replacing the right hand side of `~` with a value and changing the `~` to a `=`). +A common use of this would be to simplify a prespecified model, for example to make the variance of a random walk be known versus estimated from the data. +We also use this functionality in [`apply_method(::EpiProblem, ...)`](https://cdcgov.github.io/Rt-without-renewal/dev/lib/EpiAwareBase/public/#EpiAware.EpiAwareBase.apply_method-Tuple%7BEpiProblem,%20AbstractEpiMethod,%20Any%7D) to allow users to simplify `EpiProblems` on the fly. See more [here](https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.fix). ### Tools for working with `MCMCChain` objects