StochSS 1.9 Basic Introduction

← Back
Creating Administrator and Standard User Accounts
Importing a Model
Creating a New Model
Running a Simulation and Visualizing results
Backup and Transfer your Data


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 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.

Figure 1. Administrator login page.
Figure 1. Administrator login page.

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.

Importing an existing model

Option 1: StochSS Public Library

  1. Navigate to the Model Editor page.
  2. Click Import from Public Library in the right-hand toolbar.
  3. Select a model from the Public Library and click Copy Model to Library.

Option 2: Stochkit2 XML

  1. Navigate to theModel Editor page.
  2. Click Import from .XML in the right-hand toolbar.
  3. Select an XML file. A collection of example models can be found in the examples directory within the StochSS install folder.
  4. Click Import.

Option 3: SBML

  1. Navigate to theModel Editor page.
  2. Click SBML in the right-hand toolbar.
  3. Select an SBML file and click submit.

Note that due to limitations with the SBML standard, StochSS only supports non-spatial models in this format.
After importing the model, StochSS should display the imported model in the model editor.
Look through the page to see how the different Species, Parameters, and Reactions are defined.
By clicking Export to .zip, Export to Public Library, or Export to SBML the model can be shared across computers or shared amongst users of the same StochSS.

Creating a New Model

An example population model is defined by the following two reactions:
S0 + S0 &\xrightarrow{k1} S1\\
S1 &\xrightarrow{k0} \emptyset .
To create this model:

  1. Navigate to the Model Editor.
  2. Click Add Model and select Population, Well-mixed.
  3. Rename the model to example.
  4. 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$.
  8. Click Add Reaction to add two reactions. Select the reactants, products, rates and reaction types corresponding to \eqref{eq:tut1-reac1}. Compare to Figures 2 and 3 to verify the settings.

Figure 2. Dimerization reaction.
Figure 2. Dimerization reaction.

Figure 3. Decay reaction.
Figure 3. Decay reaction.

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.
    1. If you are simulating a population-based model you can choose between the deterministic and the stochastic solvers.
    2. 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.
  5. 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.
  2. 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.
  4. Given a volume, StochSS converts initial conditions through
    \mathrm{initial\_condition\_population} = \mathrm{initial\_condition\_concentration}\times\mathrm{volume}
    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.
  5. 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:

  1. 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.
  2. Select a model on the Model Editor page and click Export to .zip.
  3. 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.
  2. Click Import.
  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:

./ path_to_your_old_StochSS_installation

You can import the backup archive you created as described above.
← Back