OpenCell Basic Tutorial

About this tutorial

This tutorial is designed to provide a 'quick start' into OpenCell by guiding the user through a series of exercises that explain how to use the major features of the tool to work with CellML models. In this tutorial document, 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. Screenshots may be from the Linux, Windows™ or Mac OS X™ version of the software. Where the words open the context menu appear, this means right-clicking to open the menu on Windows™ and Linux, or control-clicking (or right-clicking where supported) on Mac OS X™.

Opening a repository model in OpenCell

Go to http://www.cellml.org/models/ in your browser. You will see a long list of CellML models. Many, but not all, of these models will work in OpenCell. Model curation is an ongoing process and the aim of the curators of the CellML Model Repository is to get all these models to run not just in OpenCell, but all tools based on the CellML API. For this tutorial we will use the Beeler-Reuter 1977 model. Click on this model and at the top of the page under 'Download Options' click on OpenCell. Click on 'Browse', and choose the OpenCell executable (opencell or opencell.exe in the directory where you chose to install OpenCell).

When OpenCell is installed, it is set up to be the default handler of .cellml files. Clicking on a model to download from the repository should bring up the option to open the model with OpenCell.

Once you have selected the OpenCell executable, click OK in the Open with dialog box. OpenCell should open with the Beeler-Reuter 1977 example model loaded in it.

Viewing the CellML model structure

At the top of the top-centre pane of OpenCell there are four small buttons. You can change the view displayed in the central tree view pane by clicking on these buttons.

• Clicking on the leftmost button, represented by a blue circle with a small 'v' next to it, activates the show initial conditions/constants view. This view shows all constants and initial conditions defined in the model.
• Clicking on the second button, represented by a cartoon cell between two angle brackets, activates the complete model structure tree view. This view shows all the elements that make up the selected model, in an explorable tree structure.
• Clicking on the third button, represented by the letters XML vertically between two angle brackets, activates the edit XML view. This view shows the plain text code of the selected model, and allows direct editing of this code. The code is syntax highlighted; however this highlighting does not currently update as changes are made. This will be implemented in a future version of OpenCell.
• Clicking on the last button, represented by a set of basic mathematical operators, activates the show equations view. This view shows a list of all of the mathematical equations within the selected model.

Try clicking on these different icons to activate the different views - explore the different views and what they show you.

When using the XML editor, you must be careful not to alter the CellML code to produce malformed XML. In the case that this happens, OpenCell will present you a warning when you switch to another model viewing mode (first or second buttons). If you then change anything in the graphical mode and switch back to the XML editing mode, you will be given the option to keep the changes made in the XML editor or the changes made in the graphical editor.

One point to note here is that when you select a variable or unit element in either the model structure tree view or variable tree view, the attributes of that unit will be displayed in the bottom middle pane, in place of the integrator panel. To display the integrator panel again, click on the display integration panel button ().

Components and variables

The second button on the tree view toolbar () will bring up a 'tree' representation of the entire CellML model. We are going to add in a very rudimentary component representing a leak in the membrane. Open the context menu on the first line of the tree, titled Components, and choose New. A new component called New_component appears at the bottom of the list. Click on it, and change the value in the text box from New_component to leak_current. Click on the '+' sign next to leak_current, and you will see it is empty. Now open the context menu on leak_current, and choose New Variable. Click on New_variable and change its name to i_leak to 1E-3. Click on the '+' next to i_leak, and now click on Public Interface. Change the drop-down value from None to Out. This means that other components can connect to i_leak. Also, click on the Units field on the right and choose uA_per_mm2 from the drop-down menu.

Mathematical equations

Now, we are going to alter the mathematics for the membrane voltage to account for the new leak current. Click on the '+' next to membrane (third row of the tree). Open the context menu on membrane, and choose New Variable. Again, rename New_variable to i_leak. Click on the '+' next to i_leak, and change Public Interface to In (not out this time!), and Units to uA_per_mm2 again.

Now, we will update the mathematics to include i_leak. Click on the '+' next to Mathematics, and then on Equation. The bottom middle pane of the screen will change to a mathematical editor. The intention here is that you will see a display of mathematics and an editable text form of the MathML in a model.

The equation you are editing currently reads as follows:

d(V)/d(time) ={id="membrane_voltage_diff_eq"} (Istim - (i_Na + i_s + i_x1 + i_K1)) / C

Edit the equation by adding the + i_leak term to the equation as shown below:

d(V)/d(time) ={id="membrane_voltage_diff_eq"} (Istim - (i_Na + i_s + i_x1 + i_K1 + i_leak)) / C

Connections

We will now add a connection between i_leak in membrane and i_leak in leak_current.

There are two ways to create connections in OpenCell. The easiest is to the drag and drop method. Simply hold down the CTRL key and drag one of the components which contain the variables you wish to connect to the other component. In this example you should hold down the CTRL key, drag the membrane component and drop it on the leak_current component. You should see a new connection appear in the tree view which connects i_leak in the membrane component to the i_leak in the leak_current component.

