Basics

Details

Tutorials

Files

Oscill8 Documentation: Details

Installation

Currently, we only have a windows version ready for public use. (Release of a compatible linux version is planned for June 2005). You can get the latest release at SourceForge. Download all installers that you're interested in (the setup and examples installers will give you everything you need as a user) to your hard-drive and double-click them to install. It is highly recommended at this point that you use all the default settings the installer offers. Not doing so may make the current version of the tool unavailable to other tools like the BioSPICE dashboard.

At this point, you should have a working installation of Oscill8. For those eager beavers who aren't inclined to read the rest of this document, there are example ODE files and pre-created workspaces for you to play with in the $OSCILL8_DIR/examples directory. If you have trouble with anything, you can return to this document for help!

Workspace creation

Before starting, you need to have the right-hand-sides of your ODE model, along with initial values for the state variables and parameters, stored in a file. For lack of a better term, we'll call this file an ODE file. The format of this file is similar to the ODE format used by XPPAUT, though somewhat simplified. For those of you who already have ODE files for XPPAUT, they may very well work just fine for Oscill8 (as is more and more compatible every day!). If you have trouble creating the workspace with a particular ODE file, you can try using the "ode_clean.pl" perl script found in the $OSCILL_DIR/bin directory (see utilites for details) which will attempt to correct any features it knows Oscill8 doesn't support. Warning: For those of you modeling physical systems, note that in order to do proper bifurcation analysis, it is vital that you remove all conserved quantities from your differential equations. Failing to do so can lead to singularities (and possibly unexpected results in the early version of the code) while conducting bifurcation studies.

For those of you in the Biology community, you can also now import SBML files. This conversion is automatic (for files with the .xml or .sbml extension) if (and only if) you have JigCell installed, version >= 6.0.1. Warning: until version 1.2 of Oscill8 (see the roadmap for planned release dates), we Oscill8's model parser doesn't accept functional expressions. If you have an SBML file with functional expressions, then you'll need to use JigCell by hand to convert to ODE. Then you can use the "ode_clean.pl" perl script found in the $OSCILL_DIR/bin directory (see utilitesfor details) to make the file compatible with the current version of Oscill8.

If you don't have a particular model system in mind right now, you can use one of the examples included in the distribution. Look in the $OSCILL8_DIR/examples/ode diretory.

Now, with the ODEs in hand, we need to import them into Oscill8. This can be done in one of two ways:

1. From the command-line, you can run "oscill8 modelfilename", where modelfilename is either an ODE file or and SBML file. This will transparently create an Oscill8 workspace for you in the $OSCILL8_DIR/wscache directory. The workspace is your home for doing analysis of a particular model in Oscill8.


2. The other way to get started is to open Oscill8 (either from the command line, with no arguments, or by double-clicking the icon on your desktop). Then, click File -> New, which will open the workspace creation window (see below). You can supply a workspace a name, a base directory in which to create the workspace (note that the directory you give will have the workspace name appended to it to create your workspaces home directory), a model file (or just paste the text into the given model text box), and a few settings concerning your model. For details on these settings, see workspace creation settings). Once you've entered this information, click "OK" and your workspace will be created.

Settings

• postive state variables: this setting tells Oscill8 how to set default parameter and state variable ranges. If this is unchecked, each value, v, will be set to -|1000*v| < v < |1000*v|, otherwise it will satify |v/1000| < |v| < |1000*v|. (Actually, in the case of state variables, the minimum is set to zero when this setting is checked; this is more natural for state variables of a physical system). Note that all of these min/max values can be changed by the user later; this just affects the defaults (and if you have many parameters, it can save you a headache later!).

Navigating the workspace

Once you've created and are in a workspace, you'll notice that several new menu choices have appeared, including the "Workspace" and "Run" menus. In addition, you'll see an area to the left of the workspace, which is the run navigation area. As you do your analysis, this will be the place to return to access and modify what it is you have created. If at any time you would prefer not to see this run navigation area, simply click View->Run History, and you'll toggle the run navigation off. Another area that is not visible by default is the Run Notes, which appears just below the main graphing area (the bulk of the interface is the graphing area). You can toggle this feature on and off via the View menu as well.

There are context sensitive menus for both the run navigation area and the main graphing area by which you will conduct most of your activities (until you become familiar with the defined short cut keys). You can activate these menus with an alternate-click (right-click for most of us).

ODE file format used by Oscill8

The ODE file format used by Oscill8 is a pared down version of XPPAUT's ODE format. It includes the following elements:

• Velocity expressions

  These are arbitrary expressions defined in terms of other expressions, parameters, and state variables defined in the same file. For example, we might define two terms that show up in the RHS of our model several times:

  GtA=Gt-c1-c2
fx=xt-xy-yx-2*xyx
fy=yt-y-xy-yx-xyx-ayp


• Right-hand sides of the ODEs

  Algebraic expressions for the RHS of the model ODEs. These expressions can include any algebraic combination of velocites, state variables and parameters:

  dat/dt=k5p*GtA+k9*c1+k11*c2-k6p*at
dayp/dt=k3f*(at-ayp)*fy-(k3+k3r)*ayp-k6p*ayp
dc1/dt=k8f*GtA*tfp-k8r*c1-k10f*c1*tfp+k10r*c2
dc2/dt=k10f*c1*tfp-k10r*c2
dtfp/dt=-k8f*GtA*tfp+k8r*c1-k10f*c1*tfp+k10r*c2+k7f*fx*(tft-tfp-c1-2*c2)-k7r*tfp
dxt/dt=k1*M-k2p*fx-k2pp*yx
dxy/dt=k4f*fx*y-(k4r+k4)*xy
dxyx/dt=k5f*fx*yx-(k5r+k6)*xyx
dy/dt=-(k2fpp+k4f)*fx*y+k4r*xy+k3*ayp+(k2pp+k2rpp)*yx
dyx/dt=k2fpp*fx*y-(k2rpp+k2pp+k5f*fx)*yx+k5r*(xyx)


