CellML in practice: modularity & reuse; versioning & provenance; embedded workspaces David Nickerson Auckland Bioengineering Institute University of Auckland New Zealand

2 A useful reference tutorial/tutorials/embc13/index.htmlhttp://abibook.readthedocs.org/en/EMBC tutorial/tutorials/embc13/index.html

3

Modularity & reuse in CellML CellML provides the framework for encoding mathematical models in a very modular manner –separation of mathematical model and a specific instance of the model (parameterization). –unambiguous definition of all physical quantities to allow automated translation between units across connections. Following some best practice guidelines ensures the modules are “easily” reusable by the widest possible audience. Some examples… 4

5

6

7

8

9

10

11

12

13

14

15

16

Versioning and provenance 17

The mechanics When using text-based model encoding formats (SBML, CellML, SED-ML, …) there is no excuse not to use a version control system of some description. PMR2 uses the distributed version control system Mercurial and provides access controls –makes it really trivial to share your work while it is still under progress! Don’t wait until it is perfect before sharing it or putting it into a repository. Be free when creating workspaces –modules should be in their own workspace to enhance reusability 18

The mechanics Exposures provide a permanent URL by which you can unambiguously reference a specific revision of the contents of a workspace. The user is able to configure specific items in the workspace to be processes for web-display or other tasks –e.g., Think of the person trying to reproduce you simulations in 10 years time when you write you commit messages! –or perhaps the scientist reviewing your paper next week? 19

20 Embedded workspaces PMR Workspaces –Independent mercurial repositories. –Detailed provenance record. –Contains many types of data. CellML 1.1 model hierarchies –Modularity and reuse. –Ability to ‘import’ arbitrary CellML components to assemble and create powerful models. –Define common models once and reuse them where necessary (libraries of modules).

The Problem? When importing existing models, what happens when the source model changes? –Imported components may no longer exist. –Parameterizations may no longer match requirements. –… What happens when bugs are fixed in the source model(s)? –Provenance tracking. –Versioning and model differences. And in the other direction, what about when I find bugs in models that I use? 21

A solution – embedded workspaces Mercurial subrepositories –A little concerning: 22

A solution – embedded workspaces Mercurial subrepositories –A little concerning: (but we can help avoid problems with some best practice guidelines?) A little technical but very powerful –Currently requires working directly with mercurial –And knowing what you are doing (mostly) PMR2 web interface presents information, but no other tools making use of this feature at present (I think). Allows relative URLs to be used for all imports, irrespective of the actual location of the source content. Can be nested to any depth, but need to be careful about doing so. 23

In CellML (my-model.xml) 24

On the local file system… My Model/ –HH/ gating-variable.xml … –physical-constants/ mohr_taylor_newell_2008.cellml –my-model.xml –.hgsub, defines: HH  huxley-model physical-constants  newell_

…on the local file system My Model/ –… –.hgsubstate, defines: Use HH changeset 755e83040c8ea71167d2bb50c2593f4f0092fa67 Use physical-constants changeset c506f07a2d935261f0117d8ed7d2667b7dcf7b78 26

The benefits….hgsub and.hgsubstate are normal resources in the “My Model” workspace, so all changes are tracked in the history of the workspace –If the source location for an embedded workspace is changed, you know exactly who, when, and why for the change. –Similarly for the version of the source workspace being used. Requires specific user action to change “My Model” workspace to a different version of the HH model –Protected from potentially incompatible upstream changes. 27

…the benefits Local changes in ‘HH’ or ‘physical-constants’ can easily be contributed back to original source –Accurately reflecting provenance of any changes in the source workspace(s). Because this is all done in mercurial, collaborating independent of the central PMR server is trivial. When making a PMR exposure, all embedded workspaces are unambiguously described and permanently available. Similarly, zipping up the top-level MyModel folder into a COMBINE archive will capture all the relevant versioning data. 28