Meeting Minutes - 14 March 2000

WARNING : Work in Progress!

Component Re-use in the Physiome Languages

Currently the three Physiome Languages have different mechanisms for referencing language components that are to be re-used. Examples of some component re-use are given in Figure 1.

AnatML

<body_part
    name = "leg"
    type = "group">
  <link_body_part
      name = "fibia"
      href = "./fibia.xml" />
</body_part>

CellML

<boundary>
  <uses>
    <mechanism
        name = "sodium_channel" />
    <mechanism_ref
        name = "HH_gate"
        href = "./HH_gate.xml" />
  </uses>
</boundary>

FieldML

<define
    name = "linear_map">
  <matrix />
</define>

<copy_matrix
    rename   = "map_1"
    name_ref = "linear_map" />
<share_matrix
    rename   = "map_2"
    name_ref = "linear_map" />

Figure 1 Some examples of component re-use in the current Physiome Languages.

The mechanisms for component re-use must be standardised across the languages to minimise the complexity of learning the correct use of these languages, for both those developing software and those entering data. Although they go under a variety of guises in the above examples, there are really only two intended types of re-use here, copying and referencing, and these are handled by two different kinds of elements as discussed in the following section.

Copying Components

In the first type of component re-use, objects are supposed to be copied from the specified target to the current location (replacing the referencing tag). This type of behaviour is particularly useful in FieldML where a mesh might typically be created by re-using an element multiple times, re-naming each new instance with a unique identifier, and perhaps adding or modifying information to the new instance (a process which will be discussed later.)

In examples up to this points, tags indicating copying had started with copy_. This will now be changed to a _copy suffix. A copy tag indicates to the processing application that it should be overwritten by the target, and re-named, if necessary. The DTD definition for a typical object-copying tag is given in Figure 2. Note that the tag's content model may not actually be empty, as we will see later.

<!ELEMENT  element_copy    EMPTY>
<!ATTLIST  element_copy
    name_ref          CDATA         #REQUIRED
    href              CDATA         #IMPLIED
    rename            CDATA         #REQUIRED>

Figure 2 The DTD definition for a typical object-copying tag.

The @name_ref attribute and @href attributes, combined with the type of object being copied (evaluated by removing the "_copy" from the tag name) uniquely identify an object to be copied. The value of the @name_ref attribute must match either the value of the @name attribute of the target object, or the @rename attribute of another copy tag for the same object type that is in the current scope (scope remains undefined.) The @href attribute contains information that uniquely identifies the resource in which the target object is stored, which may be a filename, URL or database reference. For this reason it should contain a protocol and locator components, as shown in the following valid examples:

http://www.physiome.org.nz/data.xml
file:/physiome/data.xml
file:///c:/physiome/data.xml (c: must be preceded by three slashes)

Why @href one might well ask. The reason is that those familiar with HTML will instantly recognise this attribute as the locator attribute belonging to an HTML linking tag. If the @href attribute is omitted then the target object should reside within the same resource as the reference.

The @rename attribute, which is required for copying tags, specifies what the @name attribute of the target object should be set to when it is copied into its new location. Its value should be unique for the specific object type within the current scope (although the rules on naming scope have really been defined yet, there will be some!). One clear rule is that the value of the @rename and @name_ref attributes must be different - otherwise there could be two objects of the same type with the same name in the same scope.

Note that the @rename attribute is not the same as a @name attribute; whereas the latter indicates the name of the current tag, the former indicates the name of the tag which will replace the current tag. ???_copy tags will probably be the among the few tags in the Physiome Languages to not have @name attributes.

Referencing Components

The second type of component re-use is currently handled by the link, reference and share tags of AnatML, CellML and FieldML respectively. The intent is to create a link from the current object to the object referenced. The DTD for a typical reference is given in Figure 3.

<!ELEMENT  mechanism_ref    EMPTY>
<!ATTLIST  mechanism_ref
    name_ref          CDATA         #REQUIRED
    href              CDATA         #IMPLIED>