Alternatively, click on the '-' next to components to hide them. Now open the context menu on Connections and choose New. Click on the '+' next to the connection at the bottom of the list. Now click on Component_1. From the drop-down menu choose membrane. Repeat the process for Component_2, this time choosing leak_current. Now open the context menu on the connection, and choose New Variable Mapping. When the variable mapping comes up, choose i_leak from the dropdown for both Variable_1 and Variable_2.

Connections ensure that variables have appropriate values set for the components in which they appear. All variables must have a value either set as an initial condition, or acquired via a connection.

Plotting data

To integrate the modified model, click on the large Integrate button at the bottom of the middle pane. Next, create a new trace by opening the context menu on the key of the graph and choosing New Trace. Set up a new Voltage vs Time graph as before, and you will get something which resembles the following output:

Saving a model

Finally, to save our modified model, go to the File menu and select Save As. Save the model to somewhere on your local file system (we will be submitting it to an online model repository later).

Changing the duration of the simulation

To change the default simulation duration of 10000 ms to 5000 ms (5 seconds), in the middle bottom pane in OpenCell, change the text field next to End time point from 10000 to 5000. Now, click the Integrate button at the bottom of the same pane. The button will briefly change to Cancel Integration (the button will persist in this cancel state until the integration is completed), and then on to Export CSV.

Running model simulations

Now we are going to plot some graphs. Open the context menu in the white area at the bottom right corner of the screen and select 'New Trace' from the popup menu. Now, left click on the (click to select) text under the heading Y and choose Membrane, and then V, from the menu that pops up. Now, repeat for the X column, but choose Environment, and then Time. The graph will now appear. Note that the colour of the trace is picked randomly, but you can change it by left-clicking on the coloured square at the start of the Link selected row.

Labelling graphs

To change the title of the graph, simply select Untitled in the white area above the graph and type in Voltage vs time.

Comparing two or more plots

To compare this voltage vs time plot with a current vs time plot first 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. Now change the name of the bottom graph to Current vs time. Since these traces will have different y-axis scales, it may be useful to use the percentage normalisation function. Between the graph title bar and the key icon is an icon that looks like graph axes. Clicking this icon will bring up a menu that will allow you to choose between linear and percentage for each axis. Select percentage for the y-axis to see what this looks like.

Next, click on the picture of the key, which is to the right of the box where you just typed in Current vs time, and the key for the current vs time graph will appear. Using the same method you used previously to create a voltage against time trace on the first graph, create a current against time trace (New Trace, choose i_x1 in time_dependent_outward_current on the Y axis, and time in environment on the X axis). Now, create another new trace, this time with i_s in slow_inward_current on the Y axis, and time on the X axis. If the colours are too similar (or poor contrast on black), you can change the colour by clicking on the coloured square next to the link selected label.

Zooming in on a plot

Now, suppose that we want to zoom in on a particular section of data, but we still want to be able to compare the two graphs. To do this, go to the View menu, and select Tie X Axis. Also check Grid lines on the same View menu, because this will help to compare data. To make the graphs bigger, drag the line separating the right pane from the middle pane to the left, until the middle pane disappears completely. Then remove the model trace key from the bottom pane by clicking on the key button again (the same button you used to turn it on). Next, on the Voltage vs time graph, hold down the shift key and use the left mouse button to drag a box around an action potential. Both graphs change such that you will now be able to see the shape of the action potential for both the currents and the voltage.

Next, we are going to make a change to the model, and see what effect this has on the results. To restore the screen to the original layout, turn off the Tie X Axis values through the View menu, by repeating the process you used to turn it on, and click on the One graph button (which is one left of the Two graph button you used before).

On the model trace key below the graph left click on the link selected text and choose Copy selected model. This binds the trace to the current model, so that when we change the model, the current graph will stay as a reference.

Finally, drag the separator that you previously dragged left, back to the right, so you can see the middle pane again.

Cloning a model

Next, we are going to clone the model. Cloning models allows changes to be made to the model, but the original version and the results are retained. To clone a model, open the context menu 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 re-name this new model right-click on the model name and choose Rename. In the Rename to what dialog box, type in Modified.

Comparing the output of multiple models in the same graph

It is possible to compare the output of two different models on the same graph. To try this, make a clone of the Beeler Reuter model as described above. We're going to change the value of a variable in the cloned model called IstimPeriod from 1000ms to 500ms. This variable should appear in the variable tree listing, or if you are viewing the model structure tree, this variable can be found under the stimulus_protocol component. Click in the box displaying the variable's value and replace 1000 with 500. This will cause the model cell to fire an action potential every 500ms instead of every 1000ms. The attributes of the variable should be displayed in the bottom middle pane. To get back the integrator panel, select the model structure tree view and click on a component, group or connection element.

