Tutorial. Download and Installation. Context. Attractor Reachability Analysis in GINsim: Firefront and Avatar

Transcription

1 Tutorial Attractor Reachability Analysis in GINsim: Firefront and Avatar Download and Installation Download: Avatar is implemented within GINsim. The documentation of the alternative services provided by GINsim can be found in Requirements: Java version 6 (JDK v1.6/jre v6) or superior. 4GB of free RAM are suggested for the exhaustive analysis of complex models. Installation Notes GUI: to run the desktop GUI either click directly on the provided.jar or use the following command on your MAC/Linux/Windows console: java -jar GINsim-[version].jar, where [version] should be replaced by the downloaded version. To control the amount of available memory add -Xmx[memory] m to the previous command where memory defines the number of allocated megabytes (e.g. java -jar -Xmx2048m GINsim jar to allocated 2GB). API: to use the programmatic interface within your Java project: 1) add the provided GINsim.JAR as a library, or 2) unzip the provided source-code, create a Java project (e.g. by opening the folder as a Java Project in Eclipse), and customize and run the disclosed testing classes. Script: to run simulations using a script, please edit the illustrative Python scripts provided in scripts/ folder and run the following command on your console: java -jar GINsim-[version].jar -s [scriptname] [input-model] [output], where version corresponds to the downloaded GINsim version, scriptname is the script file name, input-model optionally specifies the input model and output is the output file name (e.g. java -jar GINsim jar -s scripts/avatarscript.py sp1.zginml outconsole.txt). Context The Avatar software relies on logical formalisms to describe the discrete dynamics of gene regulatory and signalling networks in order to identify attractors and estimate their reachability from a given portion of the state space. For this aim, we consider the generalised modelling framework initially introduced by R. Thomas and collaborators [?] and implemented in our software tool GINsim [?], where the regulatory dynamics of a concurrent system can be translated into state transition graphs. In this context, three algorithms are make available to analyze the asymptotic behaviour of a given system: traditional MonteCarlo simulation (approximate) for an approximate reachability analysis of stable states and complex attractors (assuming apriori knowledge of the states within terminal cycles); Firefront simulation (quasi-exact) for the exhaustive estimation of the reachable stable states and compact complex attractors; Avatar simulation for an efficient discovery of stable states and complex attractors (even in the presence of arbitrarily-complex transient and terminal cycles) and approximate reachability estimation; 1

2 Running GUI: Figure 1 illustrates how to access Avatar services within GINsim, while Figure 2 provides the opened window to parameterize and run Avatar, Firefront and MonteCarlo. The desktop GUI is compatible with Linux/Mac/Windows operating systems, supports multiple model formats, performs soundness checks and provides visual representations of the outputs. Figure 1: GINsim: importing a model and accessing the dedicated window for attractor analyzes. Figure 2: Analysis of reachable attractors: Avatar, Firefront and Monte Carlo parameters. The Run button executes the selected algorithm over the inputted model and displays the progress of the search (as well as additional informative messages) at the bottom of the window (see Figure 3). The user can force the termination of the search by clicking on the Force exit button. API/Script: the API is accompanied with the javadoc documentation and with customizable testing classes to parameterize and run the algorithms. The use of the API is suggested for an easy parameterization, adaptation or extension of the proposed simulations. We also provide the possibility to call the algorithms within Python scripts. The parameterization of the algorithms (when either recurring to the API or Python scripts) can be done by inputing in text format the name of the parameters and their value (whenever applicable). The parameters that are not inputted or whose values are not specified are initialized with default values. An illustrative script with a textual call to the Avatar algorithm using the parameters illustrated in Figure 2 is: 2

3 avatar = gs.service( avatarservice ) result = avatar.run( strategy=matrixinversion runs=1000 maxdepth=10000 tau=4 mincyclesize=3 maxgrowthsize= maxrewiringsize=4000 mintransientsize=100 keeptransients keepattractors quiet plots outputdir=/output input=models/sp1.avatar ) print result.tostring() Figure 3: Execution of a simulation. Input Model. GINsim accepts a wide-variety of formats specifying how the components of a system affect each other, including the native GINML format, BoolSim, Cytoscape, NuSMV, Petri Net, SBML-qual and truth tables. Some of these formats further allow for the specification of the set of valid initial states for the target system; its input and output components; and apriori known attractors. For more details on how to specify, import and export discrete models of concurrent systems please check GINsim documentation: Model Customizations. Four major types of customizations can be applied over the input model: perturbations to the regulatory graph inferred from the model [A1]; applicable reductions to the model [A2]; addition/selection/removal of states to the original set of initial states [A3,A5]; incorporation of known attractors (referred as oracles) to guide the simulation [A4]; Parameters. Table 1 describes the parameters (and respective default values) of each one of the simulation algorithms. Despite the large number of parameters, particularly regarding Avatar simulations, our software provides effective default behavior that for some parameters is dynamically estimated from the properties of the input model. Saving Contexts. The context of a simulation is characterized by the applicable customizations to the input model and the parameterizations of the selected simulation method. Contexts can be easily created, removed, selected and modified using the left panel of the GUI [A6]. The user can also preserve these contexts 3