Figure 3 The DTD definition for a typical object-referencing tag.

As for the copying tags, the target is uniquely identified by the combination of the @name_ref and (if required) @href. No @rename attribute is required because this tag represents a link to an existing object, rather than the object itself.

Other Options

Before arriving at this scheme, various other options were considered. It would be a simple matter to merge the "??_copy" and "??_ref" elements, making the exact behaviour hinge on the presence of the @rename attribute. This option was discarded because of the increased validation powers available if the two are split up - particularly as there are many places where only references are legal, and others where only copying is appropriate.

The `<define>` Element

With all this excitement, some readers may think we had forgotten the <define> tag from FieldML (other readers may have noticed it but not really known what it was for). It was never properly explained that the <define> tag is aimed at letting the document author template a structure anywhere within a PhysiomeML document, that will be referenced or copied later. The <define> tag signals to the processing application that it doesn't have to explicitly create an object corresponding to the tag's contents as they are encountered, but only when they are referenced later. The tag also lets templates be inserted where they are most useful (a <define> tag can be placed almost anywhere in a document), where the actual tag's contents would not be appropriate. For instance, a matrix that will be used as a linear map can be defined within the field description at a position where a <matrix> element would not normally be allowed, and then referenced one or more times later in the same file.

One of the more useful functions of the <define> element involves the sharing of several copies of the same element. This is best illustrated by an example: say you define a matrix for use as a linear map for three geometric fields, and then realise that it is a valid map for some other fields, given a small change. Rather than defining a completely new matrix, or referencing the original and specifying the changes each time it is referenced, why not define a <matrix_copy> element which references the original and make any changes inside this prototype. The processing application should treat the <matrix_copy> element as though it was replaced by the referenced matrix and re-named. This new matrix can then be referenced (and hence shared) where necessary.

<define> elements are not required when the template is the root element of a file (or data resource), as the file will never be parsed unless specifically referenced, so the processor does not need to know that this is a template. This means that large components that are stored in a database and frequently referenced do not need <define> tags.

Some Examples

In Figure 4, some examples of the correct use of the new component re-use mechanism are given for each of the three main Physiome Languages.

AnatML

<body_part
    name = "leg"
    type = "group">
  <body_part_ref
      href     = "./fibia.xml"
      name_ref = "fibia" />
</body_part>

FieldML

<region>
  <-- you can't put a matrix here, but you can define one !! -->
  <define>
    <matrix
        name = "linear_map">
      ...
    </matrix>
  </define>

  <define>
    <element
        name = "my_element">
      <shape>
        <vector><ci>line</ci><ci>line</ci></vector>
      </shape>
      ...
    </element>
  </define>

  <mesh>
    <element_copy
        rename   = "1"
        name_ref = "my_element" />
    <element_copy
        rename   = "2"
        name_ref = "my_element" />
    ...
  </mesh>

  <field>
    ...
    <generalized_field_description>
      ...
      <ensemble_element_field_parameter_map>
        <matrix_ref
            name_ref = "linear_map" />
      </ensemble_element_field_parameter_map>
    </generalized_field_description>
  </field>
</region>

CellML

<boundary
    name = "myoplasm_extracellular_membrane">
  <between>
    <subspace_ref
        href     = "./myoplasm.xml"
        name_ref = "myoplasm" />
    <subspace_ref
        href     = "./extracellular.xml"
        name_ref = "wide_world" />
  </between>
  <uses>
    <mechanism_ref
        name_ref = "HH_gate" />
  </uses>
</boundary>

Figure 4 Some examples of use of the new component re-use mechanism from each of three principle Physiome Languages.

Parameter Passing

This is going to be one of the more interesting parts of our new component re-use scheme and it's still iterating here at Auckland. You may be able to keep track of what we're doing by monitoring the FieldML minutes. Coming soon!

IUPS Physiome Project