You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Loading Chemical Reaction Network Models from Files
2
-
Catalyst stores chemical reaction network (CRN) models in `ReactionSystem` structures. This tutorial describes how to load such `ReactionSystem`s from, and save them to, files. This can be used to save models between Julia sessions, or transfer them from one session to another. Furthermore, to facilitate the computation modelling of CRNs, several standardised file formats have been created to represent CRN models (e.g. [SBML](https://sbml.org/)). These enables CRN models to be shared between different softwares and programming languages. While Catalyst itself does not have the functionality for loading such files, we will here (briefly) introduce a few packages that can load files to Catalyst `ReactionSystem`s.
2
+
Catalyst stores chemical reaction network (CRN) models in `ReactionSystem` structures. This tutorial describes how to load such `ReactionSystem`s from, and save them to, files. This can be used to save models between Julia sessions, or transfer them from one session to another. Furthermore, to facilitate the computation modelling of CRNs, several standardised file formats have been created to represent CRN models (e.g. [SBML](https://sbml.org/)). This enables CRN models to be shared between different softwares and programming languages. While Catalyst itself does not have the functionality for loading such files, we will here (briefly) introduce a few packages that can load different file types to Catalyst `ReactionSystem`s.
3
3
4
4
## Saving Catalyst models to, and loading them from, Julia files
5
5
Catalyst provides a `save_reactionsystem` function, enabling the user to save a `ReactionSystem` to a file. Here we demonstrate this by first creating a [simple cross-coupling model](@ref basic_CRN_library_cc):
Here, `save_reactionsystem`'s first argument is the path to the file where we wish to save it. The second argument is the `ReactionSystem` we wish to save. To load the file, we use Julia's `include` function:
19
19
```@example file_handling_1
20
20
loaded_rn = include("cross_coupling.jl")
21
+
rm("cross_coupling.jl") # hide
22
+
loaded_rn # hide
21
23
```
22
24
23
25
!!! note
24
-
The destination file can be in a folder. E.g. `save_reactionsystem("my_folder/reaction_network.jl", rn)` saves the model to the file "reaction_network.jl" in the folder "my_folder".
26
+
The destination file can be in a folder. E.g. `save_reactionsystem("my\_folder/reaction_network.jl", rn)` saves the model to the file "reaction\_network.jl" in the folder "my_folder".
25
27
26
-
Here, `include` is used to execute the Julia code from any file. This means that `save_reactionsystem` actually saves the model as executable code which re-generates the exact model which was saved (this is the reason why we use the ".jl" extension for the saved file). Indeed, if we print the file we can confirm this:
27
-
```@example file_handling_1
28
-
read("cross_coupling.jl", String)
28
+
Here, `include` is used to execute the Julia code from any file. This means that `save_reactionsystem` actually saves the model as executable code which re-generates the exact model which was saved (this is the reason why we use the ".jl" extension for the saved file). Indeed, we can confirm this if we check what is printed in the file:
29
29
```
30
-
```@example file_handling_1
31
-
rm("cross_coupling.jl")
30
+
let
31
+
32
+
# Independent variable:
33
+
@variables t
34
+
35
+
# Parameters:
36
+
ps = @parameters kB kD kP
37
+
38
+
# Species:
39
+
sps = @species S(t) E(t) SE(t) P(t)
40
+
41
+
# Reactions:
42
+
rxs = [
43
+
Reaction(kB, [S, E], [SE], [1, 1], [1]),
44
+
Reaction(kD, [SE], [S, E], [1], [1, 1]),
45
+
Reaction(kP, [SE], [P, E], [1], [1, 1])
46
+
]
47
+
48
+
# Declares ReactionSystem model:
49
+
rs = ReactionSystem(rxs, t, sps, ps; name = Symbol("##ReactionSystem#12592"))
50
+
complete(rs)
51
+
52
+
end
32
53
```
33
-
This functionality can also be used or print a model to simplify checking its various components.
54
+
!!! note
55
+
The code that `save_reactionsystem` prints uses [programmatic modelling](@ref ref) to generate the written model.
56
+
57
+
In addition to transferring models between Julia sessions, the `save_reactionsystem` function can also be used or print a model to a text file where you can easily inspect its components.
34
58
35
59
## Loading and Saving arbitrary Julia variables using Serialization.jl
36
-
Julia provide a general and lightweight interface for loading and saving Julia structures to and from files that it can be good to be aware of. It is called [Serialization.jl](https://docs.julialang.org/en/v1/stdlib/Serialization/) and provides two functions, `serialize` and `deserialize`. The first allow us to write a Julia structure to a file. E.g. if we wish to save a parameter set associated with our model, we can use
60
+
Julia provides a general and lightweight interface for loading and saving Julia structures to and from files that it can be good to be aware of. It is called [Serialization.jl](https://docs.julialang.org/en/v1/stdlib/Serialization/) and provides two functions, `serialize` and `deserialize`. The first allows us to write a Julia structure to a file. E.g. if we wish to save a parameter set associated with our model, we can use
37
61
```@example file_handling_2
38
62
using Serialization
39
-
ps = [:kB => 1.0, :kD => 0.1, :kP => 2.0]
63
+
ps = [:k₁ => 1.0, :k₂ => 0.1, :k₃ => 2.0]
40
64
serialize("saved_parameters.jls", ps)
41
65
```
42
-
Here, we use the extension ".jls" (standing for **J**u**L**ia **S**erialization), however, any can be used. To load a structure, we can then use
66
+
Here, we use the extension ".jls" (standing for **J**u**L**ia **S**erialization), however, any extension code can be used. To load a structure, we can then use
A general-purpose format for storing CRN models are so-called .net files. These can be generated by e.g. [BioNetGen](https://bionetgen.org/). The [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl) package enables the loading of such files to Catalyst `ReactionSystem`. Here we load a [Repressilator](@ref basic_CRN_library_repressilator) model stored in the "repressilator.net" file:
49
-
```@example file_handling_3
71
+
## [Loading .net files using ReactionNetworkImporters.jl](@id file_loading_rni_net)
72
+
A general-purpose format for storing CRN models is so-called .net files. These can be generated by e.g. [BioNetGen](https://bionetgen.org/). The [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl) package enables the loading of such files to Catalyst `ReactionSystem`. Here we load a [Repressilator](@ref basic_CRN_library_repressilator) model stored in the "repressilator.net" file:
Here, .net files not only contain information regarding the reaction network itself, but also the numeric values (initial conditions and parameter values) required for simulating it. Hence, `loadrxnetwork` generates a `ParsedReactionNetwork` structure, containing all this information. You can access the model as `prn.rn`, the initial conditions as `prn.u0`, and the parameter values as `prn.p`. Furthermore, these initial conditions and parameter values are also made [*default* values](@ref dsl_advanced_options_default_vals) of the model.
57
78
58
79
A parsed reaction network's content can then be provided to various problem types for simulation. E.g. here we perform an ODE simulation of our repressilator model:
Note that, as all initial conditions and parameters have default values, we can provide empty vectors for these into our `ODEProblem`.
67
90
68
91
69
92
!!! note
70
-
It should be noted that .net files supports a wide range of potential model features, not all of which are currently supported by ReactionNetworkImporters. Hence, there might be some .net files which `loadrxnetwork` will not be able to load.
93
+
It should be noted that .net files support a wide range of potential model features, not all of which are currently supported by ReactionNetworkImporters. Hence, there might be some .net files which `loadrxnetwork` will not be able to load.
71
94
72
95
A more detailed description of ReactionNetworkImporter's features can be found in its [documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/).
73
96
74
97
## Loading SBML files using SBMLImporter.jl and SBMLToolkit.jl
75
-
The Systems Biology Markup Language (SBML) is the most widespread format for representing CRN models. Currently, there exists two different Julia packages, [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), both of which are able to load SBML files to Catalyst `ReactionSystem` structures. SBML is able to represent a *very* wide range of model featuresSome of these are not supported by these packages (or Catalyst). Hence, there exist SBML files (typically containing obscure model features such as events with time delays) that currently cannot be loaded into Catalyst models.
98
+
The Systems Biology Markup Language (SBML) is the most widespread format for representing CRN models. Currently, there exist two different Julia packages, [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), that are able to load SBML files to Catalyst `ReactionSystem` structures. SBML is able to represent a *very* wide range of model features. Some of these are not supported by these packages (or Catalyst). Hence, there exist SBML files (typically containing obscure model features such as events with time delays) that currently cannot be loaded into Catalyst models).
76
99
77
100
SBMLImporter's `load_SBML` function can be used to load SBML files. Here, we load a [Brusselator](@ref basic_CRN_library_brusselator) model stored in the "brusselator.xml" file:
Here, while [ReactionNetworkImporters generates a `ParsedReactionSystem` only](@ref file_loading_rni_net), SBMLImporter generates a `ParsedReactionSystem` (here stored in `prn`) and a [so-called `CallbackSet`](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#CallbackSet) (here stored in `cbs`). While `prn` can be used to create various problems, when we simulate them, we must also supply `cbs`. E.g. to simulate our brusselator we use:
Note that, while ReactionNetworkImporters adds initial condition and species values as default to the imported model, SBMLImporter does not do this. These must hence be provided to the `ODEProblem` directly.
93
116
94
117
A more detailed description of SBMLImporter's features can be found in its [documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/).
95
118
@@ -103,4 +126,38 @@ While CRN models can be represented through various file formats, they can also
103
126
Or
104
127
- An $mxn$ complex stoichiometric matrix (...) and a $2mxn$ incidence matrix (...).
105
128
106
-
The advantage with these forms is that they offer a compact and very general way to represent a large class of CRNs. ReactionNetworkImporters have the functionality for converting matrices of these forms directly into Catalyst `ReactionSystem` models. Instructions on how to do this are available in [ReactionNetworkImporter's documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/#Loading-a-matrix-representation).
129
+
The advantage of these forms is that they offer a compact and very general way to represent a large class of CRNs. ReactionNetworkImporters have the functionality for converting matrices of these forms directly into Catalyst `ReactionSystem` models. Instructions on how to do this are available in [ReactionNetworkImporter's documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/#Loading-a-matrix-representation).
130
+
131
+
132
+
---
133
+
## [Citations](@id petab_citations)
134
+
If you use any of this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the paper(s) corresponding to whichever package(s) you used:
0 commit comments