Tutorial on .ka files

[Héctor F Medina A]

The Kappa Tutorial, v0.1
by Héctor F. Medina A.
with contributions from Jérôme, 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 Jérôme 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 have little experience with...


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.