CellML in practice: modularity & reuse; versioning & provenance; embedded workspacesDavid NickersonAuckland Bioengineering InstituteUniversity of AucklandNew Zealand

2

A useful reference• http://abibook.readthedocs.org/en/EMBC-2013-tutorial/t

utorials/embc13/index.html

3

4

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…

5

6

7

8

9

10

11

12

13

14

15

16

17

Versioning and provenance

18

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

19

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., http://models.cellml.org/e/e1/tutorial

• 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?

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).

21

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?

22

A solution – embedded workspaces• Mercurial subrepositories

– A little concerning:

23

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.

24

In CellML (my-model.xml)<import xlink:href=“HH/gating-variable.xml”>

<component name=“hGate” component_ref=“gate”/></import><import xlink:href=“physical-constants/mohr_taylor_newell_2008.xml”>

<component name=“constants” component_ref=“codata_2006_universal”/></import>

25

On the local file system…• My Model/

– HH/• gating-variable.xml• …

– physical-constants/• mohr_taylor_newell_2008.cellml

– my-model.xml– .hgsub, defines:

• HH http://models.cellml.org/w/andre/hodgkin-huxley-model

• physical-constants http://models.cellml.org/workspace/mohr_taylor_newell_2008

26

…on the local file system• My Model/

– …– .hgsubstate, defines:

• Use HH repository @ changeset 755e83040c8ea71167d2bb50c2593f4f0092fa67

• Use physical-constants repository @ changeset c506f07a2d935261f0117d8ed7d2667b7dcf7b78

27

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.

28

…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.