CellML Specification Draft — 30 September 2003

Get the PDF!

9  Importing Models

9.1  Introduction

The component-based architecture of CellML described in the previous sections gives modellers the ability to reuse parts of different CellML models. Often in systems biology, molecular behaviour is researched, modelled, and described in steps. One scientist will model the flux of ions across a cell membrane, for instance, limiting their study to certain variables. Others will build on the first's work, expanding the focus of the study, and so on. To reflect a realistic method of model building, a CellML modeller may choose to use the import features described below.

9.2  Basic Structure

To use the units definitions and components of an existing model, that model must be referenced within the current model using a <cellml:import> element. This element must be the child of a <cellml:model> element. The <cellml:import> element is used to locate the model from which components and units will be imported. The CellML import feature makes use of the W3C hyperlink standard, XLink, to identify the link between the current model and the model being imported. Each <cellml:import> element must have an xlink:href attribute. The xlink and cellml namespace prefixes are used throughout this section to indicate that the elements are in the XLink and CellML namespaces, respectively. The xlink:href attribute has a value equal to the Uniform Resource Identifier that identifies the location of the imported CellML model.

The <cellml:import> element may contain one or more <cellml:units> elements to declare the units that are being imported. A <cellml:units> element appearing as a child of a <cellml:import> element must have a units_ref attribute and a name attribute. The value of the units_ref attribute must equal the value of a name attribute of a <cellml:units> element in the model being referenced by the import. Units local to components may not be imported. The value of the name attribute is a unique identifier by which the component will be referenced throughout the rest of the model. The <cellml:units> element is described in detail in Section 5.

Similarly, the <cellml:import> element may contain one or more <cellml:component> elements to declare the component trees that are being imported. Component trees comprise of components and their descendants. For instance in Figure 17, the component tree of component 1 consists of components 1, 2, 3, 5, and 6. A <cellml:component> element appearing as a child of a <cellml:import> element must have a component_ref attribute and a name attribute. The value of the component_ref attribute must equal the value of a name attribute of a component in the model being referenced by the import. The value of the name attribute is a unique identifier by which the component will be referenced throughout the rest of the model. The <cellml:component> element is described in detail in Section 3.

Figure 17 The encapsulation hierarchies of two models. Blue boxes represent components, green arrows represent an encapsulated by relationship, thus component 5 is encapsulated by component 2, etc.

The connections are only maintained between the components and their component trees listed in one <cellml:import> element; therefore, if an imported component relies on values from other components in the original model, every component from which it obtains values needs to be imported. However, a modeller may use separate <cellml:import> elements locating the same model to import various component trees without connections.

Any components and units from another model referenced in the current model must first be declared in the <cellml:import> element. After imported units have been declared, they can be used in the same way any other units are used within a model. Connections may be made between imported components and components defined in the current model as described in Section 3.

9.3  Examples

Figure 18 demonstrates the use of the <cellml:import> element to import parts of another CellML model located at http://www.example.com/myocyte_model.xml which contains a component with a name of "sodium_channel" and a units definition with the name of "millivolts". In this model, we'll refer to the "sodium_channel" component as "Na_channel".

In a newly defined component in the current model (the membrane component), variables may use the imported millivolts units. The membrane component sends out the membrane voltage to the imported Na_channel component and receives the resulting value for the sodium current for subsequent calculations. It is not necessary to explicitly import encapsulated components because the entire component tree will be imported along with encapsulating components.

<model
    name="our_model.xml"
    xmlns="http://www.cellml.org/cellml/1.1#"
    xmlns:xlink="http://www.w3.org/1999/xlink">
  <import xlink:href="http://www.example.com/myocyte_model.xml">
    <units name="millivolts" units_ref="millivolts" />
    <component name="Na_channel" component_ref="sodium_channel" />
  </import>
  
  <component name="membrane">
    <variable name="I_Na" public_interface="in" units="flux" />
    <variable name="V" public_interface="out" units="millivolts" />
    ...

  </component>

  <connection>
    <map_components component_1="Na_channel" component_2="membrane" />
    <map_variables variable_1="V" variable_2="V" />
    <map_variables variable_1="I" variable_2="I_Na" />
  </connection>

</model>

Figure 18 The <cellml:import> identifies the URI of the model from which the components and units are being imported. See text for more details.

Figure 19 shows part of a description of the tricarboxylic acid (TCA) cycle. The modeller wants to import the resulting pyruvate concentration from the glycolysis pathway as the initial concentration of the pyruvate for the TCA cycle. Because the pyruvate concentration depends on the entire glycolysis pathway, all of the unencapsulated components from the CellML description of the glycolysis pathway need to be imported individually so that the connections between the components are maintained.

<import xlink:href="glycolysis_model.xml">
    <units name="micromolar" units_ref="uM" />
    <component name="global_variables" component_ref="global_variables" />
    <component name="Glycogen" component_ref="Glycogen" />
    <component name="UDP" component_ref="UDP" />
    <component name="UDP_glucose" component_ref="UDP_glucose" />
    <component name="Pi" component_ref="Pi" />
    <component name="Glucose_1_phosphate" component_ref="Glucose_1_phosphate" />
    <component name="pyruvate_init" component_ref="Pyruvate" />
    ...
    <component name="reaction0" component_ref="reaction0" />
    <component name="reaction1" component_ref="reaction1" />
    <component name="reaction2" component_ref="reaction2" />
    <component name="reaction3" component_ref="reaction3" />
    ...
  </import>

  <component name="pyruvate">
    <variable
    name="pyruvate" public_interface="out"
    initial_value="pyruvate_init_conc" units="uM" />
    <variable name="pyruvate_init_conc" private_interface="in" units="uM" />
    ...

  </component>

  <connection>
    <map_components component_1="pyruvate" component_2="pyruvate_init" />
    <map_variables variable_1="pyruvate_init_conc" variable_2="Pyruvate" />
  </connection>

Figure 19 The modeller wants to run the end pyruvate concentration of the glycolysis pathway through the TCA cycle. In order to do this, the model description of the TCA cycle (the current model) must import all of the unencapsulated components in the model description of the glycolysis pathway because the pyruvate concentration depends on the entire glycolysis pathway.

9.4  Rules for CellML Documents

9.4.1  The <import> element

1. Allowed use of the <import> element

   • A <cellml:import> element must contain only the following elements, which may appear in any order:

     • <component> and <units> elements in the CellML namespace,
     • <RDF> elements in the RDF namespace.

   • Each <cellml:import> element must define an xlink:href attribute.

     [ In this and subsequent rules, the cellml and xlink prefixes are used to indicate that elements and attributes are in the CellML and XLink namespaces, respectively. ]

2. Proper use of the <cellml:import> element

   • A model must not import a model that directly or indirectly imports itself.

     [ The model tree must be acyclic. ]

   • A model must not import a units definition that is local to a component.

3. Allowed values of the xlink:href attribute

   • The value of the xlink:href attribute must be a valid Uniform Resource Identifier.

9.5  Rules for Processor Behaviour

9.5.1  Treatment of imported units

Imported units become named instances in the current model.

[ Imported units are treated as templates from which to create instances in the current model. ]

9.5.2  Treatment of imported components

Imported components become named instances in the current model.

[ Imported components are treated as templates from which to create instances in the current model. ]