Stochastic Simulation Service: Bridging the Gap between the Computational Expert and the Biologist

We present StochSS: Stochastic Simulation as a Service, an integrated development environment for modeling and simulation of both deterministic and discrete stochastic biochemical systems in up to three dimensions. An easy to use graphical user interface enables researchers to quickly develop and simulate a biological model on a desktop or laptop, which can then be expanded to incorporate increasing levels of complexity. StochSS features state-of-the-art simulation engines. As the demand for computational power increases, StochSS can seamlessly scale computing resources in the cloud. In addition, StochSS can be deployed as a multi-user software environment where collaborators share computational resources and exchange models via a public model repository. We demonstrate the capabilities and ease of use of StochSS with an example of model development and simulation at increasing levels of complexity.


Try StochSS
It is possible to try StochSS online at try.stochss.org by signing up with your e-mail address. Nothing has to be installed locally, and all modeling capabilities of StochSS are available. It is not possible to take advantage of advanced cloud capabilities (see Section 6) through the try.stochss.org-server, so for the user with the need to run large-scale computations, we recommend to consider a local install after trying out StochSS online.

Install StochSS
StochSS supports Mac OS X, Linux, and Windows through the Docker platform. To install StochSS, you will need to install Docker on your computer, and then use the appropriate StochSS launch application to initialize and run your StochSS Docker container. Docker is free software that automates the deployment of Linux applications inside software containers. To download Docker, visit https://www.docker.com/. For instructions on how to install the latest version of StochSS for your platform, please see the StochSS website http://www.stochss.org/. The source code, together with installation instructions, is also available on GitHub: https://github.com/StochSS/stochss/tree/master/stochss-launcher.

Basic Introduction
This tutorial will guide you through the basic features of StochSS. You will become familiar with the Model Editor and the Simulation Manager. You will learn how to create your own model, which can be population or concentration-based, and how to simulate it using either an ordinary differential equation (ODE) solver or the stochastic simulation algorithm (SSA).

Creating Administrator and Standard User Accounts
At the end of a successful installation process, your default browser will launch and you will be asked to create an admin account as in Figure 2.1 (there is only one admin account for the entire system). Once the admin account is created you will be forwarded to a regular login page where you can log in to StochSS. Users can click Create Account to request an account. The account will not be accessible until the admin approves it in the Admin Panel (the admin can also delete active users as well as reset their passwords there).

Importing a Model
The Model Editor will let you create new or modify existing well-mixed stochastic biochemical models as well as deterministic models based on ODEs. The best way to get started with the model editor is to import an example model and look at the different sections.

Creating a New Model
An example population model is defined by the following two reactions: To create this model: 1. Navigate to the Model Editor.

Click Add Model and select Population, Well-mixed.
3. Rename the model to example.

Click
Create Species twice to create two species.
5. By default the species are named S0 and S1. Set the initial condition for S0 to 1000 and the initial condition for S1 to 0.
6. Similarly to above, click Add Parameter twice to add two parameters.
7. By default they will be named k0 and k1. Set k0 to 0.0001 and k1 to 0.05.

Running a Simulation and Visualizing results
For this section, create or import a model using the directions above.
1. Navigate to the Simulation Manager page.
2. Select the model you wish to simulate and click Next.
3. Setup your simulation parameters: name, time, data storage frequency, realizations and solver type.
a) If you are simulating a population-based model you can choose between the deterministic and the stochastic solvers.
b) Concentration-based models can only be simulated using the deterministic solver.
4. Click Run Locally. You will be automatically forwarded to the Job Status page.

Click
View to open the Job summary page, where you can visualize the simulation's trajectories. 6. Click Access Local Data to download a raw copy of the data. This can be used to share data between StochSS installations or perform manual data analysis.

Converting a concentration model to population
Create a concentration model or use the directions above to import one. Both Lotka-Volterra examples are concentration based and are available both as XML files and Public Library models.
1. Select the newly minted concentration model.

Click
Convert to Population on the right-hand toolbar to start the conversion process. The model conversion page will open.
3. To convert a concentration model to a population, a system volume must be specified.

Given a volume, StochSS converts initial conditions through
and attempts to convert the reaction rates. It is not always possible to convert reaction rates automatically. During the conversion process StochSS lists all the reactions, and notifies the user of which reaction rates were successfully converted and which were not. If automatic conversion fails the conversion still proceeds, but the user now has to correct the reaction rates that were not automatically converted.

