User Manual

GINsim is a software supporting the definition, the simulation and the analysis of regulatory graphs. The underlying multilevel logical formalism leans on the definition of two types of graphs: regulatory graphs, which model regulatory networks, and state transition graphs, which represent their dynamical behaviour.

GINsim 2.3 is freely available for academic users, please contact us for other uses. The GINsim website (http://ginsim.igc.gulbenkian.pt/) provides the latest official version of the software, documentation, as well as a model library.

GINsim is a Java application and should thus run on any system offering a Java virtual machine (version 1.4 or later). If Java is not already installed on your computer, it can be downloaded:

Other system requirements depend heavily on model size. To work confortably, a computer with at least 512Mo of RAM is required. A screen resolution of at least 1024x768 is recommended.

GINsim is available in two forms:

	Tip
	Large models may require an increase of the amount of RAM available to the Java virtual machine. This can be done: for the jar file, with the command java -Xmx300M -jar GINsim-$version.jar (replace 300 by the amount of RAM you want, in Mo); for the archive, by changing the value of the JAVAMAXMEM variable in the launcher script.

The next section covers the Graphical User Interface of GINsim, mostly through the presentation of the main menu options. Section 3 presents the editing tools dedicated to regulatory graphs. Section 4 is dedicated to simulation (i.e. the generation of state transition graphs). Finally section 5 and 6 present analysis tools.

For a first introduction to GINsim, the GINsim tutorial may be a better starting point. This manual uses as much as possible the same examples and figures.

Noteworthy improvements:

New features:

When GINsim is launched, its main window opens (see Figure 1). This window is divided into three parts:

Figure 1 . The main window of GINsim

The main window of GINsim, featuring an empty model.

In the following, the contents of the menus are described.

Figure 2. File menu

The File menu offers all the classical options to open/save a file, to open/close a window, and to quit the application.

The File menu provides the following options:

Some of these actions (New, Open and Save) are also available from the toolbar.

Figure 3. The save dialog

The Java Save dialog allows to browse and create folders, as well as to choose their location. By default, only folders and GINML files are shown; other files can be seen by removing the GINML Files filter. The drop-down list on the right side allows to select the graphical attributes to save. The ExtendedSave checkbox allows to enable or disable extended save (which generates an archive containing the graph and related data).

	Tip
	If the Extended Save option is selected, the file is saved in an archive (zip file with a .zginml extension) instead of a xml file (with a .ginml extension). This allows to save related data, such as simulation parameters or mutant definitions, along with the model. These files need GINsim 2.3 or later to be opened.

Figure 5. The View menu

The View menu allows to control the zoom factor and to set some display options.

The View menu encompasses the following items:

Figure 6. The Actions menu

The Action menu for a regulatory graph.

Different actions can be performed from this menu, depending on the type of graph. Individual actions are detailed in the relevant part of this manual. Currently available actions are:

This window, which is originally attached to the main frame, offers a bird view of the graph and 3 tabs:

The Modelling Attributes and Graph Attributes tabs are specific to the type of graph and will be detailed later on.

Different tabs are activated depending on the current selection:

Graphical Attributes

The Graphical Attributes tab in the secondary window allows to change the visual properties of the graph elements.

• Nodes:

  • background and foreground color,
  • shape and size.

Figure 9. Graphical attributes for nodes

• Arcs:

  • line color,
  • line width,
  • intermediate points: they can be either automatically or manually placed,
  • drawing method: straight from one point to the next one, or following a bezier curve.

When the option for intermediate points is set to Manual, the points can be added by right-clicking on an arc. As the underlying drawing tool does not support ctrl+click to emulate right-click on Mac OSX, an additional toolbar button allows to insert them with a normal click ().

Figure 10. Graphical attributes for arcs

Tip

Buttons on the right side of the tab allow to apply the selected graphical attributes to additional elements: Apply to All: apply the selected attributes (those for which the checkbox is selected) to all nodes (or edges) of the graph. Note that, if several elements are selected, the selected attributes are only applied to the selection. Set as Default: use the selected attributes as default for elements that will be created in the future.

When a graph is generated (state transition graph or graph of the strongly connected components), the user can choose to display it, to perform some actions on it or to save it, through the What to do dialog box.

Figure 11. The Processing the New Grah dialog box

For state transition graphs, the number of stable states appears at the top-right corner.

Clicking on the "OK" button performs the selected action. This dialog box remains available to perform different actions on the graph. This dialog is closed when the graph is displayed, as all actions can then be performed through the Actions menu of the GINsim window.

Annotations can be attached to the different components of the regulatory graph:

An annotation is composed of a textual comment and a list of URLs.

Figure 12. Annotations

The same Note panel is used for all elements supporting notes. This screenshot shows this panel in the Graph Attributes tab.

Genes are always ordered in GINsim. This order has no effect on the regulatory graph itself but may affect the (partial) simulation and the state transition graph (the same order being used in the states names). The default order follows the chronology of node additions. This order can be modified using the arrows on the left side of the Graph Attributes tab.

Figure 13. Changing gene order

The left part of the Graph Attributes tab of a regulatory graph lists all genes of the model and allows to modify their order. The "up" and "down" buttons move selected genes in the list.

	Tip
	In all lists, several elements can be selected using the ctrl key (apple/cmd key on Mac OS X) or shift key. Several lists can be reordered using the "up" and "down" buttons.

When a single gene is selected, the Modelling Attributes tab allows to define its properties:

Figure 14. Attributes of a gene

Properties of the gene Cro, as defined in the lambda4 model (used in the tutorial and available in the model repository.

	Note
	The Modelling Attributes tab is divided into two parts. The Annotations and Parameters buttons (bottom left) respectively select annotations and logical parameters editing.

Logical parameters

When a gene is selected, logical parameters for this gene can be defined in the right part of the Modelling Attribute tab. The panel dedicated to the definition of logical parameters is divided into three parts:

• On the left, a table lists all defined logical parameters, showing their values and related interactions.
• On the right, the list of all incoming interactions on the selected gene.

• The central part contains the following buttons:

  • "<<" assigns the set of selected incoming interactions (from the right list) to the selected logical parameter,
  • "X" deletes the selected logical parameter(s),
  • "up" and "down" arrows reorder the selected logical parameters.

Figure 15. Definition of non zero parameters for C1

Annimate

The logical parameter panel, showing all parameters for C1.

Tip

While logical parameters can be numerous, usually many of them take the value zero. To ease parameter definition, only non-zero parameters have to be defined in GINsim. Adding the same set of interactions twice is impeded. The set of interactions associated to a logical parameter can be modified: select the parameter and the corresponding set of interactions will be selected in the right list. This set can then be modified, and the "<<" button applies changes. If the new interaction set is already defined in the list of logical parameters, nothing is changed. To add a new logical parameter when an existing one is already selected, select the empty line at the bottom of the list.

When a single arc is selected, the Modelling Attributes tab allows to define its properties

Figure 16. Properties of an arc

Properties of the Cro-N arc in the lambda4 model.

Depending on its activity level, a gene may have different effects on another one. The corresponding arc then contains several interactions, listed on the left.

GINsim keeps the definition of regulatory graphs consistent:

These automatic changes are necessary to keep the model valid, but they can alter it. Keep in mind that you need to double-check parameters after performing such changes.

	Important
	When a gene has several actions on another one, the activation ranges of these interactions should usually be disjoint, but GINsim does not check this property.

Checking activation intervals of interactions and the correctness of logical parameters is left to the user as adding more controls generates more annoyances than real help. Invalid logical parameters are highlighted to ease their detection. Keep in mind that a change in the activation-range of one of the interactions can turn a valid logical parameter into an ill-defined one. Parameters involving interactions from the same source with disjoint activity ranges are also ill-defined and thus highlighted for correction.

This dialog box allows to define a set of simulation settings: several simulation settings can be created, saved and restored with the graph, provided that the extended save is selected.

The right part of the dialog box enables the definition of the current simulation setting.

The left part of the dialog box enables to add, remove or switch between simulations settings.

The bottom part of the dialog box is dedicated to the definition and the selection of the initial states of the simulation (see Figure 17). A table lists and enables the definition of additional initial states. Note that the definition of initial states is shared between all simulation settings.

Each row of the table corresponds to a set of states. Gene levels are specified in the corresponding table cell. Multiple expression levels can be defined using semicolon (;) or in terms of list of values or intervals (denoted by a dash). The special value "m" denotes the maximal value of the gene. For example, "0;2-4" means "0 or values between 2 and 4"; "0-m" means "any expression level". The default, denoted by a "*", covers all possible values (it is thus the same as "0-m").

	Tip
	A value can be entered in a set of selected cells at once.

To be used for the current simulation setting, a row must be selected (using checkboxes in the second column). Only the states corresponding to the selected row(s) are considered for the simulations. If no row is selected, all possible states are considered generating a complete state transition graph.

	Note
	The "X" button deletes the selected row of initial states. The "reset" button unselects all selected rows.

GINsim facilitates the definition of mutants, which can then be selected before running a simulation. A mutant is a set of restrictions on the evolution of gene activity levels. The Configure button of the Mutant panel (in the simulation dialog box, but also in some panels) opens a dialog box, allowing to specify minimal and maximal activity levels for some genes. Once the activity level of a gene enters the specified interval, it can not leave it anymore, i.e. transitions pushing the gene outside of the interval are ignored. This enables the definition of different perturbations (knockouts or ectopic expressions for one or several genes) as an extension of the model. The simulation of more subtle mutants (conditional knockouts...) still requires modifications of the logical parameters.

	Warning
	These representation of mutants blocks some transitions, but does not affect trajectories where the activity level of the gene is outside of this range. Completely locking the expression level of a gene requires to properly set its initial values.

Figure 18. Mutant definition

Dialog box for the definition of mutants.

Annimate

Figure 19. Mutant simulation result

Result of an asynchronous simulation, where the expression level for Cro has been blocked at 1. The state transition graph is the same as the original asynchronous one, but all transitions where Cro leaves this value have been suppressed. This state transition graph is now composed of two disconnected parts, with a new stable state.

In a given state of the system, one or several genes are called to update their values. When several changes are pending, different construction strategies lead to different successor states and thus to different state transition graphs.

Asynchronous mode

In this mode, all changes are performed independantly. It will generate a state transition graph taking into account any possible trajectories. This mode is chosen by default.

A given state may have several successor states, each of them corresponding to a single updating of one gene level.

In this mode, the graph transition state can be generated "depth first" or "breadth first". The same state transition graph will be built, except if interrupted (for illustration, see depth and size limitation).

Figure 20. Construction strategy: synchronous versus asynchronous

Samples of simulation results for the lambda4 model, applying asynchronous and synchronous strategies to the same initial states (all states where C1=0 and Cro>0). Dotted arcs denote multiple, simultaneous transitions.

Priority classes

This strategy allows the user to group components into different classes, and to assign a priority level to each of these classes. In case of concurrent transition calls, GINsim first updates the gene(s) belonging to the class with the highest ranking. For each class, the user can further specify the desired updating assumption, which then determines the treatment of concurrent transition calls inside that class. When several classes have the same ranking, concurrent transitions are treated under an asynchronous assumption (no priority).

By default, all transitions belong to the same asynchronous class. Running a simulation without further configuration is thus the same as using the asynchronous assumption.

The left part of the configuration dialog box shows a list of priority classes (see Figure 21). The name of a class can be edited and a checkbox allows to change its internal mode from asynchronous (unchecked) to synchronous (checked). Buttons enable to add (+), delete (X), order (using the arrows) and group/ungroup (G) priority classes.

The central column lists transitions that belong to the currently selected class, while the column on the right displays all other transitions (i.e. belonging to other classes). To add transitions to the selected class, choose them in the right list an click on the "<<" button. The ">>" button removes the transition selected in the central list from the current class and add them to the first class in the list.

Finally, a drop-down list on the bottom left, allows to apply some predefined settings.

Figure 21. Definition of Priority classes

Annimate

Figure 22. Priority Class: example result

Example of simulation by priority classes. Two priority classes have been created. The highest ranked one is synchronous and contains C1, C2 and Cro. The other class contains only N. The resulting state transition graph is splited into two parts: N expressed versus N not expressed.

An option is also offered to limit the search depth and/or the total number of states generated in a simulation.

The limit on depth applies to all simulation modes, excepting the asynchronous breadth first one (where no information on depth is stored).

	Warning
	When considering several initial states, some of them can be reached while running the simulation from an other state. In this case, no new search will be triggered for them and the depth counter will not be reinitialised (i.e. the depth limit for these initial states will be shorter).

Figure 23. Limitation of the depth in the case of a depth first construction

State transition graph with all reachable states from the state "0111". The same simulation with a depth limit set to 2 keeps only the initial state and the nodes at a distance of two or less (i.e. the six white states).

The limit on the total number of states apply to all simulation modes. Under the asynchronous assumption, this limit has slightly different effects on depth first and breadth first search.

Figure 24. Limitation of the size (depth first and breadth first search construction)

The limit on the total number of nodes has different effects on depth first and breadth first state transition graphs. These examples show the graph of Figure 23 limited to 6 states. The first state transition graph was obtained using the depth first construction, whereas the second results from the breadth first one.

While the simulation is running, the bottom left corner indicates the size of the generated state transition graph. The simulation can be interrupted, using the Cancel button, without loosing the calculated part of the state transition graph.

At the end of a simulation, several options are available to save, display or analyse the resulting state transition graph (see processing a new graph).

The Stable States option of the Actions menu allows the analytic (i.e. without running a simulation) determination of stable states of the model. All stable states are determined, regardless of their reachability, using an algorithm described in [Naldi2007]. The stable states dialog box (see Figure 25) allows to run the analysis after the optional selection of a mutant. The result is shown in a table in the same dialog box, allowing to launch a novel analysis for another mutant. A "*" in the table denotes that each of the values of this component gives rise to a stable state (or several if another "*" appears in the same row).

Figure 25. The stable states dialog box, showing the result of the analysis

Regulatory circuits play crucial roles in the dynamical behaviour of a system. Indeed, positive circuits are required for the existence of several attractors, whereas negative circuits may generate cyclic attractors [Thieffry2007]. In [Naldi2007], we describe a method to analyse the dynamical roles of regulatory circuits. An implementation of this analysis is available in GINsim using the Circuits Functionality option of the Action menu (see Figure 26).

Figure 26. Finding and analysing regulatory circuits

A first dialog enables to select which circuits will be analysed, by specifying constraints on the length of the circuits or on the involved actors. By default all circuits are considered.

When this first step is completed, the second dialog shows the list of circuits and enables to run the analysis. When the analysis is completed, new branches then displays the functional circuits, classified according to their signs. When a circuit is selected, its functionality context is shown at the bottom of the dialog box. The analysis can be performed for the wild type model or for any predefined mutant.

Regulatory graphs can be exported into discrete Petri net using the rewriting method described in [Chaouiya2006].

Figure 27. The Petri Net export dialog

The Petri Net export dialog box allows to select the export format, the initial markup and the mutant to apply before exporting. The initial markup can be generated from an existing initial state of the model (modifications made in this dialog are also applied to the simulation settings); only the first selected state is used.

Regulatory graphs can be exported to the cytoscape format. As cytoscape is not a modelling tool, this export only preserves the structure and appareance of the graph, not the logical parameters. An experimental cytoscape plugin is available on request to perform the complementary operation (i.e. export a cytoscape model into GINML).

GINsim allows to compute the graph of the Strongly Connected Components (SCC graph, cf. http://en.wikipedia.org/wiki/Strongly_connected_component) of an existing graph, through the SCC graph option of the Actions menu. The SCC graph is an acyclic graph abstracted from the original one: each node of the SCC graph corresponds to a cycle or a set of intertwined cycles of the original graph. The resulting graph is thus usually much more compact.

Figure 28. Strongly Connected Components graph

Example of Strongly Connected Component Graph (bottom right) and the corresponding statetransition graph (top left). The Selection Attribute tab in the bottom panel shows the content of the selected SCC (i.e. the list of nodes in the original graph).

Note that the SCC Graph tool can also be applied to regulatory graphs.

The "search path" action enables the determination of paths between pairs of states of the state transition graph. Selecting the "search a path" action in the action menu opens a configuration dialog box, which allows the specification of a starting state, a target state , and optional intermediate states (using the "+" and "X" buttons to add/remove them). GINsim then performs a shortest path search. If several paths exist between these states, the first encountered shortest path is returned.

Figure 29. Search for a path in the state transition graph

The search tool has found a path from the state 0110 to 0311, involving four steps.

The animation tool is launched through the Animate option of the Action menu of a state transition graph. It allows to interactively follow a trajectory in the state transition graph. Genes of the regulatory graph are highlighted, to display the corresponding activity levels (cf. ???).

Figure 30. The animation plugin

Annimate

To follow a trajectory in the state transition graph, select a starting state. It is then colorized in blue and added to the trajectory (listed in the animation dialog box). Its successor states are highlited, and can be added to the trajectory upon selection, which in turns changes the available successor states.

To build another trajectory, select a state in the dialog and press the "<<" button to remove it and all of its successors.

To view the defined trajectory, select the starting state and press the "|>" button.

A path created with the animation plugin or found by the path finder can be visualized using gnuplot. The "GP" button (in the path finder and in the animator box) opens the gnuplot export box (Figure 31).

Figure 31. Gnuplot export box

The gnuplot export box enables the selection of the kind of graph to create as well as the genes to display.

After selecting the kind of output and the genes to display, click "export" and choose a place to save the plot. Note that two files are created but only the first file name is prompted for. If this filename is "myplot.gnuplot", the second file will then be named "myplot.data". The actual graph can then be displayed using the command load "mygraph.gnuplot" at the gnuplot prompt.

Figure 32. gnuplot export examples

Examples of the two kinds of gnuplot graphs. The first one uses arrows of different colors to show changes in the expression levels. The second one show separate subgraphs for each gene.