• "init" and "param" statements

  These special statements define which sybmols are state varaibles and which are parameters and gives their initial values. (In truth, the state variables are actually defined by the expression of the ODEs and the init statements simply set the values of those defined symbols. Parameters statements actually define--and make valid--the parameter symbols).

  init at=0, c1=0, c2=0, tfp=0, xt=0
init xy=0, xyx=0, y=1, yx=0

param Gt=1, M=0.3, k1=0.01, k10f=10000, k10r=1, yt=1
param k11=1, k2fpp=125, k2p=0.04, k2pp=1, k2rpp=4, k3=10, k3f=1250
param k3r=40, k4=35, k4f=4375, k4r=140, k5f=950, k5p=0.005, k5r=0.005
param k6=1, k6p=0.1, k7f=0.01, k7r=0.1, k8f=0.1, k8r=20, k9=10, tft=9


• global statements

  To mimic what has been done for XPPAUT, we support the "global" statement as a way of allowing discrete events to take place based on the zero of a function during the integration of the right-hand-sides. (A typical example would be cell division, when one state variable of the system is reset to half it's current value.) The syntax is simple:

  global sign { cond } { var=new }


  where "sign" is 0, +1, or -1 and specifies the sign of the derivative of "cond" when cond == 0; where "cond" is an algebraic expression made up of velocity, state variables, and/or parameters to be checked == 0; where "var" is either a state variable or a parameter (best not to put any space on either side of "=" sign for now!); where "new" is an algebraic expression made up of velocity, state variables, and/or parameters to be stored to "var".

  WARNING:This feature is experimental in release 1.1. See the roadmap for planned release dates of fully supported global.

In particular, one should note the lack of functional expressions and the fact that all mathematical expressions must be ALGEBRAIC combinations of velocities, state variables, and parameters. (This means NO special functions are currently defined, like "sqrt", "sin", or "exp"). The plan is to make our ODE format much more compatible with XPPAUT's format to include these missing features, but to aide users in the current situation, we have a utility that can convert XPPAUT's ODE format to ours (see ode_clean).

Runs

Time Series Integration

Currently, Oscill8 offers integration of ODE models via CVODE, an efficient stiff integrator. Oscill8 takes a fraction of a second to integrate fairly large, stiff systems with 30+ state variables by using a [relatively ;-)] efficient expression parser and CVODE.

To run a time series, navigate to one of the run menus -> "Time Series", which pops up the run configuration window (see here for detials on run configuration). For a time series, there are a few important parameters:

One and Two Parameter Continuation

Naturally, the primary purpose of this tool is to ease bifurcation analysis! To that end, Oscill8 provides more than just a glorified interface to AUTO. One can run one parameter and two parameter bifurcation diagrams (via one of the run menus -> "One Parameter" or "Two Parameter") en masse. Oscill8 attempts to provide the user with as much help as possible, including:

• attempt to find steady state to start continuation, which includes the following:
  
  
  1. Newton's method from given initial conditions.
  2. if 1) fails, integration of ODEs until a stable steady state is reached.
  3. if 2) fails, another attempt at Newton's method from different staring conditions.
  4. if 3) fails, opttional parameter tweaks, then return to 1). Otherwise, Oscill8 gives up.


• one-click en masse generation of one/two parameter bifurcation diagrams of ALL (or any subset of) parameters, continuing in both the positive and negative directions up to the user specified boundaries (or some other stop condition is reached).


• [will be available in version 1.3] bifurcation searching capabilities (see searching for details).


• [will be available in version 1.3] bifurcation matching capabilities for one-parameter bifurcation diagrams (see matching for details). This feature is useful to explore parameter space.

Searching for bifurcations

This feature is implemented, but not yet available to the user. It will be available in release 1.3 (see the roadmap for details).

Matching one-parameter bifurcation diagrams

This feature is currently being implemented and will be available in release 1.3 (see the roadmap for details).

Run Configuration Dialog

The run configuration dialog exposes parameters specific to each run type, in addition to numerical parameters used to control the algorithms. There is also a "Set Model Data" button which allows the user to change data associated with the state variables and control parameters, including

• value
• min/max
• activity

The "Settings" pulldown menu includes "Run", "ODE", and "Continuation" and allows the user to access parameters specific to those algorithms. For example, the "Continuation" settings with give the user the following window:

Here, we can control AUTO with all the usual constants. (There are a few parameters which are not exposed which control the problem type, etc--in the future, these may be exposed for raw AUTO runs if necessary). There are tooltips for each of the constants so that the user can understand what each means when it's not obvious.

Utilities

• ode_clean.pl

  This utility helps to migrate from XPPAUT ODE files to the simplified version used by Oscill8.

• jd2ode.pl

  This utility will soon be deprecated, and isn't likely to be in many future releases. Its purpose is to take the cut-and-pasted outputs of JDesigner (namely, the generated ODEs and the initial values from the Jarnac script) and create a valid ODE file suitable for Oscill8. This utility is now being replaced by the stand-alone JigCell SBML to ODE converter. helps to migrate from XPPAUT ODE files to the simplified version used by Oscill8.