Now we want to compare the outputs of the original and modified models in a graph. Create two new traces and select time under the environment component for the X-axis, and V under the membrane component for the Y-axis. Do this for both traces. Make the colour of one trace red and the other blue. Now integrate both models by selecting them in turn in the model selector and clicking the integrate button. Now select the original model in the model selector, and look at the trace selector under the graph. You should see the text 'Link Selected' for both traces. Click this text on the top trace and choose Copy selected model. Now choose the modified model in the model selector, and select Copy selected model for the bottom trace.

The graph should now display action potentials every 500ms, every second action potential being purple - this results from the combination of red and blue traces every 1000ms.

Cloning from output

This time we are going to clone the original model and change the IstimPeriod of the cloned model to 500ms, but we are going to append the output of the modified model to that of the first. To do this we need to use the Clone from output function. To start off, integrate the Beeler Reuter model for the 5000ms that appears as default in the Start time point field of the integrator panel. Now open the context menu the model in the model selector to bring up a menu and select Clone from output. A dialog box will appear asking you what time point you want to clone from. It will suggest 5000ms, which is fine - press OK. OpenCell will try to find a point as close as 5000 as it can, but if it can't find 5000 it will inform you and suggest a number like 4999.776680691712 - this is fine, click OK.

Now change IstimPeriod in the cloned model to 500ms. We want to integrate this model between 5001 and 10000 milliseconds, so enter these values in the fields for Start time point and End time point in the integrator panel, repsectively, and hit integrate. Then create two graph V vs time graph traces perform the steps described in the above section to plot the output from both integrations on the same graph. You should see a graph showing one action potential per second for the first 5 seconds, and then two per second for another 5 seconds.

Tabulation control: output at fixed intervals

New in PCEnv (the predecessor to OpenCell) 0.5 is the addition of tabulation control. This allows you to restrict the output of your integration to fixed intervals. We are going to create two plots of the coupled pendulum model, one with the output at the default settings, and one with output at fixed intervals of two seconds.

First, load up the coupled pendulum model from the tutorial directory. In the Basic settings tab of the integrator panel, change the End time point to 50 seconds. This will make the results of this exercise a bit clearer. Now at the top of the integrator control panel, click on the Advanced settings tab to show the tabulation control settings. Click on the Enable tabulation control check box, and then enter a value of 2 (seconds) in the text box. Also click on the Tabulate strictly check box. Turning strict tabulation on forces OpenCell to only output values at strict values of the tabulation interval.

Now click on integrate. Create a new trace in the graph pane, and select Environment, time for the x axis and PendulumUpperSegment, a for the y axis. For the trace type, select Circles. You should see a trace with circles scattered up and down across the x and y axes. These are values of the integration at strict 2 second intervals.

In order to see that these are values of the normal untabulated integration, we will add another trace to the graph. First, click on the Model column of the trace you created previously (where it says Link Selected), and change the value from Link selected model to Copy selected model. Now open the context menu on the model name, and clone the model in the model selector panel. Select the new clone of the model, and disable tabulation control in the advanced settings. Now integrate the cloned model. Create a new trace in the graph with the same x and y axis settings as for the previous trace. Now change the Type for this trace to Lines. You should now see another continuous line trace, which all of the circles from the previous tabulated output trace lie on, as seen below.

Using OpenCell sessions: recreating model figures

The next part of the tutorial will use OpenCell to open a session file. Some CellML models in the repository have session files associated with them; for example the Beeler Reuter 1977 model here.

Go to this page in your web-browser and click on the "OpenCell session" - open the file with OpenCell. You will now have the Beeler-Reuter model loaded from the repository and laid out in OpenCell. Click the Integrate button and you will immediately see some graphs which resemble those in the published paper, as well as a topology figure describing the model.

To look at the diagram more closely click on the One graph button and from the drop-down menu at the top of the graph where it says Voltage vs time, choose Topology figure. Drag the pane splitter bars to the left so the figure takes up the entire screen. You can now see, in good detail, a scalable figure from the session. This could also be used to visualise a CellML model as a pathway diagram.

You can also try this with the Bondarenko, Szigeti, Bett, Kim, Rasmusson, 2004 session to see an example of a session with an embedded pathway diagram. This diagram is interactive: clicking on the species in the diagram will bring up the flux trace associated with that species.

Submitting a model to the CellML Model Repository

The CellML model repository is at http://www.cellml.org/models. As of the time of release of OpenCell 0.5, there were about 350 individual models based on peer reviewed publications in the repository.

If you would like to practice submitting a model to the repository, you can use the test repository at http://www.cellml.org/Members/miller/models . Type this address in your browser. Click on Submit a new model to the model repository. You will have to log in. You can use the username Tutorial and the password tutorial. Please note that this log-in is case sensitive. Now follow the one screen instructions to submit your model.

If you want to upload real models to the real repository (not your test model!) you can contact Tommy Yu at tommy.yu@auckland.ac.nz, and he will issue you with a username which can be used to upload your models to http://www.cellml.org/models/