Physiome CellML Environment (PCEnv) User Manual

1. About this manual

This file describes how to use PCEnv to edit CellML models and run simulations using them. The majority of the information contained in this manual is specific to PCEnv; for more information on CellML, please see the CellML Website at http://www.cellml.org/. For suggestions on best practices for creating CellML models, please see the best practice guide on the CellML website at http://www.cellml.org/tutorial/best_practice.

In this manual, words that appear in menus, on the GUI, or on buttons are written in italics. Words or characters that are part of editable fields such as text boxes, or are to be entered by the user, are written in monospace font. PCEnv is cross-platform software; screenshots in this document may be from the Linux, Windows™ or Mac OS X™ version.

2. What is PCEnv?

The Physiome CellML Environment (PCEnv) is a Free / Open Source environment for working with CellML. The project was started at the Auckland Bioengineering Institute (part of the University of Auckland), and since then, the team has grown to include developers from around the world. It provides a unified way to work with CellML documents, including creating new models, editing existing models, and running simulations.

3. What's new in PCEnv 0.5

New features in 0.5 are:

• Improved connection view in the tree view - the names of the connected components are now displayed in the list.
• New connection details view in the interaction pane - shows details of connected components for the selected connection, including connection directions.
• New math view in the tree view; this provides quick access to all the equations in the selected model.
• New preferences service - to access the preferences, click on the menu. At present this provides the ability to toggle warnings on or off when opening RDF files.
• New "tabulation" option for output at fixed intervals when integrating.
• New validation service: this displays a list of errors in the CellML. Errors are highlighted, and can be quickly navigated to by clicking on the error messages.
• Tabbed integration panel - this now separates out basic and advanced settings for integration. The new tabulation settings are found on the advanced settings tab.

4. The PCEnv interface

The interface of PCEnv is divided into 5 main areas:

• Menus and toolbar: At the top of the window are the usual menus and a toolbar containing icons to perform a selection of functions.
  • New model: creates a new model.
  • Open model file: allows the user to open a model file via a file dialogue window.
  • Save selected model: saves the selected model.
  • Save selected model as: allows the user to save the model under a new name, via a file dialogue window.
  • One graph view: shows one graph in the graph pane.
  • Two graph view: shows two graphs in the graph pane.
  • Three graph view: shows three graphs in the graph pane.
  • Open integration pane: displays the integrator pane in the interaction pane.
• The model selector: At the far left of the window is the model selector, which contains a tree view of the currently open models.
• Tree view: At the top centre is a pane which shows the structure of the currently selected model. This pane has four view modes.
• Interaction pane: This pane at bottom centre contains the integrator pane, as well as being where information about selected items from the tree view is displayed. For example, selecting an equation in the tree view will display it in mathematical notation here.
• Graph pane: This pane is used to set up and display graphs. It can also display SVG diagrams.

5. Viewing models in PCEnv

5.1 Opening a model

You can open an existing CellML model from a file by using either the file menu or the open button on the toolbar. Using the menu, first go to the file menu and select open. A dialogue window will pop up; select the file you wish to open and click open. Clicking on the open button on the toolbar will pop up the same dialogue window.

