A new CellML-based piece of work

In this section we are going to create a new workspace into which we will add a CellML model, annotate the model using OpenCOR, and simulate the model to check that it produces the expected results. We will be using the seminal Noble (1962) cardiac cellular electrophysiology model as the demonstration model for this part of the tutorial.

Create a new workspace

You can find instructions for creating a new workspace on the teaching instance repository in the PMR workspaces documentation. Following those instructions, create a workspace similar to that shown below:

Creating a new workspace to begin a scientific study based on the Noble 1962 cardiac cellular electrophysiology model.

Once you have created the workspace, you will be taken to the workspace listing page. Take particular note of the URI for mercurial clone/pull/push, as highlighted by the arrow below.

A view of the newly created and empty workspace. The URI to be used for Mercurial actions is highlighted by the arrow. Note: the workspace URI is unique to every workspace, so yours will be different to the one shown above.

In order to make changes to your workspace, you have to clone it to your own computer. In order to do this, copy the URI for mercurial clone/pull/push as shown above. In Windows explorer, find the folder where you want to create the clone of the workspace. Then right click to bring up the context menu, and select TortoiseHG ‣ Clone as shown below:

Paste the copied URL into the Source: area and then click the Clone button. This will create a folder named after the workspace identifier (a hexadecimal number) that will be empty. The folder will be created inside the folder in which you instigated the clone command.

Command line equivalent

hg clone [URI]

The repository will be cloned within the current directory of your command line window.

You will need to enter your username and password to clone the workspace, as the workspace will be set to private when it is created.

Populate with content

We have prepared a copy of the Noble (1962) model encoded in CellML ready for your use. You can download the model n62.cellml and save it into your cloned workspace folder created above. To verify that the model works, you can load it into the OpenCOR single cell view and simulate the model for 5000 ms. You can plot the variable V in the membrane component and you should see results as shown below:

The arrows highlight the Ending point which should be set to 5000 ms and the variable V to be plotted.

As long as your results look similar to the above, everything is working as expected. Now is a good time to add the CellML model to the workspace record. The first step is to choose the TortoiseHG ‣ Add Files... option from the context menu for your workspace folder (1).

This will bring up the hg add dialog box, showing the files which can be added (in this case only the n62.cellml file is available and it is selected by default). Clicking the Add button (2) will inform Mercurial that you want to add the selected file to the workspace.

In Windows Explorer, you will see the file icon for the n62.cellml model now overlaid with the Mercurial + icon (3) to indicate that you have added the file but not yet committed it to the workspace.

You can now commit the added file to the workspace by choosing Hg Commit... from the context menu in your workspace folder (4).

This will bring up the commit dialog, which lets you explore and select all the possible changes in this workspace that you can commit. In this case, there is just the addition of the n62.cellml file to be committed. Before committing, a useful log message should be entered - this will help you keep track of the changes you make to the workspace and possibly the reasons for why a given set of changes were made (for example, due to feedback from reviewers). After entering the log message, click the Commit button to commit the changes (5). The dialog will stay visible in case you have further changes to commit, but in this case you can just close the dialog.

Once you have successfully committed the change, you will see that the icon for the n62.cellml file has now changed to a green tick (6) to indicate that the file is up-to-date with no modifications.

Command line equivalent

hg add n62.cellml
hg commit -m "Adding an initial copy of the Noble (1962) cardiac cellular electrophysiology model to the workspace."

While we have the model open in OpenCOR, we should have a go at annotating some of the variables in the model. Full instructions for this can be found in the OpenCOR CellML annotation view. First, we will follow the example given in those instructions for annotating the sodium_channel component.

The first step is to switch to the Editing mode (1) and select the sodium_channel component for annotation (2). We will be using the bio:isVersionOf as the qualifier for this annotation (3) and searching for terms related to sodium (4).

We can then add desireable terms from the search results by choosing the + button beside the term to add to the annotations for the sodium_channel component (5).

Have a play annotating other variables and components in the model. When done annotating, make sure to save the model (File ‣ Save). With the CellML model updated, now is a good time to commit the changes to the workspace.

As above, choose Hg Commit... from the context menu in your workspace folder to bring up the Mercurial commit dialog. This time you will see that there is one file modified that can be committed, n62.cellml (1). As we mentioned previously, it is important to enter a good log message to keep a record of the changes you make (2), and the changes made to the currently selected file are shown to help remind you as to your changes (3). In this case, OpenCOR has made many changes to the whitespace in the file, as well as adding the RDF annotations at the bottom of the file.

Command line equivalent

hg diff
hg commit -m "Using OpenCOR to add some annotations to my copy of the Noble 1962 model."

Push back to the repository

Having added content and performed some modifications, it is time to push the changes back to the model repository, achieved in TortoiseHG with the synchronization action. First, select TortoiseHG ‣ Synchronize from the context menu for your workspace folder.

This will bring up the TortoiseHG Sync dialog. In this dialog, you will see that by default you will be synchronizing with the workspace on the teaching repository from which you originally created this clone. This is usually what you want to do, but it is possible to synchronize with other Mercurial repositories. In this case, we want to push the changes we have made to the model repository, so choose the corresponding action from the toolbar (highlighted below).

Once you choose the push action, you will be asked to confirm that you want to push to your remote repository and then asked for your username and password (these are the credentials you created when registering for an account in the model repository). You will then see a listing of the transaction as your changes are pushed to the repository and a message stating the push has completed.

Command line equivalent

hg push

If you now return to browsing your workspace in your web browser, and refresh the page, you will see that your workspace now has some content - n62.cellml - and if you view the workspace history you will see the log messages that you entered when committing your changes above.

Now might be a good time to think about sharing your workspace with your neighbors. You might also want to have a look at creating an exposure for your workspace. To learn how to create exposures, please refer to Creating CellML exposures.