Click
Finish conversion at the bottom left of the page to create a population-based model. This newly created population model can be simulated using both deterministic and stochastic solvers.
6. Click Cancel conversion to cancel the conversion.
The conversion process operates correctly only if the model to be converted is entirely based on the mass action kinetics allowed in Gillespie Stochastic Simulation Algorithm [1]. If the model to be converted is not entirely based on mass action kinetics, the conversion tool only converts what it can.

Backup and Transfer your Data
You can backup or share your saved models and simulations with the StochSS ZIP format. There are three ways to create StochSS ZIP files: • Navigate to the Backup page in the left-hand toolbar and click Export. This exports a ZIP containing all models and simulation results for the current user. There is an option to export all data for all users if this page is accessed with the admin account.
• Select a model on the Model Editor page and click Export to .zip.
• Click View on the Job Status page, and then click Access local data.
These ZIP files can all be imported into StochSS on the Backup page. To import the contents of a ZIP file into StochSS: 1. Navigate to the Backup page.
3. Select the ZIP file to upload. The file should automatically begin uploading, and then appear in a table of ZIP archives below.
4. Select the ZIP file in the table.
5. Define the behavior of the import by either limiting what files get imported or specifying how overlapping names are handled. 6. Click Import at the bottom of the page.

Exporting data from an old version of StochSS (1.2 or previous)
To create a backup archive from an older version of StochSS, execute the following command from a terminal window in the directory of your new StochSS installation: ./exportserver.py path_to_your_old_StochSS_installation You can import the backup archive you created as described above.

Sensitivity Analysis
StochSS implements forward sensitivity analysis based on the CVODES ODE solver [2]. For instance, if we consider the population of P and the parameter V max in the Michaelis-Menten model in the Public Library. The sensitivity of the rate of the increase in population P to the parameter V max is defined as the incremental rate of change in P due to incremental changes in V max: These are the sensitivities that StochSS produces. There is no rescaling to make these sensitivities unitless.

Example: Estimate parameters of a birth-death model
We consider the Birth-Death model that can be imported from the StochSS Public Library (see Section 2 for instructions on how to import models in StochSS). After the model has been imported: 1. Select Parameter estimation from the menu on the left of the screen.  4. Upload and select these example files.
5. Configure the checkboxes to only perform parameter estimation on k1. For the example model, the value of k2 is already optimized.
6. Click Run Locally to start the parameter estimation.
7. Select Job Status from the menu on the left of the screen to monitor the status of your submitted job. For the example trajectory data, k1 = 1.0 and k2 = 0.03 are the correct parameter values so the simulation should converge to somewhere close to these.

StochOptim input file format
The StochOptim input data format consists of two tab-separated text files. The first file represents the initial conditions of the system, and the second file represents trajectories of it. Each file has three base columns. Time, Rep, and Weight. Additional columns are added for every species in the model that parameter estimation is to be run on.
• The Time column contains the time values of the various trajectories (and should be set to zero for the initial conditions file).
• The Rep column is used to include multiple trajectories in one file for fitting. Basically each trajectory should have a different Rep number.
• The Weight column is currently unused and should be set to 1.
• The rest of the columns should be named after the species (case-sensitive) in the model the data will be fit against, and the columns themselves should contain integers representing the population counts at the various time points.
An example of this can be seen by comparing the files birthDeathTrajectories.txt and birthDeathTrajec-toriesMulti.txt in the examples folder included in the StochSS package.

Spatial Stochastic Simulations
The spatial stochastic simulation capabilities in StochSS are based on PyURDME [8]. PyURDME is a general software framework for modeling and simulation of stochastic reaction-diffusion processes on unstructured, tetrahedral (3D) and triangular (2D) meshes. The current core simulation algorithm is based on the mesoscopic reaction-diffusion master equation (RDME) model. The default solver is an efficient implementation of the next subvolume method (NSM) [7].

Example: Annihilation of two species in a cylinder
We will build a simple annihilation model based on an cylinder geometry. At each end of the cylinder, different chemicals will be produced. When they diffuse and meet at the center, they will annihilate each other.
1. Navigate to the main Model editor. 5. Click Initial Condition, select scatter, and add 500 molecules of species A in subdomain 1 and 500 molecules of species B in subdomain 3.
6. Add two parameters, k0 and k1, and set their values to 1 and 100, respectively.
7. Add three reactions: R1 : Reaction R1 should be restricted to subdomain 1 and reaction R2 to subdomain 3. Reaction R3 should be allowed throughout the whole domain.
9. The model is now complete and ready to be simulated. 10. Navigate to the Simulation manager page.
11. Select the spatial model you just created and click Next.
12. Setup the simulation parameters: name, time, data storage frequency, and number of realizations.
13. You can specify a random seed for the random number generator under Advanced Settings.
15. In a few seconds you will be directed to the Job Status page where you can check the status of your simulation.
16. Once your simulation is complete, click View results to open the Job summary page, where you can visualize the diffusion of the two species over time within the cylindrical container and download the output files of the simulation.

