The Kappa Tutorial, v0.1
by Hctor F. Medina A.
with contributions from Jrme, Vincent, & the KappaUsers community

Acknowledgements:
This Tutorial & reference work would have been impossible without the kind assistance of the guys at the KappaUsers forum. Special thanks go to Jrme and Vincent.


So you want to code something in Kappa and have found that the web based interface is performing poorly. The only option now is to use the binaries and create the script files, all without a fancy user interface! But dread not my poor reader for this Tutorial will attempt to guide you through the creation of a functional, runnable, and most importantly understandable script file.


What you need:
-the binaries
-the script


The Binaries

To get the binaries, you can download them from "http://github.com/kappamodeler/kappa/" where there are several different versions depending on the system you will be using (ie: Mac, Linux, 32 vs 64bit). Some of them have GUI, some don't. Some require special libraries, some don't. If you're unsure which one is the one for you, download them all and try running them. Alternatively, there's also the source code, so you can build them according to precisely what your system needs.


The Script

As for the script, you might want to take a look at "http://www.pps.jussieu.fr/~jkrivine/binaires/Telechargements/Kappa_simulator_and_static_analyzer.html" where there's an example file, along with several command-line runnable experiments.  We will be using "example.ka" for most purposes in this tutorial.

So, Kappa script files are named thus: "foo.ka" and their structure is quite simple. Each line of code is treated independently, so the order of the instructions doesn't really matter (often). However, understandable scripts do have a structure.

As you can see on the "example.ka" file, the first section begins with line "#rules". This line is not required, but it serves as introductory to the rules section. The "#" sign means that FROM THAT POINT ON, the line is a comment, NOT to be parsed or interpreted.

The next lines are rule lines. These lines begin by naming the rules. The first rule is named "AB", the next "A..B", and so on. You can specify various names for your rules including alphanumeric, score, & underscore characters.
Once a rule has been named, the rule must be defined. This is done as if it were a simple chemical reaction. Left of the "->" sign go the reactants, right go the products. In a more formal speech, left go the required conditions to trigger the rule, and right goes the output of said rule.
A further note, the agents must be in the same order on both sides of the "->" sign. If not, they might be taken as spontaneus degradation and production... And even if an agent has no sites, it must be specified as such: "agent()".

In "Pure Kappa", when an agent is introduced in a rule, it must be FULLY defined. This means that any agent which has a site, must have it explicitly said here. Likewise, if said site can have a state, it must also be specified.

In the first rule, we are introducing two agents, "a(x)" and "b(x)"; agent "a" has a site named "x", as does agent "b".
The rule means that when agents "a(x)" and "b(x)" meet, the reaction that happens is that they bind through their "x" sites. This bond is specified by the "!1" code on both sites "x". A more complicated example is this:
a(x), b(y), c(z), d(x, y, z) -> a(x!1), b(y!2), c(z!3), d(x!1, y!2, z!3)
Where agents "a", "b", and "c" bind to agent "d", each on a different site.
Moreover, sites can have states. Think of this as specifying whether a protein is phosphorylated or not, or something akin. For example:
foo(x~active) -> foo(x~inactive) @ 1.0
Specifies that agent "foo" with site "x" in state "active" will become "inactive".

Moving on, the last part of the rule specifies the rate of the reaction. The "@" character is used to specify said rate, in units of 1/second. For bidirectional rules, the syntax is changed thus:
'rule' B() <-> C() @ 0.01, 0.01
Notice the two changes are the "<->" for "->", and the double rates separated by a comma.
You can also specify degradation and production in a simple way by not specifying output and input respectively. Examples:
'production_by_nothing' -> A() @ 1.0
'production_by_TRIGGER' TRIGGER -> TRIGGER, A() @ 1.0
'degradation_by_nothing' A() -> @ 1.0
'degradation_by_TRIGGER' TRIGGER, A() -> TRIGGER @ 1.0


So by now you have the rules defined. It is time to move on to the initial conditions.
The syntax is quite simple, you specify with the "%" sign a command line, and with "init" that those will be the initial conditions/concentrations of the reacting mixture. The number specifies the amount of molecules. For example:
%init: 1000 * (b(x),c(x~u,y~u))
States that initially, there will be a thousand molecules of agent "b" with site "x", and another thousand molecules of agent "c" with site "x" in state "u", and site "y" in state "u".


Next parte are the observables. This is one of the MOST important parts of the script as this dictate the program's output, i.e.: what it will graph. If you specify the rules and initial mixture perfectly, but forget to observe for something, then you will see nothing.
Again, the syntax is quite simple, you begin with the traditional "%", followed by "obs:", then you assign a name to that tracking event with 'name', and finally the code of what exactly is the program tracking. For example:
%obs: 'C**' c(y~p) 
This means that on the graph, one of the lines will be named "C**", and it will represent the amount of agent "c" with site "y" in state "p". Notice that if agent "c" with site "y" is in a different state other than "p", then it will NOT report here. Moreover, if it has anything bound to that site, it will also NOT report here. See the bond types in the glossary for more information.

Likewise, variable behave much like observables, except they are not plotted. They are quite useful when used with perturbations.

Causal stuff I don't get very well...


Last but not least, perturbations and modifications are events that alter the conditions of the reacting mixture. These are handy if you want to track how a system evolves into steady state and then add something, looking how it reacts to it. For example:
%mod: ['C*'] > 2*['C']/5 do 'A..B':= 100.0 
This modification states that when the amount of agent "C*" is more than 2/5ths of the amount of agent "C", then the reaction rate of the rule named "A..B" will be changed to "100.0".


So that covers the basic structure of a .ka file. With your rules, initial conditions, observables, and modifications (if applicable) set, then you're ready to go!
Give the "example.ka" file a try.


Examples (More!), Tips, & Tricks

If you want to code a phosphorylation, the code could look something like this:
'SubstActBi' OmpR(act~Off), EnvZ(act~On) -> OmpR(act~Off!1), EnvZ(act~On!1) @ 0.9
'SubstActPh' OmpR(act~Off!1), EnvZ(act~On!1) -> OmpR(act~On!1), EnvZ(act~On!1) @ 1000
'SubstActUb' OmpR(act~On!1), EnvZ(act~On!1) -> OmpR(act~On), EnvZ(act~On) @ 0.9
The first rule is the binding of the substrate (CcaR) to the enzyme (EnvZ). The next one is the actual phosphorylation of the substrate (CcaR). The final step is the unbinding of the phosphorilated substrate from the enzyme.

If you want to inject something at time T, then the code could be:
'inject' -> A() @ 0
'to_avoid_dead_lock' B() <-> C() @ 0.01, 0.01
%init: 1*B()
%obs: 'A' A()
%obs: 'B' B()
%obs: 'inject'
%mod: $T > 10 do 'inject' := $INF
%mod: ['A'] > 6 do 'inject' := 0
Where at time 10, the rate of the "inject" rule becomes INFINITE. However, as soon as the amount of A exceeds 6 units, the rate becomes zero again. Thus, the code injects precisely 7 units of A at time T.
For a sustained introduction, you could replace "$INF" with a specific unit and eliminate the final "%mod". That way, from time 10 and onwards, there would be constant production of A.

Glossary

#			Comment
%			Command
''			Naming Quotations, there's a difference in ['] vs ["]
@			Rate
Smith(foo)	Specifies a site "foo" on agent "Smith"
!x			Where "x" is a number, it indicates a bond
!_			Indicates "any bond", doesn't matter which one, but it MUST be bound
?			Indicates it doesn't matter if bound, to what, or not; notice the absence of "!"
~			Specifies the state of a given site.
