CIM = Common Information Model
The ES-DOC eco-system is built upon emerging earth system informatics standards aimed at documenting earth system experiments, models, simulations and other artefacts. The CIM (Common Information Model) is a nascent standard capturing a wide range of information relating to the earth system modelling process. The CIM is now being leveraged by a variety of international model intercomparison projects.
The CIM standard consists of a schema which defines general-purpose document types such as “Machine” and potential specializations of those document types which further refine them by adding or removing or otherwise constraining properties. For example, the CMIP6 document type “Sea Ice” is a specialization of the schema document type “Realm.”
It is expected that the ES-DOC team will govern CIM schemas, while domain experts will govern CIM specializations.
The CIM schema is canonically defined as a set of simple Python classes. Each class defines a set of properties. These properties correspond to the questions that must be answered for each document type. A subset of CIM classes are marked as documents and these can form stand-alone metadata documents which can be created by various ES-DOC tools and published to the ES-DOC Archive, to later be viewed using the ES-DOC Viewer and/or compared against similar documents using the ES-DOC Comparator.
def topic():
"""An organized collection of details upon a specific topic, e.g. model key properties.
"""
return {
'type': 'class',
'base': None,
'is_abstract': False,
'is_document': False,
'properties': [
('citations', 'shared.citation', '0.N',
"Set of pertinent citations."),
('description', 'str', '1.1',
"A description (derived from specialization)."),
('keywords', 'str', '0.N',
"Keywords to help re-use and discovery of this information."),
('overview', 'str', '0.1',
"An overview of topic being described."),
('properties', 'science.topic_property', '0.N',
"Set of associated specialized properties."),
('property_sets', 'science.topic_property_set', '0.N',
"Grouped specialized properties."),
('responsible_parties', 'shared.responsibility', '0.N',
"People or organisations responsible for providing this information."),
('short_name', 'str', '1.1',
"A short-name / key (derived from specialization)."),
('specialization_id', 'str', '1.1',
"Specialization identifier (derived from specialization)."),
('sub_topics', 'science.topic', '0.N',
"Discrete sub-topic with details.")
]
}
Figure 1: The CIM Schema definition of a “scientific topic”
Figure 1 shows the definition of a scientific topic. Notice that each property has a name, a type, a cardinality, and documentation.
CIM specializations are canonically defined as a set of simple Python dictionaries which reference the schema classes and add their own content.
DETAILS['conservation'] = {
'description': "Conservation in the sea ice component",
'properties': [
('description', 'str', '1.1',
"Provide a general description of conservation methodology."),
('properties', 'ENUM:conserved_properties', '1.N',
"Properties conserved in sea ice by the numerical schemes."),
('budget', 'str', '1.1',
"For each conserved property, specify the output variables which close the related budgets."),
('was_flux_correction_used', 'bool', '1.1',
"Does conservation involved flux correction?"),
('corrected_conserved_prognostic_variables', 'str', '1.1',
"List any variables which are conserved by *more* than the numerical scheme alone."),
]
}
Figure 2: A CIM Specialization of a “scientific topic” used by Sea Ice to define “conservation”
Figure 2 shows a specialization of the scientific topic class. Note that it overrides some existing properties (such as “description”) and adds some new properties (such as “budget”). It could re-define properties as well, if the goal was to change a properties documentation or cardinality – making something optional instead of required, for instance.
The CIM in its canonical formats can be translated into various formats including 1) internal Python objects which facilitate the inner workings of the ES-DOC eco-system, 2) UML files for reviewing CIM schema classes, 3) MindMap files for reviewing CIM specialization classes, 4) configuration files for creating CIM documents with the ES-DOC Questionnaire, and 5) template files for creating CIM documents with an IPython notebook.