Credentials
StochSS provides the options to run jobs using the Amazon cloud infrastructures. In order to use Amazon Elastic Computing Cloud (EC2), Simple Storage Service (S3) and DynamoDB database, which are all required for running jobs in the cloud, you need an Amazon Web Services (AWS) account and a credential pair (consisting of a secret key and an access key) in hand.
More information regarding how to create an AWS account and get credentials can be found here: http: //aws.amazon.com

Setting Credentials in StochSS
You must set your credentials in StochSS manually (Figure 6.1). Once StochSS validates these, you will be able to launch compute nodes and run jobs in the Amazon cloud.

Launching and Shutting Down Nodes
Once valid credentials are entered, clicking Launch nodes (Figure 6.2) by default will launch one c3.large Amazon instance. This first node is designated the head node. Any other nodes launched are called worker nodes. There can be zero or more worker nodes, and they are c3.larges instance types by default. For information on Amazon instance types, look here: http://aws.amazon.com/ec2/instance-types/. The head node must be a c3.large or c3.xlarge. The worker nodes can be any combination of t1.micro, m1.small, m3.medium, m3.large, c3.large, and c3.xlarge nodes (chosen in the Advanced settings menu).
Only one head node is needed to run jobs in the cloud. It is possible to access cloud data even when no head nodes are launched. Compute resources and storage resources are billed separately by Amazon. More details can be found at: http://aws.amazon.com/ec2/pricing/.

Job Reproduction
StochSS provides the flexibility to store simulation output in the cloud or delete it and regenerate it later. If simulations are fast but produce large amounts of data, reproducing data only when it is needed can save money.

An Example on Job Reproduction
Reproducing a cloud job is simple: 1. Launch a compute node. CHAPTER 6. CLOUD COMPUTING 2. Run a well-mixed or spatial model (everything except parameter estimation jobs can be reproduced).
3. Navigate to the Job Status page. 4. Click view beside the job you would like to reproduce.

Click
Delete Output to delete output in the cloud. No reproduction action is available until you delete the output.
6. Once the output is deleted, the option to reproduce the job will be appear as shown in Figure 6.3.
7. Choose a node type for reproduction. If there is no such instance type running, a warning will show up to guide you to the Cloud Computing page to launch one.

Click
Reproduce Results to submit the reproduction request. This will automatically redirect to the Job Status page where the new job's status can be monitored.

Cost Analysis
Because different instance types cost different amounts of money, it is not obvious which nodes are the cheapest for any given job type. StochSS allows manual measurement of job cost with the cost-analysis tool. 5. By default, cost analysis should be available for whatever instance type the job was run on. 6. Click Analyze with any other node type you would like to run and analyze the job on. At least one node of this instance type must already be running.
7. The run times and costs of simulating the jobs are plotted on the screen as in Figure 6.4.

Parameter Sweeps
It is often of interest to explore the parameter space of a model. We may want to find what the value of some parameters should be, or maybe we want to find regions in parameter space where the model exhibits interesting behavior. StochSS supports sweeps over one or two parameters. To set up a parameter sweep, simply click Parameter Sweep. Select the model that you want to analyze, the parameters you want to analyze, the upper and lower bound of the parameters, and the number of steps in each parameter.
First import the lotkavolterra_concentration_oscil model from the Public Library. Select this model in the parameter sweep main window, and run a two-parameter sweep over k1 and k2. Click Run Local, and wait for the computation to finish. Once it has finished, the output can be visualized on the Job Summary page, see Figure 7.1. You have to select a mapper and a reducer, and can view the average concentrations, the max-and min-values, as well as the variance. As an example, if the mapper is 'final time', and the reducer is 'average', then that means that you will plot the average of the populations at the final time point. Another example is that the mapper is 'average' and the 'reducer' is 'max'. That means that we first take the average of each trajectory, and then the maximum of each average. The final output is then visualized in a graph or heatmap.
Finally, if you need to perform an in-depth analysis of the data, there is the option of exporting the parameter sweep to a Jupyter Notebook. On the Job Summary page, click Analyze using interactive Jupyter Notebook. This launches a Jupyter Notebook, with a template for analyzing the data. We recommend users unfamiliar with Jupyter to visit http://jupyter.org for full documentation and tutorials. In short, it is an environment for interactive computing, and users can analyze and plot their data with Python scripts. For example, given a two-parameter sweep, we may ask ourselves which parameter values give a specific output value. While it is possible to estimate that by simply looking at the heatmap, that is likely unsatisfactory in a real modeling project. With the full scripting capabilities of Python, the user could automate and make this process rigorous by modifying the Notebook correspondingly.

