1 Introduction

1.1 Support

1.2 Preamble

1.3 Show me a running example

2 The Kappa language

2.1 General structure

2.2 Sited-graph pattern: Kappa expression

2.2.1 Graphs

2.2.2 Patterns

2.2.3 Link type

2.3 Agent signatures

2.4 Algebraic expressions, variables and observables

2.5 Rules

2.5.1 Chemical notation rules

2.5.2 Edit notation rules

2.5.3 Rates

2.5.4 Ambiguous molecularity

2.5.5 Hybrid rules

2.6 Initial conditions

2.7 Intervention language

2.7.1 directive syntax

2.7.2 shortcuts

2.7.3 Model modiﬁcation

2.7.4 Model immediate examination

3 The Kappa tools

3.1 The KaSim engine

3.2 The KaSa static analyser

3.3 The KaDE ODEs generator

4 The stochastic simulator: KaSim

4.1 General usage

4.2 Main options

4.3 Advanced options

4.4 Example

4.5 Interactivity

5 Advanced concepts

5.1 Experimental continuous examination

5.1.1 Causality analysis

5.1.2 Dynamic inﬂuence network

5.1.3 Print species of an observable

5.2 Implicit signature

5.3 Simulation packages

5.4 Simulation parameters conﬁguration

5.5 Counters

6 The KaSa static analyser

6.1 General usage

6.2 Graphical interface

6.2.1 Launching the interface

6.2.2 The areas of interest

6.2.3 The sub-tab Actions

6.2.4 The sub-tab Syntax

6.2.5 The sub-tab Output

6.3 Reachability analysis

6.4 Local traces

6.5 Contact map

6.6 Inﬂuence map

7 The KaDE ODEs generator

7.1 General usage

7.2 Graphical interface

7.2.1 Launching the interface

7.2.2 The areas of interest

7.2.3 The sub-tab Data set

7.2.4 The sub-tab Output

7.2.5 The sub-tab Integration settings

7.2.6 The sub-tab Debug

7.3 Diﬀerential semantics

7.3.1 From rules to reactions

7.3.2 Semantics convention

7.3.3 The sub-tab Model reduction

7.4 Tutorial

8 Frequently asked questions

1.1 Support

1.2 Preamble

1.3 Show me a running example

2 The Kappa language

2.1 General structure

2.2 Sited-graph pattern: Kappa expression

2.2.1 Graphs

2.2.2 Patterns

2.2.3 Link type

2.3 Agent signatures

2.4 Algebraic expressions, variables and observables

2.5 Rules

2.5.1 Chemical notation rules

2.5.2 Edit notation rules

2.5.3 Rates

2.5.4 Ambiguous molecularity

2.5.5 Hybrid rules

2.6 Initial conditions

2.7 Intervention language

2.7.1 directive syntax

2.7.2 shortcuts

2.7.3 Model modiﬁcation

2.7.4 Model immediate examination

3 The Kappa tools

3.1 The KaSim engine

3.2 The KaSa static analyser

3.3 The KaDE ODEs generator

4 The stochastic simulator: KaSim

4.1 General usage

4.2 Main options

4.3 Advanced options

4.4 Example

4.5 Interactivity

5 Advanced concepts

5.1 Experimental continuous examination

5.1.1 Causality analysis

5.1.2 Dynamic inﬂuence network

5.1.3 Print species of an observable

5.2 Implicit signature

5.3 Simulation packages

5.4 Simulation parameters conﬁguration

5.5 Counters

6 The KaSa static analyser

6.1 General usage

6.2 Graphical interface

6.2.1 Launching the interface

6.2.2 The areas of interest

6.2.3 The sub-tab Actions

6.2.4 The sub-tab Syntax

6.2.5 The sub-tab Output

6.3 Reachability analysis

6.4 Local traces

6.5 Contact map

6.6 Inﬂuence map

7 The KaDE ODEs generator

7.1 General usage

7.2 Graphical interface

7.2.1 Launching the interface

7.2.2 The areas of interest

7.2.3 The sub-tab Data set

7.2.4 The sub-tab Output