4 Notes Suggested value Sim Name Description Avatar should be selected for complex attractor analysis, while FF for a quasiexact reachability estimation. P1 algorithm selected type of simulation: {MC,FF,Avatar} P2 quiet whether detailed logs are to be printed true false hampers efficiency (suggested for debugging purposes only) outputdir directory to save the outputs (for console/script mode) /output P3 n runs number of iterations 10 5 P4 τ tauinit cycle expansion rate: τ τ 4τ 8τ 16τ 3 P5 δ maxsteps maximum number of visited states per simulation 10 5 MatrixInversion computes the exact prob. of the rewired paths (prone to memory bottlenecks) UniformExits randomly selects exits (efficient yet reachability can be biased) Matrix Inversion P6 strategy Avatar rewiring strategy P7 keeptransients whether transient cycles should be kept between iterations suggested true for MatrixInversion and false otherwise Avatar 200 guarantees that only the larger transients are preserved to foster memory and time efficiency minimum number states within a transient cycles to be kept for subsequent simulations P8 mintransientsize P9 mincsize minimum number of states within a cycle for rewiring 4 P10 maxrewiresize maximum number of states within a cycle to be rewired 500 approximate searches should be applied with a high value (10000), while MatrixInversion according to available memory (500 for 1GB RAM, for 8GB RAM) P11 maxpsize maximum number of states within a cycle to allow expansion no limit essential for the discovery of terminal cycles (should be only decreased to guarantee the scalability on models with highly complex transient cycles) 4 prevents a simulation to get locked within complex cycles (FF behavior is however able to model complex attractors from oscillating behavior and stop simulation) P12 δ maxdepth limit depth (number of expansions) within each simulation 1000 P13 α alpha minimum probability for a state to be expanded 10 5 states with probability below alpha are included in the neglected state-set P14 β beta max residual probability of prob. states to stop simulation 10 5 α β 1000 supports the convergence of the algorithm for large sets of probable states maximum number of states to expand per iteration (non-expanded states preserved for upcoming expansions) P15 maxexpand Firefront P16 n runs number of iterations 10 5 the reachability lower and upper bounds are computed based on successful iterations (attractor found below maximum depth) P17 δ maxdepth limit depth (number of visited states) within each simulation 1000 prevents a simulation to get locked within a terminal cycle or complex transient Monte Carlo Table 1: Description of the parameters of the simulation algorithms according to their name and location within the GUI (see Figure 2).

5 across sessions by saving and loading them. For this aim, the user just need to close the Avatar window and access the File Save As tab and then choose a file to keep the model and its context. When running GINsim, these contexts can be recovered by opening the saved.zginml file. Figure 4: Saving and loading parameterizations. Output Textual Display. The results of the simulation algorithms are displayed after their execution, describing the found attractors, their reachability as well as additional information dependent on the selected simulation: MonteCarlo specifies the average depth of the found attractors; displays the support of iterations used to compute the reachability of the found attractors as many iterations may be truncated due to the presence of transient cycles or the high depth of stable states. Firefront specifies the lower and upper bounds on the estimated probability of the system ending in a stable state (the true reachability is within these bounds). Avatar infers a set of pattern-states from a complex attractor to guarantee its compact presentation; specifies the average depth of the found attractors; provides statistics on the number and average length of found transient cycles. Visual Display. In addition to the previous textual results, we make available: plotting facilities: Firefront is able to plot the number of states in the F, N and A state-sets along the iterations, as well as the progression of the cumulative probability for each one of these state-sets; Avatar is able to plot the progression of the probability estimates per attractor along the iterations, as well as the depths at each attractor were discovered. Figure 6 illustrates these possibilities; the visual display of the state transition graphs associated with the complex attractors are made available when running Avatar from the GUI; Verbose Mode. The algorithms can be executed in verbose mode for debugging purposes or to further characterize their behavior. 5

6 Figure 5: Illustrative results from different simulations. Figure 6: Illustrative charts plotted by Avatar and Firefront. Figure 7: Display of logs. 6

7 Figure 8: Visual display of a complex attractor with pattern [1,0,1,1,0,1,1,,0,,0,0,0,0,0,0,0,1,1,1,1,1,0,1,0,1,0,0,, ]. 7