Integrative Biology VRE User Guide

N.B. This document is derived from a Wiki page and was written with a specific installation of the VRE software in mind. It should be re-written to take into consideration the needs of someone installing the system at their own institution. It also assumes a working knowledge of Memfem.

The Integrative Biology VRE (Virtual Research Environment) is a web-based graphical user interface and repository that provides an environment where biological simulation experiments can be constructed without the need for any knowledge of unix, cluster computing, or shell scripting.

This software is the result of a 2-year JISC-funded project of the same name <http://www.vre.ox.ac.uk/ibvre> based at the University of Oxford, which was set up to investigate and develop support for the research processes of the Computational Biology research community.

To date, the project has focussed on meeting the needs of the users of the Memfem simulation software, a nonlinear finite element simulation tool originally developed by Dr. James Eason <http://virtualheart.bmen.tulane.edu/pmwiki/pmwiki.php/Main/LabSoftware>, and used largely to perform simulations of the electrical activity of the heart. Several labs around the world use this software on a day-to-day to perform simulation experiments.

Future work intends to extend this to support other well-known simulation packages in this area. The IBVRE software as-is also only has support currently for clusters supporting the PBS queuing system, though a version supporting submission of experiments to Globus resources will be released in the very near future.

Key features include:

Organization

The VRE has a hierarchical structure where information is passed down the structure. The highest level is the Study. Under Study is Experiment and below that is Sub Experiment. Jobs (or simulations) can only be run from the lowest level. Variables defined at the Experiment level will be inherited by the Sub Experiment and cannot be changed.

Specifying a NodeSet for the Simulation

Node sets provide a convenient way to apply an identical stimulous to multiple nodes simultaneously. To refer to a node set in the VRE, enter its name in the Stimulation Node field in the VRE. Currently the rabbit geometry model has the following node sets built in:

name filename

-----------------------------------------

right_plate rabbit.right_plate.set

left_plate rabbit.left_plate.set

optical_points rabbit.optical_points.set

pace rabbit.pace.set

If you need to create a custom node set, it is necessary to write a .set file and deposit this directly on the cluster on which you want to run the simulation as the VRE does not yet have the facility to upload and store node sets in its database.

The current best practice is to put these files in the directory for the model they relate to. Models are stored in /home/ibuser/clusterhome/MEMFEM/<model> and the naming convention for node set files is <model>.<node set>.set.

TODO - specifying multiple node sets in the VRE.

Specifying Boundary Conditions and/or Ground

VRE does not automatically set a grounded point. Memfem needs this. Set the ground yourself using the Boundary File Optional Sets entry box on the Experiment page. The format for this boundary condition is always '<nodeset> ev -inf inf 0 square'. For example, to set a right plate ground condition add the following boundary condition:

right_plate ev -inf inf 0 square

In future, a ground condition parameter will be added to the VRE, and this extra boundary condition will be generated automatically.

Ischemic Simulations Requiring .dat files

DAT files map individual nodes in a particular geometry model to ionic model properties. They are needed for simulations investigating the effect of tissue heterogeneities.

As the VRE does not currently have the facility to upload and store DAT files in its database, for the time being, these files have to be deposited directly on the cluster before it is possible to run the simulations that require them.

There are two options available for doing this:

Reference the DAT files in your experiment through the Memfem Optional field in the VRE. For example,

-IschLRd.Ko.nodefile potassium.dat

-IschLRd.NaInhibition.nodefile nainhibition.dat

-IschLRd.CaInhibition.nodefile cainhibition.dat

-IschLRd.ADPi.nodefile ADP.dat

-IschLRd.ATPi.nodefile ATP.dat

-IschLRd.pATP.nodefile pATP.dat

If you have added the DAT files to a sub-directory - specify the path relative to the study directory in the Input Directory field in the VRE. In the above example, this would simply be datfiles.

Simulations Requiring Multiple Ionic Models

It is possible to run simulations requiring multiple ionic models through the VRE, though some admin work is required to add the ionic model combinations required to the VRE database. See VreAdminUpdates or contact MatthewMascord if you require an ionic model combination that is not currently available through the VRE interface.

Specifying a Restart File for the Simulation

To run simulations based on the restart file from a previous simulation:.

  1. Locate the experiment in the VRE from which you want to start the new simulation. (This must be within the same study you are working on.)

  2. Click on jobs, and note the job id of a successful simulation.

  3. Create a new experiment within the study.

  4. In Input Directory enter <job id>/output.

  5. In Memfem Optional add the -r [<time>] option to reference the required restart file.

In future, it will be possible to locate an experiment through the VRE, and click a button that will create a new experiment starting from a saved state of the previous simulation.