7.2.5 The sub-tab Integration settings

7.2.6 The sub-tab Debug

7.3 Diﬀerential semantics

7.3.1 From rules to reactions

7.3.2 Semantics convention

7.3.3 The sub-tab Model reduction

7.4 Tutorial

8 Frequently asked questions

2.1 Kappa expressions.

2.2 Algebraic expressions.

2.3 Symbols usable in algebraic expressions.

2.4 Example of kinetic rates.

2.5 Rate expressions.

2.6 Token expressions.

2.7 Intervention expressions.

4.1 Command line: main options.

4.2 Command line: advanced options.

5.1 User deﬁned parameters.

5.2 Agent signature with counters extends in Table ??

5.3 Counter expressions

2.2 Algebraic expressions.

2.3 Symbols usable in algebraic expressions.

2.4 Example of kinetic rates.

2.5 Rate expressions.

2.6 Token expressions.

2.7 Intervention expressions.

4.1 Command line: main options.

4.2 Command line: advanced options.

5.1 User deﬁned parameters.

5.2 Agent signature with counters extends in Table ??

5.3 Counter expressions

Introduction

- Kappa language tutorials and downloads: http://kappalanguage.org
- Bug reports should be posted on github: https://github.com/Kappa-Dev/KaSim/issues
- Questions and answers on the Kappa-user mailing list: http://groups.google.com/group/kappa-users
- Want to contribute to the project? jean.krivine@irif.fr

This manual describes the Kappa language and details the usage of its tool suite.

Kappa is one member of the growing family of rule-based languages. Rule-based modelling has attracted recent attention in developing biological models that are concise, comprehensible, easily extensible, and allows one to deal with the combinatorial complexity of multi-state and multi-component biological molecules.

From the description of a system by the deﬁnition of a set of entities and the enumeration of their local rule of interraction, Kappa tools provide a framework to study statically and dynamically the system without ever enumerating all its reachable states (unless very explicitely asked to by users).

In Kappa, a mixture of entities is represented as a site graphs and temporal local transformations as rewrites.

First contact with Kappa as well as interactive model developement could occurs in the Kappapp available online and as downloadable software on main platforms. Intensive scientiﬁc usage should occurs by scripting around the command line tools or by using the Python client.

After a small teaser, this manual provides an exhaustive list of what can be done and how with the tools. It is not intended as a tutorial on rule-based modelling.

To get an idea of how Kappa is used in a modelling context, the reader can consult the following note Agile modelling of cellular signalling (SOS’08). A longer article, expounding on causal analysis is also available: Rule-based modelling of cellular signalling (CONCUR’07). See also this tutorial: Modelling epigenetic information maintenance: a Kappa tutorial.

See it really running in the online user interface by clicking on the try button on https://www.kappalanguage.org/.

A minimal Kappamodel looks like:

1/* Signatures*/

2%agent: A(x, c) // Declaration of agent A

3%agent: B(x) // Declaration of agent B

4%agent: C(x1{u p}, x2{u p}) // Declaration of agent C with 2 modifiable sites

5/* Variables */

6%var: ’on_rate’ 1.0E-4 // per molecule per second

7%var: ’off_rate’ 0.1 // per second

8%var: ’mod_rate’ 1 // per second

9/* Rules */

10’a.b’ A(x[.]),B(x[.]) <-> A(x[1]),B(x[1]) @ ’on_rate’, ’off_rate’ //A and B bind and dissociate

11’ab.c’ A(x[_], c[.]),C(x1{u}[.]) -> A(x[_], c[2]),C(x1{u}[2]) @ ’on_rate’ //AB binds unphosphorilated C

12’mod␣x1’ C(x1{u}[1]),A(c[1]) -> C(x1{p}[.]),A(c[.]) @ ’mod_rate’ //ABC modifies x1

13’a.c’ A(x[.],c[.]), C(x1{p}[.], x2{u}[.]) ->

14 A(x[.],c[1]), C(x1{p][.], x2{u}[1]) @ ’on_rate’ //A binds x1_phos C on x2

