This section covers the concepts and conventions used for the Simmune Modeler and this documentation.
Model
Within the framework of the Simmune Modeler a model refers to a set of specifications describing the components, interactions and transformations of molecules and multi-molecular complexes. The specification data include entites and rules. The graphical layout information about the entities and rules is also included in the model.
For the current version of the Simmune Modeler, a model created by the Simmune Modeler is independent from any other model(s).
Model file
The Simmune Modeler manages the model data using the third party embedded database management software, called SQLite, bundled with the QT (tm) frame work (The modeler is developed with the QT frame work). A model file is a SQLite database file, which contains the complete specification of a model.
Entity and Rule
An entity is a component in a model. An entity can be a molecule, a molecule component, a binding site, a complex species or a complex. A rule specifies a relationship between entities, including molecule interactions, complex transformations, associations and dissociations. Internally, each entity or rule has a unique SimmID. An entity/rule has properties such as short name, full name, annotation, etc.
SimmID
A SimmID is a unique identifier for an entity or a rule in a model. It is automatically assigned by the Simmune Modeler.
Starting with Simmune Modeler version 2.1.0, the SimmID is for internal use only and is no longer accessible through the graphical user interface. It may be accessed through the API, if necessary.
Short Name
A short name (simplified as "name" in many cases) is a property of an entity or a rule provided by the user. If the user doesn't give a short name, the Simmune Modeler will assign a default short name.
Starting with Simmune Modeler version 2.1.0, a default name is given automatically in most of cases when a new entity/rule is created. The user may then modify the name.
Full Name
A full name is a propertiy of an entity or a rule provided by the user. If the user doesn't give a full name, the Simmune Modeler will assign the corresponding short name as the default full name.
Annotation
Free text for the user to provide annotations to an entity or a rule.
Molecule
A molecule is an entity in a model and refers to a biological molecule. A molecule is composed of molecule component(s).
Molecule component
A molecule component is an entity in a model. A molecule component can carry any (in principle) number of named states. Such states could, for instance stand for particular phosphorylation states of the molecule component.
A molecule component can be attached to another molecule component as a neighbor. A molecule component can have multiple neighbor molecule components within the same molecule.
A molecule component can have any (in principle) number of binding sites, but the molecule components of a molecule must have at least one binding site in total.
Molecule component state
A molecule component can have zero or multiple states assigned to it. Each
state is tagged with a name, called "state tag". A molecule
component state can have one of the following values: "on",
"off" or "don't care". The name of the
molecule component state tag must be unique within the molecule component.
The purpose of these state tags is to encode modifications the molecule
components experience in the course of reactions. The transition from
unphosphorylated to phosphorylated of a molecule component as part of a
complex of an Enzyme and a Substrate complex, for instance, could be encoded
with a state tag with name phosphorylated
that would switch from off to on as the result of a transformation of the
Enzyme:Substrate complex.
Binding site
A binding site is an entity in a model. A binding site can have any number of binding possibilities to mediate associations between molecules within molecular complexes.
Binding site status
A binding site can have one of the following states: "bound",
"unbound", or "don't care". Binding sites that
are involved in the binding between two molecules of a complex are
automatically in the state bound. For
binding sites that are not involved in bonds with explicitly specified
binding partners (other binding sites of other molecules) the user can
specify a binding state to restrict the allowed states for the specification
of reactions. The user could, for example, specify that a certain
transformation of a complex can only take place if a particular binding site
in the complex is unbound. On the other
hand, if the state of this binding site does not affect the transformation
the user would specify its state as don't
care. In the latter case, during the simulation of the model
all complexes would be subject to the transformation that match the
structural properties (molecules, bonds, components states) of the specified
complex with the additional degree of freedom that the binding site with the
don't care state could be involved in
a bond not specified explicitly in the complex. In the case of unbound only those complexes that do not have a
bond at the specified binding site would experience the transformation,
whereas specifying a bound state would
allow only those complexes to perform the transformation that have bond at
the site (regardless of the actual binding partner if it is not explicitly
defined in the complex). The examples will clarify this further.
Molecule interaction
A molecule interaction is a rule in a model. A molecule interaction describes the binding relationship of a pair of binding sites.
A molecule interaction can also be referred to as a binding site interaction.
Complex species
A complex species is an entity in a model.
A complex species refers to a set of complexes composed of the same set of molecule(s) and binding site interaction(s) within the complex. If a complex species has more than one molecule, each molecule should directly or indirectly be connected to all other molecules within the complex species through binding site interaction(s) -- in other words: a complex species has to be simply connected.
The default name (or short name) for a complex species is composed
of the names of molecules. For example, a complex species that is
composed of molecules A, B and
B, would have a default name "A.B.B".
If the default name has been taken by another complex species, a
suffix number is added to obtain a unique default name such as
"A.B.B.2". A single molecule complex species will
have the molecule name as its default name.
Complex
A complex is an entity in a model and related to a complex species. It shares the binding structure of all complexes belonging to the same species but can have unique states of its molecule components and binding status of those binding sites not used for explicit bonds (with explicitly specified binding partners within the complex species).
A complex is uniquely identified by the complex species name, the combination of its molecule component state(s) and the combination of its binding site status.
If there is no "don't care" state defined in any molecule component and binding
site, a complex defined in the Simmune
Modeler corresponds to a fully specificied complex. Such
complexes can be used to specify initial biochemical compositions of
simulated cells. In contrast, if there is at least one "Don't
care" state in its molecule component(s) or binding site(s),
the complex is not fully specified but rather corresponds to a group of
complexes having the same molecular components and binding structure and
matching those states that are not don't
care. We will sometimes refer to such complexes as
patterns. This simplifies the
definition of reaction rules: rules can be built to be applied to
classes of complexes sharing particular properties (such as
phosphorylation of certain phosphorylation sites or possessing certain
unbound binding sites).
State tags in molecules, complex species and complexes
State tags in molecules in the molecule definition tab or as part of complex species indicate which states can be defined for the specification of particular complexes or patterns. The small squares symbolizing their state tags therefore are neither full (corresponding to on) nor empty (corresponding to off) nor empty with a dotted line (corresponding to don't care) but instead show a diagonally divided coloring to remind users of the fact that they are dealing with a complex species.
Complex transformation
A complex transformation is a rule in a model.
A complex "source" can undergo a transformation into another complex "result" with a certain transformation rate. The complex species of the "source" and "result" complexes must be the same, or equivalent. "Equivalent" complex species may differ only with regard to intra-complex bonds. For instance, the breaking of one bond may transform a "closed ring structure" complex into an "open ring structure" complex.
Complex association
A complex association is a rule in a model.
A complex association describes how a complex interacts with another complex to generate a result complex through the formation of a bond between the two, mediated by a binding site interaction and proceeding with a given association rate. Associations can involve state changes.
Complex dissociation
A complex dissociation is a rule in a model.
A complex dissociation decribes how a complex splits into 2 fragment complexes with given a dissociation rate. Dissociations can involve state changes. Dissociations declared as 'Intra-complex' break a bond within a complex without creating two separate fragments (i.e. the complex after the dissociation is still held together by internal bonds).
Intra-complex dissociations can be replaced by transitions between equivalent (i.e. differing only with regard to intra-complex bonds) complexes. However, Intra-complex dissociations sometimes offer more flexibility because it is possible to specify only the interacting molecules and binding sites of the complex. The software generating the reactions from the reactions rules will apply these intra-complex dissociations only to complexes that will - after the dissociation - maintain a connected structure.
Note on "Don't Care" molecule
component states or binding site status
Don't care states for the binding status of binding sites or the states of molecular components can help making the composition of models much simpler than it would be if all states would have to be defined explicitly. During the simulation of a model, however, the simulated biochemistry never actually contains molecule complexes with don't care states. At the beginning of such simulations, the biochemical compositions of all cellular and extracellular regions has to be specified using complexes without don't care states. During the simulations, the rules that contain don't care states are applied to those complexes that match the patterns specified by the rules: complexes having the same molecular components and binding structure as the complexes in the rules and matching those states that are not don't care.
The meaning of don't care in a rule differs depending on whether the corresponding complex acts as "source" or as "result" within the reaction rule.
For a source complex in a rule such as a transformation, association or dissociation, a molecule component with a don't care state means the state can be either "on" or "off" in a complex in order to be subject to the reaction. Similarly, a don't care binding status means the binding site can be "bound" or "unbound".
For a result complex a molecule component's don't care state means the state will be inherited from the corresponding molecule component state in the source molecule.
Note on the mapping between source and result molecules in reaction rules
In all rules defined by Simmune Modeler, the molecules in source complexes have a "1 to 1" mapping relationship with the molecules of the result complexes. In some cases - when the complexes in a transformation rule contain multiple molecules of the same type and the binding structure does not uniquely determine the mapping (for instance in a ring) - the user may have to specify the mapping manually. This will be described further below.
"Negation" to molecule component
states
Sometimes it is easier to specify what properties a complex must
not have in order to be subject to
a particular reaction rule. This can be done by negating component
states: If a molecule component in a source complex has more than one
state tag with states "on" or "off", the user
can add a "negation" the states of the component. Consider,
for example, a molecule component with 2 state tags "s1"
and "s2". The negation of "s1(on)" and
"s2(off)" would cover the following states: (1)
"s1(on)" and "s2(on), (2)
"s1(off)" and "s2(off) and (3)
"s1(off)" and "s2(on).