). This tutorial is designed to provide a 'quick start' into PCEnv 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.
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 PCEnv. 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 PCEnv, 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 PCEnv. Click on 'Browse', and choose the PCEnv
executable (pcenv or pcenv.exe in the directory
where you chose to install PCEnv).
When PCEnv 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 PCEnv.
Once you have selected the PCEnv executable, click OK in the Open with dialog box. PCEnv should open with the Beeler-Reuter 1977 example model loaded in it.
At the top of the top-centre pane of PCEnv there are four small buttons. You can change the view displayed in the central tree view pane by clicking on these buttons.
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, PCEnv 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 ().
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. Right click 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 right click 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.
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). Right click 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 (however, due to a bug in our underlying
architecture, a wrong font gets selected so the math display is not useful
right now).
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
Now, click on the '-' next to components to hide them. We will now add a
connection between i_leak in membrane and
i_leak in leak_current. To do this, right click 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, but
for Component_2, choose leak_current. Now right
click 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.
To integrate the modified model, click on the large Integrate button at the bottom of the middle pane. Next, create a new trace by right clicking 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:
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).
To change the default simulation duration of 10000 ms to 5000 ms (5 seconds), in the middle bottom pane in PCEnv, 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.
Now we are going to plot some graphs. Right click 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.
To change the title of the graph, simply select Untitled in
the white area above the graph and type in Voltage vs time.
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.
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.
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, 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 re-name this new
model right-click on the model name and choose Rename. In the
Rename to what dialog box, type in Modified.
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.
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 right click 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. PCEnv 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.
New in PCenv 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
PCEnv 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 right click on 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.
The next part of the tutorial will use PCEnv 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 "PCEnv session" - open the file with PCEnv. You will now have the Beeler-Reuter model loaded from the repository and laid out in PCEnv. 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 Huang-Ferrel 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.
The CellML model repository is at http://www.cellml.org/models. As of the time of release of PCEnv 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/