Visualization
Full three-dimensional spatial stochastic simulations can be difficult to analyze. To simplify the process, StochSS has built in three different methods for visualization of spatial models.

Surface Renderings with Domain Clipping
By default, spatial stochastic simulations are rendered as shown in Figure 8.1. These are surface renderings, but the simulations are volumetric. To see inside the volume, StochSS allows slicing the mesh in half along one axis with a plane and only rendering one of the resultant halves. This is shown in Figure 8

Colorized Wireframe Meshes
The second rendering type is similar to the first, but instead of rendering surfaces only edges are rendered (see Figure 8.3). The colorization is the same, it is just ideally easier to see inside the mesh. Similarly to the surface rendering the wireframe renderings can be clipped to get a clearer view of what is happening inside the volume. See Figure 8.4 for a demonstration of clipping a mesh in the Y dimension.

Volume Rendering
The final rendering StochSS offers is a volume rendering (Figure 8.5). It uses a basic ray-tracing implementation following the one in [10].

Visualization in Interactive Jupyter Notebook
In many projects the need to perform custom postprocessing and visualization will eventually arise. To facilitate this process, StochSS offers the possibility to export a Jupyter Notebook template, which reads the output and plots the average populations of the species. The user can then customize the Notebook to perform the required postprocessing and plotting.
To access this function, simply click Analyze using Interactive Notebook on the Job Summary page.

Import a custom mesh
When setting up a spatial problem in StochSS information about the geometry needs to be provided through two files: a file containing the mesh information in DOLFIN XML format and a text file containing information about subdomains. The file with subdomain information is optional in general (if it is not provided the entire mesh will belong to one subdomain). Below is a tutorial on how to provide that information in a variety of cases.

Mesh library
The first and simplest scenario is using one of the default built-in meshes provided by StochSS in the Mesh Library. These include simple example mesh and subdomain combinations that are common in biological modeling. For example there is a unit sphere with a membrane (i.e. the volume is one subdomain and the surface is another), a unit cube witha membrane, a cylinder with the two ends being different subdomains among others. If for a given problem these are not sufficient then mesh and subdomain information can be provided by attaching files. One simple case where creating and attaching a file may be necessary could involve using the DOLFIN built in meshes but with different subdomains than provided in the Mesh Library. This can be done as follows.

Using DOLFIN Built-In Geometry with Subdomains Outside of Mesh Library
For example consider a sphere with three different subdomains: the top half of the membrane, the bottom half of the membrane and the volume. This can be done using PyURDME as follows (PyURDME and FEn-iCS are software packages that are automatically installed during the StochSS installation and DOLFIN is a library within FEniCS).
In an IPython Notebook, import the appropriate libraries: And finally two files are created to store the mesh and subdomain information respectively in the the correct format: This is a dolfin xml file with mesh information dolfin.File("sphere_top_bot_mesh.xml") << model.mesh Now that these two files have been created they can be attached in the Mesh tab of the model editor in StochSS and the rest of the problem can be defined from there. Again it is important to note that if a problem does not involve subdomains then only the mesh XML file is necessary and the entire mesh will be given the same domain! One last situation that could arise in defining spatial information is that a mesh has to be created in external software then converted to the correct format.

Advanced mesh generation
For many real world applications the geometry involved will be more complicated than the built?in meshes provided by DOFLIN (and by extension StochSS). In these situations a mesh will have to be created in an external program such as Gmsh then converted into the DOLFIN XML format. Once the mesh has been created in an external program the conversion to DOLFIN XML format can easily be done by the built in script dolfin?convert [1]. The following command line code demonstrates how to convert from the Gmsh format (suffix .msh or .gmsh) to DOLFIN XML format.
The following needs to be run from the command line in the Terminal: dolfin-convert mesh.msh mesh.xml File formats that are currently supported by the dolfin-convert script can be found in the The XML file that is created from the dolfin?convert command can then be used directly in StochSS. If subdomains are required then a text file can be created using code similar to that above. Consider the situation where the XML file created was called "coli.xml" then the code to create a subdomain file consisting of the outer membrane would look as follows: