Catalyst introduction doc remake #818
Conversation
TorkelE
force-pushed
the
catalyst_introduction_doc_remake
branch
from
90b4c05
to
1b6ed62
Compare
| μ, P₂ --> ∅ | ||
| μ, P₃ --> ∅ | ||
| end | ||
| show(stdout, MIME"text/plain"(), repressilator) # hide |
There was a problem hiding this comment.
Since this is the first new users will see, I figured it would be better to start of with a simpler model
| Assuming [Graphviz](https://graphviz.org/) is installed and command line | ||
| accessible, within a Jupyter notebook we can also graph the reaction network by | ||
| ```julia | ||
| g = Graph(repressilator) |
There was a problem hiding this comment.
Last time we discussed I think we said that it made sense to move the graph visualisation out of the intro tutorial, and instead have a specific section.
There was a problem hiding this comment.
(the dedicated model visualisation doc page is written and should be merged as soon as the tests can be run again)
| Alternatively, we can use ModelingToolkit-based symbolic species variables to | ||
| specify these mappings like | ||
| ```@example tut1 | ||
| t = default_t() |
There was a problem hiding this comment.
All MTK and internal stuff is moved to the thrid intro page (Advanced introduction to Catalyst, or something like that, not sure what we think the best name is)
| \frac{dX}{dt} &= -2 k X^2 Y^3, & | ||
| \frac{dY}{dt} &= -3 k X^2 Y^3, & | ||
| \frac{dX}{dt} &= -2 k X^2 Y^3, & | ||
| \frac{dY}{dt} &= -3 k X^2 Y^3, & |
There was a problem hiding this comment.
Not sure if we maybe shoudl add CLE equations after here as well.
|
The plan is to basically split this one. This one then because a pure intro to Catalyst that do not really assume that the user have read anything else (but are familiar with basic Julai syntax). Next, we have a "Advanced introduction to Catalyst" or "Introduction to Catalyst and its internals", or something (not really sure of its name) where we go through stuff like how system conversions work, symbolic representations, and give examples of the various types of modelling approaches (DSL, Programmatic, Compositional). |
| ``` | ||
|
|
||
| ## [Creating basic Catalyst models](@id introduction_to_catalyst_model_creation) | ||
| Catalyst exports the [`@reaction_network`](@ref) [macro]([macro](https://docs.julialang.org/en/v1/manual/metaprogramming/#man-macros)), which provides the main way of creating CRN models (an alternative, and in many ways more potent, approach is described [later](@ref programmatic_CRN_construction)). This is followed by a `begin ... end` block which encapsulates the model's reactions. E.g here we create a simple [birth-death model](@ref ref) (where a single species $X$ is both produced and degraded): |
There was a problem hiding this comment.
There is quite a few (@ref ref) here that will be broken links if someone click on them (I can add them in once the other docs are merged as well as this one).
| ```@example intro_1 | ||
| using StochasticDiffEq | ||
| sol = solve(sprob, STrapezoid()) | ||
| sol = solve(sprob, STrapezoid(); seed = 1234) # hide |
There was a problem hiding this comment.
Generally, I pu hidden seed simulations throughout the docs so that they look the same each time they are built. However, I agree that we should not depend on this. For all cases I have done this, I go through and ensure that the stochastic behaviour is more or less the same (e.g. I would not repeat what we had previously and have a workflow that depends on a seed in the early stage, but which might give a different result if this is modified).
| ## Notes | ||
| 1. For each of the preceding models we converted the `ReactionSystem` to, i.e., | ||
| ODEs, jumps, or SDEs, we had two paths for conversion: | ||
| ## [Catalyst represents its models symbolically, and these can be generated programmatically](@id introduction_to_catalyst_sym_prog) |
There was a problem hiding this comment.
This example is probably a bit long, but I thought it was really nice to be able to show of both automatic generation using programmatic modelling, and how to utilise symbolic representations.
|
|
||
| If we consider the code above, we use the species and parameters (e.g. `K` and `X`) to designate values and create our reactions. This is possible because the `@species` and `@parameters` macros create these as [*symbolic variables*](@ref ref). This enables us to form algebraic expressions using them. E.g. here we create an expression describing $X$'s production rate: | ||
| ```@example intro_prog_sym | ||
| X_prod = K/(K + Z^3) |
There was a problem hiding this comment.
I think this part is quite nice in showing of how the symbolic representation is useful. Originally I used normal hill functions to model the repressilator, but then the print-out of this was just
hillr(X, v, K, n)
which was kind of underwhelming. This gave a better result (and is also a fair way to model a repressilator)
|
|
||
| --- | ||
| ## References | ||
| ## [References](@id introduction_to_catalyst_references) |
There was a problem hiding this comment.
Generally, I just put reference tags on all sections now, even if not used. It is not strictly required (especially this one would surprise me). However, from the previous year of working across multiple branches, it sometimes lead to annoying merge things where you modify other files when you write a tutorial. This way, if you write a new tutorial and have to reference some other section, you do not have to worry about modifying other files.
updates the catalyst intro doc