CellML in practice: modularity & reuse; versioning & provenance; embedded workspaces

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

2. A useful reference • http://abibook.readthedocs.org/en/EMBC-2013-tutorial/tutorials/embc13/index.html

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…

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 componentsto 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 @ changeset755e83040c8ea71167d2bb50c2593f4f0092fa67 • 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.