Tags:
create new tag
, view all tags

The VCML Specification Version 0.4

Introduction

The Virtual Cell Markup Language (VCML) is an XML document format for describing biological and mathematical models and specifications for analysis (e.g. simulations) to be performed on those models.

Versions

Version 0.4 is the baseline version derived from the native format of Virtual Cell 4.7. Version 1.0 will be a significant refactoring and removal of several major SBML incompatibilities. Used by first Open Source version of VCell (VCell 5).

This is a placeholder for a work-in-progress document. Final documents for each version of VCML will be deposited at http://projects.sourceforge.net/vcell/

Overview

This document describes the various Virtual Cell concepts (such as Unit representations in the Virtual Cell, Expression handling in the Virtual Cell (VCML), VCML symbols and namespaces, reserved symbols allowed in the Virtual cell. This document also presents the VCML document format and the specifications for the various VCML elements.

Unit Representation and Built-in Unit System in the Virtual Cell

Units in the Virtual Cell are not explicitly specified in VCML. Units for quantities in the Virtual Cell are based on the SI unit system. Each quantity in the Virtual Cell (species concentration, structure size, reaction rate, etc.) has pre-defined units, and in VCML, it is understood that these units hold for those quantities. The following table lists some of the basic quantities and their default units in the Virtual Cell.

Quantity Units
Length um
Area um2
Volume um3
Time second
Voltage mV
Current pA
Capacitance pF
Species Concentration in Feature (3-d compartment) uM
Species Concentration on Membrane (2-d compartment) molecules/um2
Reaction rate in Feature (3-d compartment) uM/sec
Reaction rate in Membrane (2-d compartment) molecules/um2/sec
Flux rate on Membrane (2-d compartment) uM.um/sec

Unit support in the Virtual Cell is provided with the use of an extenal java library from The University Corporation for Atmospheric Research (UCAR). The ucar.units package provides support for parsing and formatting string unit specification, converting numerical values between compatible units, and performing arithmetic on units (such as dividing one unit by another).

VCML expressions

Expressions in the Virtual Cell use the infix notation similar to the expression handling in C and Java languages. The only notation not handled by the Virtual Cell expression handler is the conditional operation { ( boolean_condition) ? ( value_1) : ( value2) }.

Similar to the C language, the following operators can be used in the Virtual Cell - arithmetic operators : +, -, *, /, ^; and logical operators : &&, &||*, !. Operations are performed on real numbers, not integers. Also, like the C language, Virtual Cell coerces booleans to real and real to booleans. For example, boolean false when converted to real gets a value of 0 and true is 1; and a non-zero real number when converted to boolean is true and zero is converted to false.

The following functions are allowed in Virtual Cell expressions: exp, sqrt, abs, pow, log, sin, cos, tan, asin, acos, atan, atan2, max, min, ceil, floor, csc, cot, sec, acsc, acot, asec, sinh, cosh, tanh, csch, coth, sech, asinh, acosh, atanh, acsch, acoth, asech, factorial, log10.

When expressions are written out to VCML from a Virtual Cell model, it is written out in MathML format.

VCML Identifier Symbols

When defining an identifier token (in expressions) in the Virtual Cell, the following syntax is used:

#ID: LETTER ( LETTER | DIGIT)

where LETTER: ["a"-"z", "_", "A"-"Z"] {alphabet and underscore characters}

and DIGIT : ["0"-"9"] {numbers}

An identifier can start with a letter or underscore character but not with a digit, followed by letters or digits.

Reserved Symbols

The Virtual Cell specifies a set of reserved symbols and constants that can be used in expressions and computations. The reserved symbols used in Virtual Cell are : x, y, z representing the x, y, z coordinates in with units of um and t representing time in seconds. The reserved constants used in Virtual Cell computations are listed in the table below.

Name Description Value Units
_T_ Absolute temperature - Kelvin (K)
_F_ Faraday constant 9.648e4 Coloumbs/mole (C/mol)
_F_nmol_ Faraday constant 9.648e-5 Coloumb/nano-mole (C/nmol)
_N_pmol_ Avogadro's number (scaled) 6.02e11 molecules/pico-mole (molecules/pmol)
_K_GHK_ Goldman_Hodgkin-Katz unit scale 1e-9 1e9
_R_ Gas Constant 8314.0 mV.C/K/mol
KMOLE Flux unit conversion 1.0/602.0 uM_um3_per_molecules
K_millivolts_per_volt voltage scale 1000 1e-3

MIRIAM compliance

The Minimum Information Requested In the Annotation of biochemical Models (MIRIAM) is a set of standards that help researchers to reuse, modify and combine computer models of biochemical processes. MIRIAM has two parts: (1) a ‘reference correspondence’ that matches each model to its description, documenting the model’s provenance and a stable link to its full description (often a journal publication), and (2) a set of annotation schemes linking the components of the model to relevant bioinformatics resources.

Currently Virtual Cell is working towards making the model, structures, species, and reactions comply with the MIRIAM standard for annotations. An editor has been developed to allow Virtual Cell users to enter MIRIAM compliant annotations in their model components. In VCML, the MIRIAM annotations are stored (in the 'rdf' format) in the annotation element of the corresponding element.

Description of VCML

VCML Container

VCML can have a <BioModel> element (that represents a Virtual Cell BioModel) or <MathModel> element (that represents a Virtual Cell MathModel) as a top level element.

The schema of VCML relationships is shown below:

vcml-general-schema.png

BioModel

A Virtual Cell BioModel, represented by the <BioModel> element, consists of a Model (represented by a <Model> element; containing all the necessary information needed to define the biological model, i.e., compartments, species, reactions, fluxes and geometry), one or more optional experimental set-ups or Applications (containing all the necessary information on how the model is simulated, such as parameters and solver settings; represented by the <SimulationSpec> element in VCML), and auxiliary information such as <Version> and different types of annotations. Below is an XML data object representing a full model:

XML-biomodel.png

A <BioModel> element has a required Name attribute of type String which identifies the BioModel. A BioModel can have an optional <Annotation> child used to store useful information about a model such as any comments that the creator of the model wishes to add to indicate what the model represents. The <Model> and <SimulationSpec> elements will be discussed in more detail in separate sections below. The required <Version> child of the BioModel stores version information for the BioModel. For models that have MIRIAM annotation, there is an additional <annotation> element which stores the MIRIAM annotation in the rdf format. The <BioModel> element is illustrated in the UML diagram below:

final_vcml_biomodel.png

Version

The Version of a BioModel or any Virtual Cell entity that has a Version represents the version information for the entity, such as the the key value in the BioModel database table, a description string, date and time of creation, owner, whether the entity is archived or not, etc. The version of a BioModel is automatically created when a BioModel (and the other model entities) are created and saved. In the VCML, the <Version> element represents the Version of the Virtual Cell model entities. The following entities have a Version : BioModel, MathModel, Model, SimulationSpec, Geometry, MathDescription, Simulation (and hence their corresponding VCML elements will contain a <Version> element).

The <Version> element is represented by the UML diagram below:

final_version.png

The <Version> element has the following attributes of type String:

Name : the name of the versionable entity

KeyValue : the database table key value of the entity

BranchId: this attibute is a marker for a group of related versioned models. All entities with the same branchId are versions of the same model.

Archived : represents the VersionFlag of the versionable entity. It can take one of 3 values: '0' represents Current which is the default/normal flag setting; '1' represents Archived which prevents users from deleting the entity; '3' represents Publish which indicates that the model/entity has been archived and published (in extenal publications) and is used internally to deter administrators from deleting the model from database. (Note: a value of '2' represents Unchanged which is not used any longer).

Date : Date of the last save of the entity in "dd-MM-yyyy HH"mm:ss" format.

FromVersionable : a boolean that represents if the entity is versionable.

In addition, the <Version> element contains the following elements:

<Owner> : Represents the owner of the versionable element. This element has the following attributes of type String: Name of the owner, and Identifier is an number that represents the key value of the owner in the Virtual Cell database.

<GroupAccess> : This element represents the accessibility/visibility of the entity for other users. It has a Type attribute which can have a value of '0' to indicate no group access (entity is 'private' and not shared); or a value of '1' which indicates group access to all (shared with all users of the Virtual Cell, or 'public' access), or a an arbitrary value representing a group id (access to the entity is allowed to some of the users). If the group access type is for some users, the <GroupAccess> element has an additional attribute Hash which contains a hash key. In this case, the <GroupAccess> element also has a list of <User> elements that represent the list of users that have access to the entity. Each <User> element contains the attributes of type String: Name of User; KeyValue of User in the Virtual Cell database; Hidden, which is a boolean value (true indicates that the User is hidden; false implies User is a normal user).

<Annotation> : This element contains the annotation string of the versionable entity.

<ParentSimRef> : This element is present only if the versionable entity is a Simulation. This has an attribute KeyValue that represents the keyvalue of the parent simulation (when only the name and nothing else is changed in a simulation that has been run and has results, the simulation should not be run again. This keyvalue allows the results to be obtained from the original (parent) simulation).

Model

A Model describes the physiology of the biological model : the cellular structures or compartments (represented as Feature for 3D and Membrane for 2D compartments in the Virtual Cell), species (represented as LocalizedCompound for a species and Compound for a species type in the Virtual Cell), and reactions (represented as SimpleReaction for a biochemical reaction and FluxStep for a transport in the Virtual Cell). A example VCML code for a model is as shown:

XML-model.png

UML representation of a physiological model:

final_model.png

A <Model> element has a required Name attribute of type String - if one is not provided, it uses a default name of 'unnamed_model'. The <Model> element has an optional <Annotation> element that contains a description of the model. It contains one or more <Feature> and <Membrane> elements - which represent the compartments of a cell; one or more <Compound> elements; one or more <LocalizedCompound> elements; zero or more <SimpleReaction> and <FluxStep> elements (which describe simple reactions or fluxes); one or more <Diagram> elements. A <Model> element also has a <ModelParameters> element and <Version> element (which contains necessary version information about the model).

The <Compound> element in VCML represents species in a model, and <LocalizedCompound> element represents species contexts (species with their associated compartments). LocalizedCompound is equivalent to Species in SBML, and Compound is roughly equivalent to SpeciesType in SBML. Unlike SBML, the number of LocalizedCompounds should equal the number of Compounds.

MLB: Compared to SBML, no numerical values for initial values or kinetics is given in the <Model> element - all numerics is given in SimulationSpec.

Features and Membranes

A physiological model contains Features and Membranes that represent mutually exclusive compartments within the cells. All features and membranes can contain molecular species and a collection of reactions that describe the biochemical behavior of those species within or adjacent to that feature or membrane.

A <Feature> element represents a 3-dimensional volumetric compartment. A <Membrane> element represents a 2-dimensional surface (or Membrane) separating Features. The Name and KeyValue fields, both of type String, are common for Feature or Membrane elements. In the case of <Membrane> element, a few additional fields (all of type String) are defined : the InsideFeature - indicates the name of the feature which the membrane encloses; OutsideFeature - indicates the name of the feature that encloses a membrane; and the MemVoltName field that represents the name of the voltage across the membrane.

Compound

A <Compound> element represents the molecular species type - any distinct state necessary to describe the biochemistry of the cell, for example, molecular conformation, receptor bound versus receptor unbound. A species (compound) can be separately defined in multiple compartments. The species are described by concentration and diffusion constants when associated with a compartment (volume species), and surface densities when associated with a membrane (membrane species). Species can participate in reactions, fluxes, and diffusion. Species diffusion is defined separately for each cellular compartment or membrane, and is specified by diffusion constants. There may be a flux of species through a membrane separating two neighboring compartments and species in adjacent compartments and membranes may react with one another.

A <Compound> element has a required Name attribute and an optional Annotation element, both of type String. In addition, the <Compound> element contains a <DBSpecies> element which links the compound with an existing database species, molecule, enzyme or compound (in the Virtual Cell database, KEGG, SWISSPROT databases).

Localized Compounds

A <LocalizedCompound> element represents the instance of a species in a particular compartment. It references the compound and the structure in which the species is located. When used in an expression, a localized cocmpound that is in a volume will take the value of the volumetric concentration (expressed in uM) and if the localized compound is on a membrane, it takes the value of surface density (expressed in molecules/um2).

A <LocalizedCompound> element has the following required fields : Name of type String which specifies the name of the localized compound; CompoundRef of type String which indicates the compound with which this localized compound element is associated; Structure of type String which indicates the name of the compartment in which the localized compound is located; a boolean HasOverride field which, if true, indicates that the localized compound name has been overridden (changed by the user), and if false, indicates that the localized compound name has not been changed by user (MLB explain) ; a KeyValue field of type String which contains the database key value of the localized compound.

Diagram

A <Diagram> element represents the reaction network in a structure (compartment) - it has shapes (icons) for localized compounds, simple and flux reactions. The UML diagram for Diagram element is shown below:

final_diagram.png

ModelParameters

Global parameters in the Virtual Cell are represented by the <ModelParameters> element in the <Model> element. The <ModelParameters> element contains a list of <Parameter> elements; each containing the expression for the parameter and having the following attributes of type String : a Name representing the name of the parameter, a Role attribute representing the parameter role (reaction rate or inward current density or user-defined), and a Unit representing the name of the units of the parameter. These parameters can be global consftants or functions of other global parameters or of model species. Note: when using species in global/model parameter expressions, the speciesContext name (the LocalizedCompound name), should be used.

Biochemical reactions and transport

The biochemical reactions represent complete descriptions of reaction stoichiometry and kinetics. Reactions can be either a collection of related reaction steps occurring in or near a single structure (e.g. membrane receptor binding, cytosolic calcium buffering), or transmembrane fluxes (e.g. flux through an ion channel). Each reaction is associated with a single cellular structure. The stoichiometry of a reaction is defined in terms of reactants, products, and catalysts, which are related to species in a particular cellular structure. It should be pointed out that reaction in a compartment involve only those species within that compartment, whereas reaction on a membrane involve the species on that membrane as well as the species present in the compartments neighboring the membrane. Numerically, the reaction rates and fluxes are represented symbolically by arbitrary algebraic expressions in terms of parameters and species concentrations.

The Reaction element in VCML is either a <SimpleReaction> element (representing a reaction in a 3-d compartment or membrane) or a <FluxStep> element representing a flux reaction on a membrane. Both these elements can contain an optional <Annotation> element.

SimpleReaction (Needs review)

A SimpleReaction contains the reaction participants - zero or more reactants, zero or more products and zero or more catalysts/modifiers of the reaction and the kinetics of the reaction. Reactants/products/modifiers refer to species in a given compartment - <LocalizedCompound>. It must be noted that there must be at least one reactant or one product for a reaction. The <SimpleReaction> element has the following attributes of type String : Name that indicates the name of the reaction; Structure that represents the Feature or Membrane in which the reaction takes place; FluxCarrierValence represents the value of the charge carrier valence (RMH: can we substitute "valence of the charged species"?; MLB: explain ) ; the FluxOption field indicates if the flux option is molecular only, molecular and electrical or electrical only (RMH: What is the electrical flux? where does it come from? Is molecular referring to the species?; MLB: explain ); KeyValue is the database key value of the simple reaction object (RMH: object=instance?;MLB: explain ). The <SimpleReaction> element also contains the <Kinetics> element which represents the kinetics of the reaction. Displayed below is the UML diagram and a VCML example to illiustrate a <SimpleReaction>:

final-simpleRxn.png

XML-simpleRxn.png

FluxStep

A FluxStep is associated with a single membrane and describes the flux of a single compound through that membrane. The flux compound must be a compound that is present in both neighboring compartments. A single inward flux is defined by with units (uM*um*s-1) and enforces flux conservation across the membrane. The flux is a function of flux carrier and catalyst concentration in the membrane's neighboring compartments and of membrane bound catalyst surface density. A <FluxStep> element has the attributes Name, Structure, FluxCarrierValence, FluxOption and KeyValue similar to the <SimpleReaction> element. In addition, it contains another attribute of type String - FluxCarrier, which represents the name of the species that is the flux carrier for the flux reaction. The <FluxStep> element also contains the <Kinetics> element (representing the kinetics of the flux reaction) and zero or more catalysts/modifiers for the flux reaction. The following UML diagram and VCML code represents a <FluxStep>:

final_fluxStep.png

XML-fluxRxn.png

Kinetics

The <Kinetics> element represents the reaction kinetics. Virtual Cell supports any user-specified kinetics (as General kinetics), and certain pre-defined kinetics (Mass-Action, Henri-Michaelis-Menten reversible and irreversible) for volume reactions. For flux reactions, the user can specify an arbitrary flux or use pre-defined General Current Density, Goldman-Hodgkin-Katz Permeability and Nernst Conductance kinetics options. Shown below is a VCML sample for the <Kinetics> element:

XML-kinetics.png

The <Kinetics> element in VCML has a KineticsType attribute of type String that represents the name of one of the kinetic types supported by the Virtual Cell (mentioned above). It also has a list of <Parameter> elements; each containing the expression for the parameter and having the following attributes of type String : a Name representing the name of the parameter, a Role attribute representing the parameter role (reaction rate or inward current density or user-defined), and a Unit representing the name of the units of the parameter. The parameter role inward current density is not defined for a reaction in a Feature (3-d compartment), it is defined only for reaction on a Membrane (2-d compartment).

SimulationSpec

A SimulationSpec is the VCML representation of an Application in the Virtual Cell, which establishes the association between a biological model, a geometry properly mapped to the biology, initial conditions, mathematical description, simulations and analysis. The <SimulationSpec> element has the following attibutes of type String : Name representing the name of the SimulationSpec or application, Stochastic which can take the value true or false indicating if the SimulationSpec is stochastic or not, an optional CharacteristicSize which indicates the characteristic size of the geometry image. In addition, the element contains an optional <Annotation> element of type string that stores a description of the SimulationSpec; a <Geometry> element that stores the geometry associated with the SimulationSpec; a <GeometryContext> element to represent the geometric mapping; a required <ReactionContext> element to represent the parameter/variable mapping; an optional <ElectricalContext> element that contains the <ElectricalStimuli> and the <GroundElectrode> elements for applications with electrophysiology; an optional <MathDescription> element; a list of <Simulation> elements, if present; an optional list of <AnalysisTask> elements (tasks set up for parameter estimation); a <Version> element that contains the version information of the SimulationSpec.

The following figures show the UML representation and a VCML example of the <SimulationSpec> element:

final-appln.png

Add ReactionSpec for ReactionContext.XML-simSpec.png

Geometry (Review)

Each Virtual Cell model requires a description of the cellular geometry to represent the behavior of the cellular system. A geometric model is used to represent the morphometry of a particular cell, or a portion of a cell. A typical cell contains various structures that can span a few orders of magnitude in scale. The geometry may be captured by researchers using various imaging modalities such as wide field, confocal, or electron microscopy. The decision to include small structures, i.e. intracellular mitochondria, depends on the ability to experimentally resolve such anatomical structures and the spatial scale of interest. Internal structures that are included in the physiological model, but are not spatially resolved in the geometry, will be mapped continuously (distributed) as a volume fraction of the enclosing compartment unless otherwise specified. In order to properly define a simulation domain, the geometry must be specified as 2-D or 3-D segmented images (based on pixel intensity) with the appropriate scaling information (pixel size defined in microns). Segmentation is necessary to establish discrete regions that represent the anatomical features of interest. Membranes are implicitly represented as the boundary between dissimilar compartments. For very regular structures or symmetric cells, analytic geometry may be a sufficient approximation to define the cell geometry instead of experimental images.

A <Geometry> element in VCML has a Name and Dimension attributes and contains an optional <Annotation> element, an <Extent> element and <Origin> co-ordinates, <Image> (if it is a spatial geometry), a <Subvolume> element, a <SurfaceDescription>, if present, and the <Version> element that contains the version information for the <Geometry> element. The <Geometry> element in the Virtual Cell is represented by the following UML diagram

final-geometry.png

The VCML code for a spatial geometry is as shown:

XML-geometry.png

Dimension attribute of type String represents the dimension of the geometry (0, 1, 2 or 3).

<Annotation> : optional, of type String, contains the description of the geometry if present.

<Extent> : contains 'X', 'Y', 'Z' string attributes indicating the extent of the geometry.

<Origin> : contains 'X', 'Y', 'Z' string attributes indicating the origin of the geometry.

<Image> : present if geometry is spatial (RMH:Clarify. when is a geometry spatial or not spatial?). This element represents a segmented image of n colors where there are n classes of volumetric compartments. This element has a Name attribute of type String and an optional <Annotation> element of type String. It contains an <ImageData> element that has attributes X, Y, Z for the x, y, z extent of the image and the CompressedSize attribute that specifies the compressed size of the image; and contains the encoded compressed pixels of the image. The image element also has an optional <Version> element with the version details of the image; and a list of <PixelClass> elements depending on the number of regions in the image; each <PixelClass> element has String attributes : Name - indicating the name of the pixelclass or image region, ImagePixelValue representing the integer pixel value, and an optional Key attribute containing the database keyvalue for the pixelclass.

<Subvolume> : The list of subvolumes elements in the geometry can be of one of the following types : AnalyticSubVolume, CompartmentSubVolume or ImageSubVolume. The three subvolume type elements each have the following attributes of type String : Name - indicating the name of the subvolume (region) in the geometry; Handle denoting the handle of the subVolume; Type which can be Analytic, Compartmental or Image; and KeyValue - representing the database keyvalue of the subvolume. In addition, if the subvolume type is AnalyticSubVolume, the <Subvolume> element contains an <AnalyticExpression> child element that contains the analytic expression for the subvolume; and if the subvolume type is ImageSubVolume, the <Subvolume> element contains the attribute ImagePixelValue representing the integer pixel value.

<SurfaceDescription> : refer to the section on SurfaceDescription below.

<Version> : represents the version of the geometry object (creation date and time, key value in the database, description of geometry, etc)

Surface Description and Regions

SurfaceDescription is a representation of the surface of the geometry. It is a collection of all the surface elements between the individual subvolume regions of the geometry. The <SurfaceDescription> element has the following attributes of type String : NumSamplesX, NumSamplesY, NumSamplesZ which indicate the x, y, z parameters of the size of the surface; CutoffFrequency which represents the filter cutoff frequency of the surface. In addition, the <SurfaceDescription> contains a list of geometric regions which can be MembraneRegions or VolumeRegions.

<MembraneRegion> element represents a surface Geometric Region. It contains the following attributes of type String : Name of the membrane region; the VolumeRegion_1 and VolumeRegion_2 attributes indicating the adjacent volume regions for the membrane; Size attribute for the membrane region, if it is set; and the Unit attribute that represents the units of the size.

<VolumeRegion> element represents a volume Geometric Region. It contains the following String attributes : Name of the volume region; RegionID representing the integer region ID for the volume region; SubVolume representing the subVolume name; Size containing the size of the volume region, if it is set; and and the Unit attribute that represents the units of the size.

GeometryContext

The <GeometryContext> element maps features and membranes to geometrical objects defined in Geometry. The <GeometryContext> element contains a list of <FeatureMapping> (for a volumetric compartment) and <MembraneMapping> (for a membrane) elements. The following figure is the UML representation of the <GeometryContext> element:

final-geom-context.png

A <FeatureMapping> element has the following attributes of type String : Feature represents the name of the feature (3-d compartment), Subvolume represents the name of the subvolume, Resolved indicates if the feature is resolved or not, Size contains the size of the feature if it is set. In addition, the <FeatureMapping> element contains a <BoundariesTypes> element, which contains the attributes (String) Xm, Xp, Ym, Yp, Zm, Zp - each of which can be set to Flux or Value - positive and negative values X, Y, Z boundary conditions.

A <MembraneMapping> element has the following attributes of type String : Membrane represents the name of the membrane; SurfaceToVolumeRatio, VolumeFraction, Size contain the expressions for the surface-to-volume ratio, volume fraction and size parameters, if they are set; CalculateVoltage tag that has values of true or false indicating if voltage should be calculated or not; SpecificCapacitance and InitialVoltage that contain the expressions for specific capacitance and initial voltage, if present (default values of 1.0 and 0.0 respectively).

ReactionContext

A <ReactionContext> element represents the reaction mappings in VCML. It contains a list of <LocalizedCompoundSpec> elements and a list of <ReactionSpec> elements. The UML representation of a <ReactionContext> element is shown below:

final-reaction-context.png

A <LocalizedCompoundSpec> element has the following attibutes of type String : LocalizedCompoundRef which is the name of the corresponding LocalizedCompound, ForceConstant which indicates if a concentration of LocalizedCompound is constant or not, EnableDiffusion which indicates if the LocalizedCompound has diffusion enabled or not. The <LocalizedCompoundSpec> element also contains an <Initial> element that contains the initial expression for the LocalizedCompound. If the SimulationSpec (application) is spatial, the <LocalizedCompoundSpec> element also has a <Diffusion> element that contains the diffusion rate for the speciesContext; and a <Boundaries> element which has attributes (of type string) Xm, Xp, Ym, Yp, Zm, Zp values for the LocalizedCompound (+ve and -ve values X, Y, Z boundary conditions).

A <ReactionSpec> element has two attributes of type String : ReactionStepRef the represents the name of the ReactionStep (reaction), and ReactionMapping has one of the following options : included, excluded, fast, molecular only, current only (representing if the reaction is included, excluded, fast, etc.).

Reaction mapping is a way for the user to specify the subset of reactions that have fast kinetics and the fast system will automatically be generated and integrated into the mathematical description by selecting or deselecting the option. The Virtual Cell software has been designed based on the separation of fast and slow kinetics, because there is often a wide range of time scales in interrelated cellular processes that pose a problem when computing numerical solutions.

Structure mapping is used to establish the relationship between the BioModel and Geometry documents. In the compartmental model, the structures defined in the model description are mapped to a single compartment (RMH: point?). A compartmental application ( SimulationSpec) represents a single point simulation that is based on the defined physiological model and the geometric assumptions (Are these different than the single point, i.e. homogenous?), the Surface to Volume Ratios and Volume Fractions. In a spatial application, each mutually exclusive volumetric region in the geometry must be mapped to a single volumetric compartment in the BioModel and an interface separating any two regions is mapped to the corresponding membrane. A compartment in the BioModel that is not spatially resolved in the geometry by default will be considered continuously distributed within the geometric region of its parent compartment.

Math Description

The MathDescription describes the class of mathematical systems that are encountered in the Virtual Cell. It is represented by the Virtual Cell Math Description language (VCMDL), which is a declaritive mathematics language. This language defines parameters, independent variables, differential/algebraic systems defined over a complex geometry including discontinuous solutions and membrane boundaries and the description of the task to perform on such a system.

The following figure is the UML representation of the <MathDescription> element:

final-math-desc.png

The <MathDescription> element has Name attribute and <Annotation> element of type String. It also has a <Version> element wihch contains necessary version information about the math description. The mathDescription element also contains lists of constants, variables, functions and Subdomains (refer to the next sections for further details). An example VCML for a MathDescription is shown below:

XML-mathDesc.png

Variables

Variables represent the variables used in the Virtual Cell Math Description Language (VCMDL). A Variable can be one of the following types :

Constant

A <Constant> element represents a constant in the math description, for example, initial conditions for species, other user-defined constants in reactions,or built in Virtual Cell constants (e.g., Faraday's constant, Temperature in Kelvin, Gas constant, etc.). The <Constant> element has a Name attribute of type String and contains the constant value in an expression.

Function

A <Function> element represents user-defined functions or functions generated for volume variables or membrane variables following the mass conservation rules during the math generation process. A <Function> element has a Name attribute of type String and contains an expression for the function.

VolumeVariable

A <VolumeVariable> element represents a state variable (species in the model) compartment in the math description. A volume variable in a spatial context has different values at different points in the volume. A <VolVariable> element has a Name attribute of type String.

VolumeRegionVariable MLB: what is it?

A VolumeRegionVariable in the math description is an element that represents a volumetric variable in a region in a spatial model. A VolumeRegionVariable has the same value within the region. A <VolumeRegionVariable> element has a Name attribute of type String.

MembraneVariable

A <MembraneVariable> element represents a state variable on a membrane in the math description. A MembraneVariable is used only in a spatial model and the element has a Name attribute of type String.

MembraneRegionVariable MLB: what is it?

A <MembraneRegionVariable> in the math description is an element that represents a membrane variable (species) in a spatial model. A <MebraneRegionVariable> element has a Name attribute of type String. It has a single value for a contiguous patch of membrane of the same type (membrane region), for e.g., a contiguous patch of plasma membrane. Example of MembraneRegionVariable is the membrane electric potential for the cell that is well-clamped spatially (where the membrane potential is equipotential).

StochVolVariable MLB: what is it?

A <StochVolVariable> in the math description is an element that represents a stochastic variable (or species) in the model. A <StochVolVariable> element has a Name attribute of type String. It represents a discrete valued random var that is currently integer-valued. Stochastic equations are going to be integer-valued and associated with a Poisson process.

CompartmentSubDomain

A <CompartmentSubDomain> element represents a volumetric subdomain. The <CompartmentSubDomain> element has a Name and a Priority attribute of type String. The value represented by the Priority attribute string should be such that if two CompartmentSubDomains are separated by a MembraneSubDomain, the priority of the inside CompartmentSubDomain must be greater than that of the outside CompartmentSubDomain. It also contains <BoundayType> elements for negative and positive X, Y, Z directions (Xm, Xp, Ym, Yp, Zm, Zp). Each <BoundayType> element has two attributes of type String : Boundary (which takes values of Xm, Xp, Ym, Yp, Zm, Zp depending on which boundary type element it is); and a Type which can be Dirichlet (Flux) or Neumann (Value).

A CompartmentSubDomain also contains a list of Equations ( <PdeEquation> and <OdeEquation>, representing the equations that are generated from the geometric mapping of the model), a fast system, if any; and if the model is stochastic, a list of <VariableInitialConditions> and <JumpProcesses>.

MembraneSubDomain

A <MembraneSubDomain> element represents a surface (membrane) subdomain. The <MembraneSubDomain> element has an InsideCompartment and an OutsideCompartment attribute of type String, representing the names of the volumetric compartments that are inside and outside the membrane respectively. It also contains <BoundayType> elements for negative and positive X, Y, Z directions, similar to the ones defined for CompartmentSubDomain above.

A MembraneSubDomain also has a list of equations ( <PdeEquation> and <OdeEquation>), a fast system, if any; and a list of <JumpConditions>.

OdeEquation

An <OdeEquation> element represents an ODE equation for a variable. It has a Name attribute of type String which indicates the name of the variable of the Ode equation. It contains a <Rate> element and an <Initial> element. The <Rate> element contains the Ode rate expression (default value of 0.0) for the variable. The <Initial> element contains the initial value of the variable.

PdeEquation

A <PdeEquation> element represents a Partial Differential Equation for a variable. PDEs are present only in spatial models. A <PdeEquation> element has a Name attribute of type String indicating the name of the PDE equation variable; an optional <Boundaries> element which has attributes Xm, Xp, Ym, Yp, Zm, Zp (of type string) that represent the positive and negative values of X, Y, Z boundary conditions for the variable; a <Rate> element containing the PDE variable rate expression (default value of 0.0); a <Diffusion> element that contains the variable diffusion rate (default value of 0.0); an <Initial> element for the initial value of the PDE variable; and an optional <Velocity> element that contains the attributes X, Y, Z that represent the velocities in the x, y, z directions.

JumpCondition

A <JumpCondition> element represents an internal flux boundary conditions for reaction diffusion equations defined over volumes at membrane boundaries. The <JumpCondition> element has a Name attribute of type String; an <Influx> element containing an expression that represents the flux moving from the membrane to the inside compartment (the compartment enclosed by the membrane); and an <Outflux> element containing an expression that represents the flux moving from the membrane to the outside compartment (the compartment enclosing the membrane).

FastSystem

A <FastSystem> element is defined in each domain that has fast reactions and represents a fast system or the set of reactions that have fast kinetics in a domain in the model. A FastSystem element has one or more (depending on the number of reactions that are fast) <FastInvariant> elements each of which contains the expression of the fast invariant for the reaction; and one or more <FastRate> elements each of which contains the expression of the fast rate (reaction rate) of the reaction.

VolumeRegionEquation

A VolumeRegionEquation is an equation describing the dynamics of a VolumeRegionVariable. The <VolumeRegionEquation> element representing the VolumeRegionEquation has a Name attribute for the VolumeRegionVariable. This element contains rate elements ( <UniformRate>, <VolumeRate> and <MembraneRate> with default values of 0.0) that are evaluated on the region and integrated over adjacent surfaces and integrated over the volume (to look at net effects of heterogenous contributions). This is useful for infinite diffusion approximation within a volume domain. In addition, the <VolumeRegionEquation> contains the <Initial> element for the initial value expression of the VolumeRegionVariable and a <SolutionType> element which contains a_Type_ attribute of type String (which can take a value of '0' for Unknown Solution and a value of '1' for Exact Solution). If the solution type is Exact, the <SolutionType> element contains the expression for the exact solution.

MembraneRegionEquation

A MembraneRegionEquation is an equation describing the dynamics of a MembraneRegionVariable. The <MembraneRegionEquation> element has a Name attribute for the MembraneRegionVariable. The element contains rate elements ( <UniformRate> and <MembraneRate> with default values of 0.0) that are evaluated on the region and integrated over adjacent surfaces and integrated over the volume. For example, all electric currents (which may not be uniformly distriubuted across the membrane) passing through the membrane are summed to determine the total current which is used to update the membrane potential. In addition, similar to the <VolumeRegionEquation>, the <MembraneRegionEquation> has an <Initial> element a <SolutionType> element.

Electrical Context

An <ElectricalContext> element specifies the Membrane Potential Options and Electrical Stimulus that can be applied to flux reactions. The Membrane potential options table lists the membranes in the BioModel and the user has the option of specifying the initial voltage (V_initial) and the specific capacitance of each membrane. The user can choose between three options for the applied electrical stimulus: no clamp, voltage clamp or current clamp. Electrical Mapping is available in both Spatial and Compartmental models. In Compartmental models the user cannot specify clamp or electrode position. The UML diagram for ElectricalContext is as shown below:

final-electricalcontext.png

ElectricalStimuli : This can be either a VoltageClamp stimulus or a CurrentClamp stimulus. The ElectricalStimuli is represented by the <Clamp> element which has an attribute Type of type String that indicates if it is voltage or current clamp. It also contains an <Electrode> element and a list of <Parameters> (electricalStimulusParameters). The <Electrode> element has a Feature attribute of type String that represents the name of the feature where the electrode is located, and contains the <Coordinate> element that has attributes X, Y, Z indicating the x, y, z coordinates of the electrode position. Each <Parameter> element has the attributes (of type String) Name for paramter name; Role indicating the parameter role (voltage, current or user_defined); and Unit representing the parameter units; and contains the parameter expression.

<GroundElectrode> : This element represents the ground electrode property of the electrical mapping. The <Electrode> (Add to UML diagram) element is the same as decscribed above, containing the Feature attribute with the name of the feature where the ground electrode is located and containing the <Coordinate> element representing the position coordinates of the ground electrode.

Simulations

Once the BioModel and Application(s) or the MathModel have been set up, simulations can be created and run. The appropriate solvers for non-spatial (ODE) and spatial models (PDE) will automatically be implemented based on the mathematical description. The non-spatial simulation executes a single point simulation based on the defined physiological model and the geometric assumptions, surface-to-volume ratios and volume fractions. The ODEs for single point approximations, representing the reactions kinetics are generated and passed to an interpreted ODE solver. This system of equations is solved using one of a variety of integration schemes. For a spatial model, the Math Description consists of PDEs that correspond to diffusive species and ODEs for non-diffusive species.

The <Simulation> element has a Name attribute of type String and an optional <Annotation> element of type String that contains a description of the simulation. In addition, it contains the following elements : <SolverTaskDescription>, <MathOverrides>, <MeshSpecification>, <Version>. The <Version> element contains version information for the simulation, namely, database keyValue, creation date and time, description, etc. A UML diagram and an example VMCL code for simulation is shown below:

final-simulation.png

XML-simulation.png

SolverTaskDescription

The <SolverTaskDescription> element describes the solver-related specifications such as the time bounds, time step, error tolerance, solver type, etc. It has the following attributes of type String : TaskType that can take the values Steady or Unsteady and indicates if the simulation represents the system in steady state or not; UseSymbolicJacoboan that can take values of true or false to notify that the solver uses Symbolic Jacobian; and SolverName that contains the name of the solver. For a non-spatial simulation, the possible solver type values are : Forward Euler, Runge-Kutta (Second Order, Fixed Time Step), Runge-Kutta (Fourth Order, Fixed Time Step), Runge-Kutta-Fehlberg (Fifth Order, Variable Time Step), Adams-Moulton (Fifth Order, Fixed Time Step), IDA (Variable Order, Variable Time Step, ODE/DAE), CVODE (Variable Order, Variable Time Step). For a spatial simulation, the possible solvers are : Finite Volume, Regular Grid, Finite Volume Standalone, Regular Grid; and for a stochastic simulation, the possible solvers are : Gibson, Hybrid (Gibson + Euler-Maruyama Method), Hybrid (Gibson + Milstein Method), Hybrid (Adaptive Gibson + Milstein Method). In addition, the <SolverTaskDescription> has the following elements :

<TimeBounds> : This element has the attributes StartTime and EndTime of type string, that specifies the start and end times for the simulation.

<TimeStep> : This element has the attributes MinTime, DefaultTime, and MaxTime which represent the minimum time step (default value 1e-8), default time step (0.1), and maximum time step (1.0).

<ErrorTolerance> : This elemebt has the attributes Absolute and Relative that contain values for the absolute (default 1e-9) and relative (default 1e-9) error tolerances.

<OutputTimeSpec> : This element represents the times at which output is calculated. It can be of 3 types : default, explicit or uniform. If it is default, it has the followng attributes : KeepEvery and KeepAtMost, which specify the points at which the output is retained and maximum number of output values to be retained in the result set. If the OutputTimeSpec is explicit, it has the attribute OutputTimes that contains a comma or space separated list of time points at which output values have to be computed. If the OutputTimeSpec is uniform, it has the attribute OutputTimeStep that contains the uniform time interval between the start and end times of the simulation at which the output values have to be computed - this option is useful for variable time step solvers when it is required to compute output values at fixed time steps.

<StochSimOpton> : This element is present if the simulation is stochastic. It has the following attributes of type String : UseCustomSeed which can be true or false indicating if the simulation uses a custom seed or not; if UseCustomSeed attribute is 'true', the StochSimOption has the attibute CustomSeed which contains the value of the custom seed; NumberOfTrial attribute that contains the number of trials for the stochastic simulation; and if the stochastic solver is hybrid, it has the following attributes : Epsilon, Lambda, MSRTolerance, SDETolerance.

<SensitivityParameter> : This element is present in the SolverTaskDescription only if sensitivity analysis has been enabled for the simulation. It is the same as a Constant element, and has a Name attribute representing the name of the sensitivity parameter (RMH: paramter to be analyzed?) and contains the parameter expression value (initial value/expression?).

MathOverrides

The <MathOverrides> element of Simulation contains the parameters of the model that have been overridden for this simulation. It contains a list of <Constant> elements (as described previously, with a Name attribute and containing the constant expression/value). Each item in the list corresponds to an overridden parameter in the simulation. If the overridden parameter is a scan (multiple override values for same parameter), that <Constant> element has another attribute in addition to Name, ConstantArraySpec, which can have a value of 1000 if it is an explicit list of values (e.g., 0.0, 0.2, 0.5, 1.0) or 1001 if the scan values are in an interval (e.g., 0.0 to 1.0, 5 values); and instead of containing a single expression/value for the parameter, it will contain the list or the interval of values.

MeshSpecification

The <MeshSpecification> element of Simulation is available only for spatial simulations. It contains the size of the mesh or the grid points in the spatial geometry where the solution is to be computed. This element contains the element <Size> which has attributes X, Y, Z that specify the mesh size in the x, y, z directions (for a 2-D geometry, only x and y are specified).

Analysis Task

An Analysis Task represents the parameter estimation task that can be run in a Virtual Cell application. Currently, parameter estimation in the Virtual Cell is allowed only for non-spatial applications (or SimulationSpecs). If parameter estimation is present in a given Virtual Cell application, the <SimulationSpec> element contains a <AnalysisTaskList> element. The UML diagram for the <AnalysisTaskList> element is as shown below:

final-analysis-task.png

MathModel

A MathModel (stands for Mathematical Model) element allows a biological model to be specified as a class of mathematical systems using the Virtual Cell Math Description Language (VCMDL), a declarative mathematics language. This language defines parameters, independent variables, differential/algebraic systems defined over a complex geometry including discontinuous solutions and membrane boundaries, and the description of tasks to be performed on such a system. The figure below shows a UML diagram for a mathematical model:

final_mathmodel.png

A <MathModel> element is similar to <BioModel> element in that it has a required attribute Name used to identify a model. It can have an optional <Annotation> child, used to store a description of the mathematical model. It also contains the following elements : a <Geometry> element that represents the geometry of the model; a <MathDescription> element that describes the mathematical system that represents the model; a list of <Simulation> elements, if present; and a <Version> element that contains the version information for the model. The attributes and contents of these elements are the same as those defined for these elements in the BioModel.

Math namescope, Bio namescope and Scoping Rules

Each entity in the BioModel (and MathModel) are defined in separate namescope, with its own set of available logical symbols (or identifiers). If an entity is defined within another (parent) entity, some of the symbols defined in the child entity are not accessible in the parent entity or another peer entity; but symbols defined in the parent entity are available in the children entities. For example, a species initial condition defined in an application (also referred to as SimulationSpec or SimulationContext) is not accessible in the model, but global parameters defined in the model is available in the application. Also, when the math is generated in the application or MathModel, it has its own namescope, hence the generated symbols are not accessible in the model or application. The following table lists each namescope (used interchangeably with namespace) and the available symbols in that namescope.

NameScope Available symbols in namescope
Model Reserved Symbols, global parameters, structure sizes, membrane voltages, speciesContexts
Reaction Charge Carrier Valence, kinetics parameter, unresolved kinetics parameters, Model level parameters
SimulationContext (Application) Reserved Symbols, simulationcontext parameters (none defined yet), Model level parameters
ElectricalStimulus Reserved Symbols, ElectricalStimulus Parameters (total current, potential difference, user defined)
StructureMapping SurfaceToVolumeRatio, VolumeFraction, SpecificCapacitance, InitialVoltage, structureSize
SpeciesContextSpec Reserved Symbols, Initial Condition/initial count, diffusion rate, boundary conditions (Xm, Xp, Ym, Yp, Zm, Zp), velocity (Vx,Vy,Vz), Model level parameters
ReactionSpec Reserved Symbols, reactionSpec Parameters (none defined yet), simulationContext level parameters
MathMapping Reserved Symbols, MathMapping parameters (probability parameter, species concentration paramter, species couint parameter, KFluxparameter, total mass, etc), Model level parameters, SimulationContext level parameters

The diagram below depicts the namescope heirarchy in a BioModel (the math namescope is flat with no accessibility from other namescopes and hence is independent).

final-vcml-namescope.png

Examples

XML Schema for VCML

Biomodel_VCML_Schema_10_09.xsd: XML Schema for a Virtual Cell BioModel.

Mathmodel_Compartmental_VCML_Schema_10_09.xsd: XML Schema for a Virtual Cell Mathmodel (compartmental/non-spatial geometry).

Mathmodel_Stochastic_VCML_Schema_10_09.xsd: XML Schema for a Virtual Cell Mathmodel (stochastic).

Mathmodel_Spatial_VCML_Schema_10_09.xsd: XML Schema for a Virtual Cell Mathmodel (spatial).

Developer notes

1. SimulationSpec are referred to users in VCell interface and manuals as Applications and internally in the VCell code base as SimulationContext .

2. In VCell code base Features and Membranes are referred as Structures.

3. Note that Compound is referred to users in VCell interface and manuals and internally in the VCell code base as Species .

4. Note that LocalizedCompound is referred to users in VCell interface and manuals as Species and internally in the VCell code base as SpeciesContext .

5. In VCell code base geometry dimension, extent and origin co-ordinates, image (if it is a spatial geometry), and subvolumes are contained in a class GeometrySpec.

6. surfaceGeometricRegion, volumeGeometricRegion ???

7. A SimulationSpec is called SimulationContext in the VCell code base. The SimulationContext consists of Structure Mapping, Initial Conditions, Reaction Mapping, Electrical Mapping, Math, Simulations, and Analysis (for parameter estimation).

8. What is Boundary Conditions? For resolved Structures (compartments), there are two choices for boundary conditions Neumann (for flux) and Dirichlet (value) conditions.

Topic attachments
I Attachment Action Size Date Who Comment
Unknown file formatdia Diagram1.dia manage 2.5 K 2007-09-19 - 12:31 JimSchaff diagram for VCML
PDFpdf VcmlSpec___VCell___TWiki-old.pdf manage 188.4 K 2009-06-04 - 00:15 MichaelBlinov  
PNGpng XML-biomodel.png manage 10.0 K 2008-01-29 - 17:25 AnuradhaLakshminarayana Xml snippet for Biomodel element
PNGpng XML-fluxRxn.png manage 7.0 K 2008-01-29 - 00:11 AnuradhaLakshminarayana Xml snippet for FluxReaction element
PNGpng XML-geometry.png manage 18.6 K 2008-01-29 - 17:29 AnuradhaLakshminarayana Xml snippet for Geometry element
PNGpng XML-kinetics.png manage 7.4 K 2008-01-29 - 00:11 AnuradhaLakshminarayana Xml snippet for Kinetics element
PNGpng XML-mathDesc.png manage 21.2 K 2008-01-29 - 17:27 AnuradhaLakshminarayana Xml snippet for MathDescription element
PNGpng XML-model.png manage 16.0 K 2008-01-29 - 18:07 AnuradhaLakshminarayana Xml snippet for Model element
PNGpng XML-simSpec.png manage 18.1 K 2008-01-29 - 19:56 AnuradhaLakshminarayana Xml snippet for SimulationSpec element
PNGpng XML-simpleRxn.png manage 9.0 K 2008-01-29 - 00:10 AnuradhaLakshminarayana Xml snippet for SimpleReaction element
PNGpng XML-simulation.png manage 10.5 K 2008-01-29 - 17:30 AnuradhaLakshminarayana Xml snippet for Simulation element
PNGpng final-analysis-task.png manage 13.5 K 2009-07-13 - 21:15 AnuradhaLakshminarayana AnalysisTask UML diagram
PNGpng final-appln.png manage 8.8 K 2009-07-13 - 21:35 AnuradhaLakshminarayana SimulationSpec UML diagram
PNGpng final-electricalcontext.png manage 8.0 K 2009-07-13 - 21:16 AnuradhaLakshminarayana ElectricalContext UML diagram
PNGpng final-geom-context.png manage 8.2 K 2009-06-29 - 20:38 AnuradhaLakshminarayana Geometry Context UML diagram
PNGpng final-geometry.png manage 15.5 K 2009-06-29 - 19:54 AnuradhaLakshminarayana Geometry UML diagram
PNGpng final-math-desc.png manage 19.7 K 2009-06-29 - 19:53 AnuradhaLakshminarayana MathDescription UML diagram
PNGpng final-reaction-context.png manage 6.8 K 2009-06-29 - 20:46 AnuradhaLakshminarayana ReactionContext UML diagram
PNGpng final-simpleRxn.png manage 9.9 K 2009-07-14 - 14:55 AnuradhaLakshminarayana Simple Reaction UML diagram
PNGpng final-simulation.png manage 10.8 K 2009-07-14 - 14:55 AnuradhaLakshminarayana Simulation UML diagram
PNGpng final-vcml-namescope.png manage 55.9 K 2009-11-03 - 16:47 AnuradhaLakshminarayana VCML Namescope hierarchy
PNGpng final_diagram.png manage 7.1 K 2009-07-14 - 14:54 AnuradhaLakshminarayana Diagram UML diagram
PNGpng final_fluxStep.png manage 7.5 K 2009-07-14 - 14:55 AnuradhaLakshminarayana FluxStep UML diagram
PNGpng final_mathmodel.png manage 6.4 K 2009-10-13 - 21:43 AnuradhaLakshminarayana MathModel UML
PNGpng final_model.png manage 15.5 K 2009-06-29 - 15:06 AnuradhaLakshminarayana Model UML diagram
PNGpng final_vcml_biomodel.png manage 10.0 K 2009-06-26 - 19:42 AnuradhaLakshminarayana VCML-Biomodel UML diagram
PNGpng final_version.png manage 8.5 K 2009-09-30 - 16:55 AnuradhaLakshminarayana Version UML diagram
PNGpng vcml-general-diagram.png manage 6.8 K 2009-09-17 - 21:28 AnuradhaLakshminarayana General VCML (schema) diagram
PNGpng vcml-general-schema.png manage 6.8 K 2009-09-18 - 20:30 AnuradhaLakshminarayana General VCML schema diagram
PNGpng vcml_general.png manage 6.8 K 2009-09-17 - 20:53 AnuradhaLakshminarayana General VCML (schema) diagram
Topic revision: r59 - 2011-03-09 - 18:30:40 - AnuradhaLakshminarayana
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback