CellML Graph Metadata Specification - 01

A specification for metadata describing how to draw graphs.
This version:
http://www.cellml.org/specifications/metadata/graphs/draft-graph-metadata-01
Latest version:
http://www.cellml.org/specifications/metadata/graphs
Previous version:

Authors:
Andrew Miller <ak.miller@auckland.ac.nz> (Bioengineering Institute, University of Auckland)

Abstract

CellML provides a mechanism to describe mathematical models. While CellML can describe the mathematics used by many models published in scientific journals, it does not describe all of the information to create graphs of those models. One step towards this is reproducing experimental results, and this is described in the simulation metadata specification. However, it is also useful to be able to produce the exact graphs from a paper, and this specification allows for metadata which provides the information needed to do this.

Such data fits naturally into a CellML model, as metadata. CellML metadata is expressed in Resource Description Format (RDF). This specification provides an RDF based language for describing graphs. As RDF is an open-world framework, such RDF data may be embedded in a CellML document, or alternatively, could be provided by a third party in a separate document.

Status of this document

This document is a discussion draft version of the CellML simulation metadata specification, and has not been endorsed by the CellML team or members of the CellML community. Comments are solicited and should be sent to cellml-discussion@cellml.org.

Graphical summary of core features (non-normative)


An RDF graph showing the structure of the graph metadata specification

Prefix

The URI http://www.cellml.org/metadata/graphs/1.0# is used as the prefix for all RDF predicates defined in this specification. When describing documents in RDF/XML, it is recommended that the prefix cg be bound to this URI. However, processing software which parses CellML simulation metadata in RDF/XML form must not assume that this prefix will be used.

Within this document, predicate resources are referred to using the notation of qualified names in RDF/XML, and assuming that the cs prefix is bound to "http://www.cellml.org/metadata/graphs/1.0#". For example, cg:graph refers to the resource "http://www.cellml.org/metadata/graphs/1.0#graph".

Within this document, it is assumed that the prefix cmeta is bound to the XML namespace "http://www.cellml.org/metadata/1.0#", and that the prefix cs is bound to the XML namespace "http://www.cellml.org/metadata/simulation/1.0#" However, processing software must not assume that these prefixes will always be used.


Specifications of graphs

As described in the CellML metadata specification, the CellML model is associated with the RDF resource with fragment identifier matching the cmeta:id on the model element and the URI base equal to the CellML document URI.

Every CellML model may have zero or more graphs associated with them. Such graphs are specified by an arc from the model
(subject) to a node (object), with predicate cg:graph. As one model can have more than one simulation associated with it, it is not a contradiction for two or more such arcs to exist. Where CellML processing software discovers more than one such arc, it may display them all, or may prompt the user to select one or more, or it may choose one or more arcs to display arbitrarily.

Throughout this document, the object node of the arc just described is referred to as the "graph node".

Graphs which refer to more than one model may also be defined. In this case, the mechanism by which processing software discovers the graph node is beyond the scope of this specification.

The graph node (and all other nodes reachable from it by arcs defined in this specification) shall be closed-world with respect to predicates defined in this specification — that is, it shall be completely specified within the XML file in which it is defined. If a user wishes to add additional details defined in this specification to a different XML document, they must not attempt to define new arcs with the graph node (or any other nodes reachable from it defined in this specification) as the subject. Instead, they should define a new graph with the additional information. However, it is acceptable for predicates which annotate the graph(perhaps, for example, to comment on the relationship between the graph and reality), rather than define it, to be specified in a different XML file.

A graph is made up of one or more traces superimposed on top of each other on a set of axes. A common numerical scale on each axis is shared by all traces (even if the units are incompatible). The implementing software is free to choose this numerical scale however it likes. Future versions of this specification may allow the metadata to specify a scale for the software to use.

When describing graph nodes in RDF/XML, it is recommended that the node be given an explicit resource URL, rather than using the anonymous node facilities. This makes it easier for other RDF documents to refer to the graph.

Specification of traces

For each graph node, there shall be exactly one arc with subject equal to the graph node, and predicate equal to cg:traces. The object of this node shall be a collection. Each member of the collection shall be a resource. Throughout this document, the members of the collection just described are referred to as the "trace nodes".

Each trace node shall have exactly one arc with subject equal to the trace node, and predicate equal to cg:type. The object of this arc shall be a resource taken from a limited set. This specification defines two resources, cg:line (for a line graph) and cg:scatter (for a scatter plot), which may be used as the object of this arc. Other specifications may add additional resources.

Each trace node shall have exactly one arc with subject equal to the trace node, and predicate equal to cg:colour. The object of this arc shall be a plain literal. The literal shall be formatted as a # character, followed by six hex digits (made up of the character 0-9, A-F, and a-f). The first two hex digits shall specify the red component of the colour of the trace, with the second two specifying the green component, and the final two specifying the blue component.

Each trace node of type cg:scatter shall have exactly one arc with subject equal to the trace node, and predicate equal to cg:glyph. The object of this arc shall be a resource taken from a limited set. This specification defines seven glyphs, cg:dot, cg:square, cg:circle, cg:diamond, cg:plus, cg:triangle, and cg:asterisk. Other specifications may add additional resources.

Each trace node of type cg:line or cg:scatter shall have exactly one arc with subject equal to the trace node, and predicate cg:x-variable, and similarly for the predicate cg:y-variable. The objects of these arcs shall be resources. Such resources shall be referred to as trace variable nodes within this specification.

Each trace variable node shall have exactly one arc with subject equal to the trace variable node, and predicate cs:variable. The object of this arc shall be an RDF resource with fragment identifier matching the cmeta:id on a variable element and the URI base equal to the CellML document URI in which the variable is found.

Each trace variable node shall have exactly one arc with subject equal to the trace variable node, and predicate cg:simulation. The object of this arc shall be a simulation node resource, as defined in the simulation metadata specification.

When describing trace nodes in RDF/XML, it is recommended that the node be given an explicit resource URL, rather than using the anonymous node facilities. This makes it easier for other RDF documents to refer to the trace.

Appendix A: Sample model with graph metadata (non-normative)