15’mod␣x2’ A(x[.], c[1]),C(x1{p}[.], x2{u}[1]) ->

16 A(x[.], c[.]),C(x1{p}[.], x2{p}[.]) @ mod_rate //AC modifies x2

17/* Observation */

18%obs: ’AB’ |A(x[x.B])|

19%obs: ’Cuu’ |C(x1{u}, x2{u})|

20%obs: ’Cpu’ |C(x1{p}, x2{u})|

21%obs: ’Cpp’ |C(x1{p}, x2{p})|

22/*Initial conditions */

23%init: 1000 A(),B()

24%init: 10000 C(x1{u}, x2{u})

2%agent: A(x, c) // Declaration of agent A

3%agent: B(x) // Declaration of agent B

4%agent: C(x1{u p}, x2{u p}) // Declaration of agent C with 2 modifiable sites

5/* Variables */

6%var: ’on_rate’ 1.0E-4 // per molecule per second

7%var: ’off_rate’ 0.1 // per second

8%var: ’mod_rate’ 1 // per second

9/* Rules */

10’a.b’ A(x[.]),B(x[.]) <-> A(x[1]),B(x[1]) @ ’on_rate’, ’off_rate’ //A and B bind and dissociate

11’ab.c’ A(x[_], c[.]),C(x1{u}[.]) -> A(x[_], c[2]),C(x1{u}[2]) @ ’on_rate’ //AB binds unphosphorilated C

12’mod␣x1’ C(x1{u}[1]),A(c[1]) -> C(x1{p}[.]),A(c[.]) @ ’mod_rate’ //ABC modifies x1

13’a.c’ A(x[.],c[.]), C(x1{p}[.], x2{u}[.]) ->

14 A(x[.],c[1]), C(x1{p][.], x2{u}[1]) @ ’on_rate’ //A binds x1_phos C on x2

15’mod␣x2’ A(x[.], c[1]),C(x1{p}[.], x2{u}[1]) ->

16 A(x[.], c[.]),C(x1{p}[.], x2{p}[.]) @ mod_rate //AC modifies x2

17/* Observation */

18%obs: ’AB’ |A(x[x.B])|

19%obs: ’Cuu’ |C(x1{u}, x2{u})|

20%obs: ’Cpu’ |C(x1{p}, x2{u})|

21%obs: ’Cpp’ |C(x1{p}, x2{p})|

22/*Initial conditions */

23%init: 1000 A(),B()

24%init: 10000 C(x1{u}, x2{u})

Lines 1-4 of this kappa ﬁle contain signature declarations. Agents of type C have two sites x1 and x2 whose internal state may be u (unphosphorylated) or p (phosphorylated). Line 11, rule 'ab.c' binds an A connected to someone on site x to a C.

There are two main points to notice about this model: A can modify both sites of C once it is bound to them. However, only an A bound to a B can connect on x1 and only a free A can connect on x2. Note also that x2 is available for connection only when x1 is already modiﬁed.

We try ﬁrst a coarse simulation of $100,000$ events (10 times the number of agents in the initial system).

- KaSim ABC.ka -u event -l 100000 -p 1000 -o abc.csv

Plotting the content of the abc.csv ﬁle, one notices that nothing signiﬁcantly interesting happens to the observables after 250s. So we can now specify a meaningful time limit by running:

- KaSim ABC.ka -l 250 -p 0.25 -o abc.out

which produces the data points whose rendering is given in Fig. 1.1.

We will use variant of this model as a running example for the next chapter.

The Kappa language

A model is represented in Kappa by a set of Kappa Files. We use KF to denote the union of the ﬁles that are given as input to a tool.

A KF is composed of a list of declaration. Declarations can be: agent and token signatures (Sec. 2.3), rules (Sec. 2.5), variables (Sec. 2.4), initial conditions (Sec. 2.6), intervention (Sec. 2.7) and parameter conﬁgurations (Sec. 5.4).

The KF’s structure is quite ﬂexible. Neither dividing into several sub-ﬁles nor the order of declarations matters (for the exception of interventions and variable declarations, see respectively Sections 2.7 and 2.4 for details).