When PCEnv is installed, it will also become the default file handler for .cellml files. Clicking on links to CellML models on the web (for example from the model repository at http://www.cellml.org/models) or opening CellML files from the operating system will therefore load them into PCEnv.

5.2 The tree view pane: view modes

At the top of the model tree view pane of PCEnv, there are four small buttons:

These allow you to select one of the four following display modes for the tree view pane:

• Show initial conditions/constants view: This presents a view of all the constants and initial conditions defined in the model.
• Show complete model structure view: This shows a tree view of the entire CellML model. From this view you can explore and edit components, groups, connections and units, equations and variables. This is the primary editing view of PCEnv.
• Edit XML view: This enables a syntax-highlighted text view of the XML of the model. You can edit the code directly from this view.
• Show equations view: Selecting this view will display all of the equations in the model.

When either a variable or unit element is selected in the model structure tree, information about the attributes of that variable will appear below the model structure pane in the interaction pane. If a variable is selected, this information includes the variable's name, units, initial value (if applicable), and interface values. If a unit element is selected, the information displayed is an equation-like representation of the derivation of that unit from base units. To show the integrator in the interaction pane, either switch to another view, or click the display integration pane () button.

Currently, the XML view within PCEnv does not perform dynamic syntax highlighting (highlighting which updates as you edit the code). It is planned to implement dynamic highlighting in future versions; for the time being, simply change to another view and back to the XML view to refresh the syntax highlighting.

6. Editing models in PCEnv

6.1 Creating a new model

To create a new model in PCEnv, either open the File menu and select New, or click on the new button on the toolbar (). A window will appear prompting you to enter a name for your model, and to choose the version of CellML you wish to use. Unless you have a compelling reason not to, use CellML 1.1 to create your new model. Once created, your new model will appear in the model selector pane.

6.2 Editing a model

The primary view for editing models in PCEnv is the Show complete model structure view. This view is selected using the second button at the top of the tree view pane ()

6.2.1 Adding new components and variables

To add a new component to a model right click on the first line of the tree, titled Components, and choose New. A new component called New_component will appear at the bottom of the list. The name of this component can be changed by clicking on it and by changing the value in the text box.

To add a new variable to a component right click on the component name and choose New Variable. Next, click on the '+' sign next to the component name to expand the component. Click on New_variable to change its name.

6.2.2 Adding mathematical equations

To add a mathematical equation to a component, right click on the component name and choose New Maths. Right click on Mathematics and choose New Equation. Expand Mathematics, and then Equation. The bottom middle pane of the screen will change to a mathematical editor, with a graphical display of the mathematics rendered below it.

6.2.3 Creating connections

When two or more components share a particular variable it is necessary to connect those components. To create a connection between two components first, right click on Connections and choose New. Click on the '+' next to the connection at the bottom of the list, and add the components to be connected by clicking on Component 1 and choosing the appropriate component from the drop-down menu. Repeat the process for Component 2, then right click on the connection and choose New Variable Mapping. In a similar way, choose the appropriate variable(s) to be connected from the drop-down menu.

PCEnv 0.5 adds a new connections view; each connection in the list now displays the components it connects as its name, instead of simply "connection". When you select a connection, details of the connected components, including the directions of these connections, is displayed in the bottom panel.

6.2.4 New units

CellML provides a dictionary of standard units that may be used in variable declarations or attached to bare numbers in mathematics. These include the SI base units and some additional units commonly used in the types of biological models likely to be defined using CellML (for a list of these units please refer to the CellML 1.1 specification). When units are required which are not included in this list, it is possible to describe them by adding a new units definition, which is based on units in the SI dictionary listed in the CellML dictionary, perhaps with a prefix (e.g. milli) or a multiplier attached.

A new unit can be added to a model in PCEnv by right clicking on Units in the model tree and choosing New. This new unit can be defined as either being base or derived by clicking on the drop-down menu next to the unit name. PCEnv allows components and models that declare variables with different units to be connected as long as variables that are mapped to one another have the same dimensions: for example feet and metre, or pound and kilogram.

6.2.5 Imports

CellML 1.1 allows for you to import other models. To add a new import, right click on Imports, and choose New. Click on the new import row. Now type a URL for the model in the box under the Type column.

You will now be able to add in Import Components (components to import) and Import Units (units to import). To add a new import component, expand the imported model, and then choose New. You will now have a new Import Component appear. The text-box under the type column (initially New_import_component) describes the name in the importing model, and the text-box under the value column describes the name in the imported model. An exactly analogous rule applies for the import units.

You can also expand Model to view the imported model. Changing the imported model here not recommended, as there is no way to save your changes. Instead load the imported model separately in PCEnv.

6.3 Cloning a model

Cloning models allows changes to be made to a model whilst retaining the original version of a model and its results. To clone a model, right click on the model name in the left hand pane and select Clone. A new model appears in the tree, underneath the original model. Initially it is named by the date it was created. To rename this new model right-click on the model name and choose Rename.

6.3.1 Cloning from output

Clone from output lets you create a clone of a model in which the state variables have an initial value equal to those that result after a period of time. If, for example, the value of variable y is 0 at time 0 and 100 at time 10, then if the model is cloned at time 10, the initial value of y will be 100 in the clone.

There are several reasons why you might want to do this:

• You want to 'intervene' in a simulation by changing a value after the simulation has started and watching the effects. This is equivalent to cloning from output at the point you want to intervene, changing the value, and starting the simulation from there.
• You want to run a model for a long time in the hope it will reach a steady state, and then save a model with the state variables already at their steady state values.

To Clone from Output:

• Follow the instructions in 'Running a Model Simulation' to run your simulation up to the point you wish to clone from. You can go past the point if you want, but then there may not be a data point exactly where you want to clone from output.
• Right click on the model in the model selector to bring up the context menu.
• Choose 'Clone from Output' on the context menu.
• A popup appears asking you for the point to clone at. It defaults to the end point. Press Ok to perform the clone.
• You can now change any parameters you wish to on the cloned model.
• If you are performing an intervention, you may wish to change the 'Start Time Point' for the cloned model to the time of the intervention — otherwise the time start again at the original starting time (while keeping the updated state variables).

Below is an example of what cloning from output is able to achieve.

6.4 Validating a model

PCEnv 0.5 now provides a validation service that makes it easier to find and correct errors in your XML. To start the validation service, select the model in the model selector. Right click on the model and select the Validate option. The validation service will find any errors and display them in the right hand panel. Double clicking on an error message will automatically display and select the cause of the error. PCEnv will only be able to highlight the error if you are in show complete model structure view mode.

Remember to select the complete model structure tree view before using the validation service.

Currently the validation service only takes you to errors in the model structure and equations views. In future versions it will also be able to also highlight errors in the XML editing view.

7. Running models

7.1 Running model simulations

In order to run a simulation, first make the integrator controls visible in the interaction pane area - do this by clicking on the display integration pane button () in the toolbar. The integrator pane lets you set the initial conditions for a number of different parameters before starting the simulation. It is split into two tabs; Basic settings and Advanced settings.

7.1.1 Basic settings:

The following choices are available for algorithm:

7.1.2 Advanced settings:

Once you are ready to run the simulation, click the Integrate button. This will run the model.

In PCEnv, there is a 1:1 relationship between integration runs and models in the model tree view. Therefore, you select previous integration runs in exactly the same way that you select models. If you want to have more than one run for the same input model, you can clone the model in the model selector. You will be prompted to do this automatically if you try to change a model after you have run it.

7.2 Viewing graphs

The graph viewer lets you plot the data from your model simulations onto a graph. This also allows you to compare graphs from two or more simulations. You can plot variables on the X and Y axes, and have an arbitrary number of traces.

To add a new trace, right click in the white area at the bottom right corner of the screen and select New Trace from the popup menu. You are now able to define the different attributes of the trace by left-clicking on the appropriate column in the list, as described in the table below:

You can disable, re-enable or delete traces by right clicking on the trace, and choosing the respective options from the popup menus.

7.2.1 Labelling graphs

To change the title of the graph, simply select Untitled in the white area above the graph and type in the new name of the plot.

7.2.2 Comparing two or more plots

To compare two plots simultaneously click on the Two graphs button which is on the toolbar beneath the main menu and is the second icon from the right. Clicking on this icon provides a two graph view. Likewise, clicking on the Three graphs button will provide a three graph view.

7.2.3 Gridlines

You can add gridlines to the graph display by selecting gridlines within the View menu.

7.2.4 Axis scaling: percentage normalisation

Both axes can be designated as either linear or percentage-normalised. Using percentage- normalisation function will cause the values along that axis to be plotted as a percentage of their maximum value. This function tends to be more useful for the Y-axis and can be very helpful for comparing traces with different scale ranges. For example the shape of a trace within the millimolar range can be compared with that of a trace within the picomolar range. Using the linear axis view, the picomolar range trace would appear as a flat line running along the bottom of the graph.

7.2.5 Zooming in and out

To zoom in on a feature of the data, click the left mouse button, drag a box over the feature, and release the mouse button. The selected box will be your new coordinate space.

You can zoom in and out on a graph by holding down the right mouse button and moving the mouse; in this case, you have independent control over the zoom in the X and Y directions by moving the mouse side to side or up and down.

To zoom out by 150%, right click on a zoomed in graph, and select Zoom out. To return to the original view showing all data, right click on a zoomed in graph and select Zoom full.

When you plot a graph with a large number of points, you might not always see every feature in the data from low zoom levels. The reason for this is because PCEnv will summarise data as you zoom out to make the program more responsive, and also because you have a limited number of pixels on the screen. Try zooming in on features for a clearer view.

7.3 Re-arranging the environment

PCEnv's user interface contains many different components; sometimes you may want one part of the environment to take up more or less screen space than the default. You can do this by putting the mouse over the bar that separates components of the user interface, holding down the left mouse button, and dragging the component into the part of the screen where you want it. If you try to resize a component to below the minimum size, it will fold down to zero size until you drag it back out.

To see features of your data better, try expanding your graph area to take up the whole screen.

Although only one graph panel is visible when you initially start PCEnv, there are actually two more hidden at the bottom right of the screen. This is useful if you want to compare two different graphs on separate, but lined up, axes.

8. Sessions

A session file stores the state of PCEnv, including the list of models which are open, any graphs which you may have defined, the positioning of the various sliders, and so on. Session files can also store a link to a diagram or other external content. The diagram may be set up so that clicking on components of the model in the diagram toggle specific graph traces on and off in the displayed graphs. Session files are usually used for display and dissemination purposes; models may be set up to be integrated with specific time intervals, with specific graph traces and diagrams showing. An increasing number of the models in the Physiome Model Repository have session files available for download.

For an example of what session files can do, download the session file from this model. Load the session file into PCEnv by opening it as you would a model file. Once the session file is loaded, PCEnv will be arranged quite differently to the default layout, as shown below:

Clicking on the channels in the diagram will cause traces associated with them to be toggled on and off in the graph above the diagram.

8.1 The default session

The default session is a special session file which is stored in your PCEnv profile directory. It provides a convenient way to save what you are doing and come back to it later.

To save the default session, choose File => Save Default Session.

To restore you default session saved earlier, choose File => Load Default Session.

A session does not actually contain the models, it only contains links to them. It is therefore important that you save your models as well as your session. Also, because sessions need cmeta IDs on variables to properly save your mathematics (it adds them automatically when saving your session) it is important to save the models after you save your session.

8.2 Exporting and importing sessions

Sometimes, you may want to export a session to give to someone else, or to keep for a long period of time. You can create such a session by choosing File => Export Session and choosing the file to save to.

You can also import a session provided by someone else by choosing File => Import Session and choosing the file to load.

Sessions will normally refer to models by a file URL. You can edit the session file after exporting if you know of a more generally valid URL for the model, and replace the URLs.

Don't forget to share your models together with your session, because session files do not contain the model itself, only a link to them.

You can find some pre-configured session files for certain models on the CellML repository. PCEnv will load them for you if you click on them and choose PCEnv as the program to open the file.

8.3 Graph features in sessions

There are two main graphing features that can be applied to sessions. Gridlines can be turned on, and graph axis scaling can be switched to "percentage-normalised." These are described in the viewing graphs section of this manual.

8.4 Embedding diagrams in a session

You can embed an SVG or HTML diagram into a session file. To do this, you must edit the session file in a text editor. First, rename one of the graphs with no traces on it from 'Untitled' to the final name.

Next, use the Export Session command on the file menu. Open the session file in a text editor. Perform a text search for the name of the graph.

After the attribute NS1:graphname="{Graph title}", add NS1:externalurl="{URL of diagram}" . The string NS1 may vary — in any case you should use the same prefix on the externalurl attribute. {Graph title} refers to the title you entered for the graph, and {URL of diagram} is replaced with the URL for the diagram.

When this session is loaded, the diagram will be displayed in the place of the selected graph.

9. Javascript in PCEnv

9.1 Embedding Javascript in PCEnv

PCEnv allows Javascript to be embedded in external files embedded as content in sessions (for example, SVG diagrams added as explained in the section above). Use of scripting inside SVG (or other documents) associated with a CellML model via a session file operates in exactly the same manner as when these documents are embedded in a web page, with the addition of the PCEnv Javascript API.

9.2 The PCEnv Javascript API

PCEnv exposes three methods to Javascript through the pcenv object. They let you show and hide traces, and set status bar messages. These methods can be invoked from the unprivileged Javascript in an embedded diagram. To hide a trace, use the method hideTraces(graph name), where graph name is the name you have selected for the graph. To show a trace, use the method selectTrace(graph name, x variable name, y variable name, colour, style). The x and y variable names must be in the form "component/variable". Colour is either an empty string, in which case the colour of the trace is not changed, or a string of the form "#rrggbb" specifying the new colour of the trace. Style has six allowed values:

• "" - Make no change.
• "lines" - Draw as lines.
• "squares" - Draw as squares.
• "circles" - Draw as circles.
• "diamonds" - Draw as diamonds.
• "dots" - Draw as dots.
• "none" - Don't draw (disable trace).

To write a message to the status bar, use the method status(message). All of these methods are invoked through the pcenv object. To see an example of a session file using this api through an svg object, click here.