Please note: This sample uses RDF/XML in a particular structure. Processing must not assume that the RDF/XML will always be specified in the same way, and must treat alternative inputs which produce the same set of RDF triples in the same fashion.
<?xml version="1.0" encoding="iso-8859-1"?>
<model
    name="CoupledPendulum"
    xmlns="http://www.cellml.org/cellml/1.0#"
    xmlns:cmeta="http://www.cellml.org/metadata/1.0#"
    xmlns:cellml="http://www.cellml.org/cellml/1.0#"
    cmeta:id="CoupledPendulum_version01">
  <rdf:RDF
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:dc="http://purl.org/dc/elements/1.1/"
      xmlns:cmeta="http://www.cellml.org/metadata/1.0#"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:vCard="http://www.w3.org/2001/vcard-rdf/3.0#"
      xmlns:bqs="http://www.cellml.org/bqs/1.0#"
      xmlns:cs="http://www.cellml.org/metadata/simulation/1.0#"
      xmlns:cg="http://www.cellml.org/metadata/graphs/1.0#">
    <rdf:Description rdf:about="">
      <dc:creator rdf:parseType="Resource">
        <vCard:N rdf:parseType="Resource">
          <vCard:Family>Miller</vCard:Family>
          <vCard:Given>Andrew</vCard:Given>
          <vCard:Other>Keith</vCard:Other>
        </vCard:N>
        <vCard:EMAIL rdf:parseType="Resource">
          <rdf:value>ak.miller@auckland.ac.nz</rdf:value>
          <rdf:type rdf:resource="http://imc.org/vCard/3.0#internet" />
        </vCard:EMAIL>
        <vCard:ORG rdf:parseType="Resource">
          <vCard:Orgname>The University of Auckland</vCard:Orgname>
          <vCard:Orgunit>The Bioengineering Institute</vCard:Orgunit>
        </vCard:ORG>
      </dc:creator>
      <dcterms:created rdf:parseType="Resource">
        <dcterms:W3CDTF>2004-12-09</dcterms:W3CDTF>
      </dcterms:created>
      <dcterms:modified rdf:parseType="Resource">
        <dcterms:W3CDTF>2006-11-16</dcterms:W3CDTF>
      </dcterms:modified>
      <dc:publisher>
        The University of Auckland, The Bioengineering Institute
      </dc:publisher>
    </rdf:Description>
    <rdf:Description rdf:about="#CoupledPendulum_version01">
      <dc:title>Coupled Pendulum Model</dc:title>
      <bqs:WebResource rdf:parseType="Resource">
        <bqs:url>http://www.cs.wisc.edu/~hasti/cs310/notes/ODE1/ODE1Notes.html</bqs:url>
      </bqs:WebResource>
      <cs:simulation>
        <rdf:Description rdf:ID="mainsim" cs:simulationName="SwingFor100s">
          <cs:variablesImportantInSimulation rdf:parseType="Collection">
            <rdf:Description rdf:about="#time" />
            <rdf:Description rdf:about="#a_angle" />
            <rdf:Description rdf:about="#b_angle" />
          </cs:variablesImportantInSimulation>
          <cs:boundIntervals rdf:parseType="Collection">
            <rdf:Description>
              <cs:boundVariable><rdf:Description rdf:about="#time" /></cs:boundVariable>
              <cs:maximumStepSize rdf:datatype="http://www.w3.org/2001/XMLSchema#double">1</cs:maximumStepSize>
              <cs:startingValue rdf:datatype="http://www.w3.org/2001/XMLSchema#double">0</cs:startingValue>
              <cs:endingValue rdf:datatype="http://www.w3.org/2001/XMLSchema#double">100</cs:endingValue>
            </rdf:Description>
          </cs:boundIntervals>
        </rdf:Description>
      </cs:simulation>
      <cg:graph>
        <rdf:Description rdf:ID="maingraph">
          <cg:traces rdf:parseType="Collection">
            <rdf:Description rdf:ID="trace1">
              <cg:type rdf:resource="http://www.cellml.org/metadata/graphs/1.0#line"/>
              <cg:colour>#ff0000</cg:colour>
              <cg:x-variable rdf:parseType="Resource">
                <cs:simulation rdf:nodeID="mainsim"/>
                <cg:variable><rdf:Description rdf:about="#time"/></cg:variable>
              </cg:x-variable>
              <cg:y-variable rdf:parseType="Resource">
                <cs:simulation rdf:nodeID="mainsim"/>
                <cg:variable rdf:resource="#a_angle"/>
              </cg:y-variable>
            </rdf:Description>
            <rdf:Description rdf:ID="trace2">
              <cg:type rdf:resource="http://www.cellml.org/metadata/graphs/1.0#scatter"/>
              <cg:colour>#0000ff</cg:colour>
              <cg:glyph rdf:resource="http://www.cellml.org/metadata/graphs/1.0#circle"/>
              <cg:x-variable rdf:parseType="Resource">
                <cs:simulation rdf:nodeID="mainsim"/>
                <cg:variable rdf:resource="#time"/>
              </cg:x-variable>
              <cg:y-variable rdf:parseType="Resource">
                <cs:simulation rdf:nodeID="mainsim"/>
                <cg:variable rdf:resource="#b_angle"/>
              </cg:y-variable>
            </rdf:Description>
          </cg:traces>
        </rdf:Description>
      </cg:graph>
    </rdf:Description>
  </rdf:RDF>
  <units name="rad_per_s">
    <unit units="radian" />
    <unit units="second" exponent="-1" />
  </units>
  <units name="rad2">
    <unit units="radian" exponent="2" />
  </units>
  <component name="environment">
    <variable name="time" public_interface="out" units="second" cmeta:id="time" />
  </component>
  <component name="PendulumUpperSegment">
    <variable name="a" units="radian" public_interface="out" cmeta:id="a_angle" initial_value="1"/>
    <variable name="a_angular_velocity" units="rad_per_s"
              public_interface="out" initial_value="0"/>
    <variable name="time" units="second" public_interface="in"/>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <eq/>
        <apply>
          <diff/>
          <bvar><ci>time</ci></bvar>
          <ci>a</ci>
        </apply>
        <ci>a_angular_velocity</ci>
      </apply>
    </math>
  </component>
  <component name="PendulumLowerSegment">
    <variable name="b" initial_value="1" units="radian" public_interface="out" cmeta:id="b_angle" />
    <variable name="b_angular_velocity" initial_value="0"
              units="rad_per_s" public_interface="out"/>
    <variable name="time" units="second" public_interface="in"/>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <eq/>
        <apply>
          <diff/>
          <bvar><ci>time</ci></bvar>
          <ci>b</ci>
        </apply>
        <ci>b_angular_velocity</ci>
      </apply>
    </math>
  </component>
  <component name="Pendulum">
    <variable name="a" private_interface="in" public_interface="out" units="radian"/>
    <variable name="b" private_interface="in" public_interface="out" units="radian" initial_value="1"/>
    <variable name="a_angular_velocity" private_interface="in" units="rad_per_s"/>
    <variable name="b_angular_velocity" private_interface="in" units="rad_per_s"/>
    <variable name="time" public_interface="in" private_interface="out" units="second"/>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <eq/>
        <apply>
          <diff/>
          <bvar><ci>time</ci></bvar>
          <ci>a_angular_velocity</ci>
        </apply>
        <apply>
          <plus/>
          <apply>
            <times/>
            <cn cellml:units="dimensionless">-2.0</cn>
            <ci>a</ci>
          </apply>
          <ci>b</ci>
        </apply>
      </apply>
      <apply>
        <eq/>
        <apply>
          <diff/>
          <bvar><ci>time</ci></bvar>
          <ci>b_angular_velocity</ci>
        </apply>
        <apply>
          <minus/>
          <apply>
            <times/>
            <cn cellml:units="dimensionless">2.0</cn>
            <ci>a</ci>
          </apply>
          <apply>
            <times/>
            <cn cellml:units="dimensionless">2</cn>
            <ci>b</ci>
          </apply>
        </apply>
      </apply>
    </math>  
  </component>
  <component name="analytic_solution">
    <variable name="a_" units="radian" public_interface="out"/>
    <variable name="b_" units="radian" public_interface="out"/>
    <variable name="time" units="second" public_interface="in"/>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply><eq/>
        <ci>a_</ci>
        <apply><plus/>
          <apply><times/>
            <cn cellml:units="dimensionless">0.5</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 - sqrt(2)) -->
                <cn cellml:units="dimensionless">0.765366864730179</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
          <apply><times/>
            <cn cellml:units="dimensionless">0.25</cn>
            <!-- sqrt(2) -->
            <cn cellml:units="dimensionless">1.41421356237310</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 - sqrt(2)) -->
                <cn cellml:units="dimensionless">0.765366864730179</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
          <apply><times/>
            <cn cellml:units="dimensionless">0.5</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 + sqrt(2)) -->
                <cn cellml:units="dimensionless">1.84775906502257</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
          <apply><times/>
            <cn cellml:units="dimensionless">-0.25</cn>
            <!-- sqrt(2) -->
            <cn cellml:units="dimensionless">1.41421356237310</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 + sqrt(2)) -->
                <cn cellml:units="dimensionless">1.84775906502257</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
        </apply>
      </apply>

      <apply><eq/>
        <ci>b_</ci>
        <apply><plus/>
          <apply><times/>
            <cn cellml:units="dimensionless">0.5</cn>
            <cn cellml:units="dimensionless">1.41421356237310</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 - sqrt(2)) -->
                <cn cellml:units="dimensionless">0.765366864730179</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
          <apply><times/>
            <cn cellml:units="dimensionless">0.5</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 - sqrt(2)) -->
                <cn cellml:units="dimensionless">0.765366864730179</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
          <apply><times/>
            <cn cellml:units="dimensionless">-0.5</cn>
            <!-- sqrt(2) -->
            <cn cellml:units="dimensionless">1.41421356237310</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 + sqrt(2)) -->
                <cn cellml:units="dimensionless">1.84775906502257</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
          <apply><times/>
            <cn cellml:units="dimensionless">0.5</cn>
            <apply><cos/>
              <apply><times/>
                <!-- sqrt(2 + sqrt(2)) -->
                <cn cellml:units="dimensionless">1.84775906502257</cn>
                <ci>time</ci>
              </apply>
            </apply>
          </apply>
        </apply>
      </apply>

    </math>
  </component>
  <component name="errors">
    <variable name="a" public_interface="in" units="radian"/>
    <variable name="a_" public_interface="in" units="radian"/>
    <variable name="b" public_interface="in" units="radian"/>
    <variable name="b_" public_interface="in" units="radian"/>
    <variable name="error_A" units="rad2"/>
    <variable name="error_B" units="rad2"/>
    <variable name="RSS" units="rad2"/>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply><eq/>
        <ci>error_A</ci>
        <apply><power/>
          <apply><minus/>
            <ci>a</ci>
            <ci>a_</ci>
          </apply>
          <cn cellml:units="dimensionless">2</cn>
        </apply>
      </apply>
      <apply><eq/>
        <ci>error_B</ci>
        <apply><power/>
          <apply><minus/>
            <ci>b</ci>
            <ci>b_</ci>
          </apply>
          <cn cellml:units="dimensionless">2</cn>
        </apply>
      </apply>
      <apply><eq/>
        <ci>RSS</ci>
        <apply><plus/>
          <ci>error_A</ci>
          <ci>error_B</ci>
        </apply>
      </apply>
    </math>
  </component>

  <connection>
    <map_components component_1="environment" component_2="Pendulum"/>
    <map_variables variable_1="time" variable_2="time"/>
  </connection>
  <connection>
    <map_components component_1="environment" component_2="analytic_solution"/>
    <map_variables variable_1="time" variable_2="time"/>
  </connection>
  <connection>
    <map_components component_1="Pendulum" component_2="PendulumUpperSegment"/>
    <map_variables variable_1="time" variable_2="time"/>
    <map_variables variable_1="a" variable_2="a"/>
    <map_variables variable_1="a_angular_velocity" variable_2="a_angular_velocity"/>
  </connection>
  <connection>
    <map_components component_1="Pendulum" component_2="PendulumLowerSegment"/>
    <map_variables variable_1="time" variable_2="time"/>
    <map_variables variable_1="b" variable_2="b"/>
    <map_variables variable_1="b_angular_velocity" variable_2="b_angular_velocity"/>
  </connection>
  <connection>
    <map_components component_1="errors" component_2="analytic_solution"/>
    <map_variables variable_1="a_" variable_2="a_"/>
    <map_variables variable_1="b_" variable_2="b_"/>
  </connection>
  <connection>
    <map_components component_1="errors" component_2="Pendulum"/>
    <map_variables variable_1="a" variable_2="a"/>
    <map_variables variable_1="b" variable_2="b"/>
  </connection>
  <group>
    <relationship_ref relationship="encapsulation"/>
    <component_ref component="Pendulum">
      <component_ref component="PendulumUpperSegment"/>
      <component_ref component="PendulumLowerSegment"/>
    </component_ref>
  </group>
</model>