Comments works like in the C language. It can be used either by inserting the marker // that tells KaSim to ignore the rest of the line or by putting any text between the delimiters /* and */.

The following sections present formal grammars. Here are hints to read them. Terminal symbols are written in (blue) typed font, and $\mathit{\epsilon}$ stands for the empty list. An identiﬁer Id can be any string generated by a regular expression of the type $\text{\_}\phantom{\rule{1em}{0ex}}{\left[a-z\phantom{\rule{1em}{0ex}}A-Z\phantom{\rule{1em}{0ex}}0-9\phantom{\rule{1em}{0ex}}\text{\_}\phantom{\rule{1em}{0ex}}-\phantom{\rule{1em}{0ex}}+\right]}^{+}|\left[a-z\phantom{\rule{1em}{0ex}}A-Z\right]{\left[a-z\phantom{\rule{1em}{0ex}}A-Z\phantom{\rule{1em}{0ex}}0-9\phantom{\rule{1em}{0ex}}\text{\_}\phantom{\rule{1em}{0ex}}-\phantom{\rule{1em}{0ex}}+\right]}^{\ast}$.

The state of the system is represented in Kappa as a sited graph: a graph where edges use sites in nodes. One must think sites as resources. At most one edge of the graph can use a site of a node (representing an agent in our case). Moreover, all the sites of an agent must have diﬀerent names.

This leads to the property that an embedding between 2 sited graphs is completely deﬁned by the image of one node. This is absolutely critical for the eﬃciency and we call this concept the rigidity of Kappa.

Kappa_expression | ::= | agent_expression , Kappa_expression $\mid \mathit{\epsilon}$ |

agent_expression | ::= | Id(interface) |

interface | ::= | Id internal_state link_state , interface $\mid \mathit{\epsilon}$ |

internal_state | ::= | $\mathit{\epsilon}$ | {.} | {Id} |

