mozCellML Help

User help for mozCellML

Installing mozCellML

Before you can install mozCellML, you need to install the Firefox browser. Firefox is a Free/Open Source browser based on the Mozilla architecture. You can download it from http://www.mozilla.com/. You need version Firefox 1.5(although later releases might still work).

In order to install mozCellML, you need to get hold of the latest XPI file (more advanced users might also wish to build mozCellML from source). The XPI(cross-platform installer) file contains prebuilt binaries for everything you need to get mozCellML running(except Firefox). You can download the XPI file at http://www.cellml.org/tools/mozCellML/releases. Start up Firefox, and open the XPI file with it. You will then see a dialog asking if you want to install the package. Click "Agree", and when the install completes, restart Firefox.

Getting Started

Start Firefox using the usual method. When the browser window comes up, you can click on Tools(on the menu bar) => CellML. This will bring up the CellML main window, placing you in the mozCellML environment.

mozCellML 0.3 uses a multiple document interface design. This means that you have one main mozCellML window, and inside of this, there are other sub-windows. Each sub-window can be individually dragged around the screen and resized just like any other window. Windows can also obscure other windows(although this is currently not fully supported for graph windows). Clicking on a window brings it to the front. If you lose a window behind another, you can get it back by right clicking on the title-bar. A menu showing all windows will pop up. Click on the window you want to bring to the front.

You can also tile all windows(that is, lay them out as equally sized tiles) on the screen, in either a vertical or a horizontal direction. To do this, select Window => Tile Vertically (or Tile Horizontally, as the case may be).

mozCellML has two main types of MDI windows. One of each type appears when you first start mozCellML. Load model windows let you load models into mozCellML. You can make a new Load Model window appear by clicking File => Models => Load Model. General windows let you view and manipulate other models. You can open a new general window by selecting Window => New Window.

Loading CellML models

To load a new model, use a Load model window(see above). The location of a model is specified using a uniform resource locator(URL). The URL can use any protocol supported by your Firefox installation. For example, you could use a http:// URL, or an ftp:// URL, or a file:// URL. If you know the URL, type it in the textbox at the top of the CellML Main Interface, and then click the button to the right of the textbox, labelled "Load CellML".

Because you will often want to load a model from your filesystem, you can click on "Browse Local Files". You will now get a dialog box prompting you for the location of the file. You can use this box to navigate your filesystem. When the box first comes up, it will show all files with the extension .cml and .xml. You can change this by clicking on the drop-down box labelled "Files of Type" and choosing another option from the list. After you click okay, the file:// URL for the file you selected will appear in the box. You can now click "Load CellML" to load the file.

The model selector

You can load more than one model into mozCellML at any one time. You can also create new derivative models from loaded models. In order to switch between different loaded models, you can use the model selector. The model selector resides permanently at the left side of the screen, but can be resized by clicking on the right border and dragging.

The model selector offers several ways to view the loaded models, which can be selected using the view drop-down list. In Latest mode, only the most recent versions of each loaded model can be seen. In Changes(tree) mode, changes can be viewed as a forest of trees, with loaded models being the root of the trees, and derivatives of models nested under the parent from which they were derived. In History List mode, each model is listed in the order they were loaded or created by derivation.

When you click on a model in the model selector window, it will become the active model in all open general windows, except for general windows which are already locked on another model.

Using general windows

General windows have a checkbox titled "Lock model on window". Clicking this will prevent selections on the model selector affecting this window.

General windows also have a mode selector. This lets you select what sort of task the general window will perform.

The variables mode

The Variables mode is a mode available in any general window. Most of the window is taken up by a listing of all variables. You can view this listing as a tree, in which case variables are nested under the component, which are in turn nested under the imported model from which they were loaded(or Base if they were loaded from the main model). Alternatively, you can view it as a flat list of all variables. To switch between the two ways to view listings, click on the Draw as tree checkbox at the bottom of the window.

If you find that there too many unwanted variables are making it difficult to work with the variables that you are interested in, you can mark the variables you are interested in as important. To do this, select a variable, and click the Important checkbox. Repeat this for all important variables. Once you have done this, click the Hide Unimportant checkbox. Click the checkbox again when you want to see all variables.