link_state | ::= | $\mathit{\epsilon}$ | [.] | [n] | [_] | [#] | [Id.Id] |

The ASCII syntax we use to represent sited graphs follows the skeletons (describe formally in Table 2.1):

- We write the type of the agent and then its interface (the space separated list its sites) between parenthesis.
- The state of a site is written after its name. Sites can have 2 kind of states: a linking state and an internal states. The order in which they are speciﬁed does not matter.
- The linking state of a site is written in between squared brackets: []
- The internal state of a site is written in between curly brackets: {}
- When the site is free (i.e. it is not a member of an edge), its linking state is written with a
dot: [.]. For example, the following graph:
is written as A(x[.], y{p}[.], z{e0}[.]).

- When a site is a part of an edge, one assign an arbitrary positive integer identiﬁer
$n$
to this edge and one specify the appurtenance of the site to this edge by writing the linking
state [n]. The following graph:
can be reprensented as A(x[23], y[4]{u}, z{e1}[.]), A(x[4], y{u}[95], z{e1}[.]), A(x[95], y{u}[23], z{e1}[.]).

Kappa strength is to describe transformations by only mentioning (and storing) the relevant part of the subgraph required for that transformation to be possible. This is the don’t care, don’t write (DCDW) principle which plays a key role in resisting combinatorial explosion when writing models.

If a transformation occurs independently from the state of a site of an agent, do not mention it in the pattern to match. The pattern A(x[.],z[.]) represents an agent of type A whose sites x and z are free but the sites y and z can be in any internal state and the site y can be linked or not to anything.

If the link state of a site does not matter but the internal state does, just mention it. An agent A whose sites x and z are free, y is in state u and z in state e2 is written as A(x[.],y{u},z{e2}[.]).

A state that is modiﬁed (by a rule that will be presented just below) always matter. For such situation, the symbol # (meaning “whatever” state) has been introduced.

In Kappa, in order to require a site to be bound for an interaction to occur, one may use the semi-link construct [_] which does not specify who the partner of the bond is. For instance, in the following instruction: %var: ’ab’|A(x[_]),B(y[_])|, the variable 'ab' will count the number of As and Bs connected to some agents, including the limit case A(x[1]),B(y[1]). It is sometimes convenient to specify the type of the semi-link, in order to restrict the choice of the binding partner. For instance, in the following instruction: %var: ’ab’|A(x[y.B]),B(y[x.A])|, the variable 'ab' will count the number of As whose site x is connected to a site y of B, plus the number of Bs whose site y is connected to a site x of A. Note that, this still includes the case A(x[1]),B(y[1]).

Remark Transformations on semi-links and links type induce side eﬀects (eﬀect on unmentioned agents/unmentioned site of agent) and can even do not make sense at all. What would mean to remove the link to A but not the link to B in the example above? Be careful when one use them.

Kappa tools can seek in the KF what agents are used, what sites they have and what states the sites are in but it is error prone: just make a typo once and the tools won’t complain and create a nonsens new agent/site/states...

To avoid that, Agent signatures can be deﬁned and tools will then ensure that agents respect their signature.

Agent signatures list all the agents that will appear in the KF. They enumerate the name of interaction sites an agent has. They provide information about sites binding capabilities. They specify whether a site has internal state and if so give the possibilities.

A signature is declared in the KF by the following line:

- %agent: signature_expression

according to an extention of the grammar given in Table 2.1. Linking states and internal states are space separated lists instead of being singleton. Site binding capabilities are speciﬁed by giving a list typed semi-links.

For instance, the line:

will declare an agent A with 3 (interaction) sites x,y and z, the site y possessing two internal states u and p (for instance, for the unphosphorylated and phosphorylated forms of y) and the site z having three possible states $e0$, $e1$ and $e2$, sites x and sites y being able to bind (intra agent or inter agents).

Special case If no agent signature provides any site binding capabilities, constraints are released and any site of any agent is allowed to bind any site of any agent.

Algebraic expressions original purpose was to deﬁne kinetic rates for rules but many components of a KF will now implies algebraic expressions. Their syntax are deﬁned in Table 2.2 (available symbols for variable, constants and operators are given in Table 2.3).

algebraic_expression | ::= | $x\in \mathbb{R}$ $\mid $ variable |

$\mid $ algebraic_expression binary_op algebraic_expression | ||

$\mid $ tcbunary_op (algebraic_expression) | ||

$\mid $ boolean_expression [?] algebraic_expression | ||

[:] algebraic_expression | ||

The last item of the list is an if-expression. boolean_expression are described in Table 2.7. Think very carefully whether it is the correct thing to do before using it. Mechanistic conditions have to be expressed in rule bodies and not in rule rates!

variable | Interpretation |

[E] | the total number of (productive) simulation events |

since the beginning of the simulation | |

[E-] | the total number of null events |

[T] | the bio-time of the simulation |

[Tsim] | the cpu-time since the beginning of the simulation |

'v' | the value of variable 'v' (declared by using the %var: statement) |

|t| | the concentration of token 2.5.5 t |

|Kappa_expression| | number of occurences of the pattern Kappa_expression |

inf | symbol for $\infty $ |

unary/binary_op | Interpretation |

[$f$] | usual mathematical functions and constants |

with $f\in \left\{\mathtt{\text{log,exp,sin,cos,tan,sqrt,pi}}\right\}$ |

It is possible to declare variables for later use with the declaration:
where var_name can be any string. For instance, the declarations
deﬁne two variables, the ﬁrst one tracking the number of embeddings of A(x[1]),A(x[1]) in the
graph over time, while the second divides this value by 2: the number of automorphisms in
A(x[1]),A(x[1]). Note that variables that are used in the expression of another variable must be
declared beforehand.
More importantly, KaSim may output values of an algebraic expression in the data ﬁle (see option
-p in Chapter 4) by using the primitive
One may use the shortcut:
to declare a variable and at the same time require it to be outputted in the data ﬁle.
Dynamics of agents is described in the KF by deﬁning rules.
There are two ways of specifying rules:

1%var: ’homodimer’ |A(x[1]),A(x[1])|

2%var: ’aa’ ’homodimer’/2
1%plot: ’var_name’

## 2.5 Rules