You can modify an initial condition by selecting the variable, and then altering the text-field in the lower right-hand corner of the window. When you alter a model(other than a derivative model which has not yet been integrated) a derivate model is automatically created and selected. The change you made is then applied to the derivative model. Derivative models are named after the time when they were created.

If you want to exchange the derivative model with another person, or load it into a different CellML compliant program, you can save it as a CellML model by clicking the Save As CellML button, and entering a filename when prompted.

The integration parameters mode

The Integration Parameters mode is a mode available in any general window. You can set a parameter by editing the text-box next to it. Changes to integration parameters are treated as if they were changes to the model(and so derivative models are automatically created).

You can set the following parameters:

Parameter Function
Starting bound variable The value of the bound variable(e.g. time) at which the specified initial conditions apply. This will be the first output point from the integrator.
Stopping bound variable The value of the bound variable(e.g. time) at which the integrator should stop integrating.
Grid resolution The spacing(in the units of the bound variable) between points generated by the integrator. Smaller values will result in a larger total number of points.
Relative error control The relative error control threshold. Smaller values will result in more accurate results.
Absolute error control The absolute error control threshold. Smaller values will result in more accurate results.
Maximum step size The maximum step size to be used by the integrator. The integrator uses dynamic step size computation to choose a sensible step size. However, some functions(which are relatively flat but have a sudden peak around a certain range) can cause it to fail. Such functions are common in certain electrophysiological models.

Once you have set the initial conditions and integration parameters to your satisfaction, you can begin to integrate the model. In order to do this, you can click on the Integrate Model button. This will launch the integration process. The button will be replaced by a button to stop the integration. You can use this button the interrupt the integration process. Once the integration has completed, the button will disappear altogether.

The raw integration results mode

The Raw Integration Results mode is a mode available in any general window, provided that the model has already been integrated. If the model has not been integrated, the general window will switch to the Integration Parameters mode.

The raw integration results mode contains a tree view much like the variables mode. The Draw As Tree and Hide Unimportant features from the variables mode are also available in this mode. However, neither the bound variable nor constant variables are visible in this view.

The mode features a box in which you can type bound variable values. The results around this value will then be displayed in the tree view. You can also scroll through the results using the up and down arrows beside the textbox.

You can also save the results as a comma-separated value(CSV) file. This data can then be loaded into another program, such as a statistical program, or a spreadsheet. Click on the Save As CSV button, and you will be prompted for a filename to save to.

The graph editor mode

The graph editor mode lets you define new types of graph, or edit existing ones. These graphs can then be viewed in the integration results graph mode.

Graphs are shared between all models derived from the same loaded graph. Therefore, you can set up a graph once, and then switch between derived models to see the same graph for different parameter sets.

The first thing you will want to do is create a new graph. To do this, click on the New button on the line beginning with Graph:. You will be prompted to enter a name for the graph. Once you have created a graph, you can make changes to it, or you can delete it, by clicking on the Delete button on the same line.

One graph consists of a single pair of axes, with one or more traces on it. Each trace consists of an X-axis variable and a Y-axis variable. Where there is more than one trace in a graph, all of the variable choices for a particular axis must be in the same units. mozCellML will prevent you from choosing incompatible units by removing illegal choices from the list of variables.

To add a new trace to a graph, select the graph on the Graph: line, then select New in the drop-down box on the Trace: line. Next choose an X-axis variable and a Y-axis variable from the boxes, and select a colour. The trace will now be created and added to the drop-down box.

To edit a new trace, select the graph and trace to edit, and then click on a new X-axis or Y-axis variable, or select a new colour.

The graph mode

In graph mode, you can view graphs of the integration results. You need to have created at least one graph before you can do this(otherwise you will be redirected to the graph editor mode). You also need to have integrated the model, or you will be redirected to the integration results graph mode.

You can select a graph to plot from the drop-down box at the top of the mode content, on the same line as the Graph: text.

You can then use the graph area to view the data. You can pan the data by holding down the middle mouse button, and dragging with the mouse. You can zoom in and out by holding down the right mouse button, and dragging with the mouse. Note that the axes do not cross at the origin by default, but are instead fixed at one position in the window.