| | 1 | = Processing the mindmaps (bundled version) to create XML suitable for ingestion by the CMIP5 questionnaire = |
| | 2 | At the telco on the 29th September 2009 it was decided to change the format of the mindmaps to support a (hopefully) improved version of the questionnaire. |
| | 3 | |
| | 4 | === Background === |
| | 5 | Marie-Pierre et al have been keeping two versions of the mindmaps, the original "scientific" mindmaps and a set of "flattened" mindmaps. In the flattened mindmaps component properties have no hierarchy, hence the term flattened. Marie-Pierre has been manually translating from the scientific mindmaps to the flattened mindmaps. The flattened mindmaps are subject to a set of rules which allow them to be translated into an XML format that is more suitable for ingestion by the CMIP5 questionnaire. |
| | 6 | |
| | 7 | It has been proposed that the flattened mindmaps are replaced by a "bundled" mindmap. The bundled mindmaps allow component properties to be grouped together by a label (hence the term bundle). They also allow component properties to be grouped together by a constraint. |
| | 8 | |
| | 9 | The bundled mindmap rules are described below. The associated CMIP5 questionnaire XML rules are documented in ticket 343. |
| | 10 | |
| | 11 | === Rules === |
| | 12 | Golden Rule: Don't create ambiguity where no ambiguity exists by using different names for the same thing. |
| | 13 | |
| | 14 | 1: The mindmaps should be named <name>_bdl.xml where <name> is one of the seven realms. |
| | 15 | |
| | 16 | 2: Controlled Vocabulary (CV) nodes should be to the right on the MindMap (MM). Anything to the left will be ignored. [We can't actually check this, all we can do is check that nodes to the right conform to the rest of the rules defined here] |
| | 17 | |
| | 18 | 3: Specifying work in progress |
| | 19 | |
| | 20 | * A CV node and its children will be checked but not go through to the questionnaire if it includes the yellow triangular warning icon (messagebox_warning). This icon is meant to be used when the node is not yet complete. The xsl stylesheet MMtodo.xsl outputs any "to be completed" nodes. |
| | 21 | * In the development phase there will be a version of the questionnaire that does include the work in progress components (so long as they obey the rules). These nodes will come with a warning. |
| | 22 | * A CV node and its children will be ignored if its text is in an italic font. Eg. enumerations of controlled vocabularies that have not yet been agreed. |
| | 23 | |
| | 24 | 3: All CV nodes that are not covered by rules 2: and 3: must conform to the following visual rules |
| | 25 | |
| | 26 | ||a: component||Bold|| |
| | 27 | ||b: component ref||as a: + red arrow (LINK attribute defined in MM xml)|| |
| | 28 | ||c: leaf parameter||Brown(#996600)|| |
| | 29 | ||d: complex parameter||Purple(#990099) '''NO LONGER ALLOWED ?'''|| |
| | 30 | ||e: common property||Blue(#0033ff)|| |
| | 31 | ||f: common property ref||as e: + red arrow (LINK attribute defined in MM xml)|| |
| | 32 | ||g: value||NodeStyle fork|| |
| | 33 | |
| | 34 | Comment: The mm distinguishes between components based on their position in the hierarchy. A root component is 18pt, a child of a root component is 14pt, any other children are 14pt and Purple(#990099). This information is purely a visual aid and is not required in the questionnaire. |
| | 35 | |
| | 36 | 4: A value may include the pencil icon or the Purple-1 icon. These icons indicate that a keyboard input is required. The pencil icon indicates that a 'string' is to be input. The Purple-1 icon indicates that a 'numerical' value is to be input. In both cases the text is enclosed in square brackets. This text acts as a description rather than being controlled vocabulary. If a value does not include either icon it is assumed to be a controlled vocabulary definition. |
| | 37 | |
| | 38 | 5: If a value node has value node siblings (i.e. more than one value node have the same parent) then it, and all its siblings, must include either the tick icon (button_ok), the cross icon (button_cancel) or the yellow star icon (bookmark). A value node and all its siblings must have the same icon. The tick icon indicates an OR group, the cross icon indicates a XOR group and the yellow star icon indicates an AND group. |
| | 39 | |
| | 40 | 6: Notes: |
| | 41 | |
| | 42 | * a: A controlled vocabulary value node can include a note (pen and book icon) which provides a description of the value. --This is particularly useful for CV lists which contain "other", the note can be used to inform the user of the information we require about the other item-- |
| | 43 | * b: A leaf parameter can include a note (pen and book icon) which provides information about the parameter. |
| | 44 | * c: Notes associated with any other nodes will be ignored. |
| | 45 | |
| | 46 | 7: Hierarchy rules: |
| | 47 | |
| | 48 | * a: There is one mindmap per level 1 parent component and one for the root (level 0) component. (This rule implies that it is not valid to have both atmos and ocean in the same mindmap) |
| | 49 | * b: A component will contain 0 or more components and/or component references. |
| | 50 | * c: A component will contain 0 or more common CV nodes. Common CV nodes may also be children of the central node. In this case they apply to all component nodes. Any common CV nodes may be references. '''Rupert made this up we need to talk about it, we need to come back to this.''' |
| | 51 | * d: Leaf components (components not containing other components) will contain 0 or more parameters. |
| | 52 | * e: Common CV nodes will contain 1 or more parameters. '''hmmmm''' |
| | 53 | * f: complex parameters (a choice based parameter) will contain 1 or more complex parameters and/or parameters '''NO LONGER REQUIRED but we may be able to flatten these using a piece of code if we come up with rules to govern it. ''' |
| | 54 | * g: parameters will contain one or more values (of the same type - see rule 10) '''Oh dear.''' Suggestion that we should have more control over user responses. |
| | 55 | * h: values are atomic, they may not contain any other nodes. [MMCheckValues.xsl] '''(True for atmosphere not true for ocean right now, we may be able to get round this with the flattening rules in point f)''' |
| | 56 | |
| | 57 | 8: Component names must not end in Scheme. |
| | 58 | |
| | 59 | * Avoid component names that end with "Scheme" (eg. TracersLateralAdvectionScheme -> TracerLateralAdvection). To know whether it is a scheme or not rule 9 is sufficient. |
| | 60 | |
| | 61 | 9: If a component describes a parametrization/numerical scheme then it must have a SchemeType parameter (SchemeName is not mandatory as some schemes have no usual name and are only identified by their type). ' |
| | 62 | |
| | 63 | 10: There must be a one to one mapping between a parameter name and the type of numerical value it contains. This is to reduce confusion when we process the questionnaire responses. |
| | 64 | |
| | 65 | 11: the mindmap will interpret the syntax: [name](units) as follows... |
| | 66 | |
| | 67 | * the contents of [] is the name/description of the parameter that appears next to the keyboard input box in the questionnaire |
| | 68 | * the contents of () are the units that correspond to a numerical parameter. |
| | 69 | |
| | 70 | We need a check for this. |
| | 71 | |
| | 72 | Checking and Translating |
| | 73 | |
| | 74 | = BELOW ARE THE OLD FLATTENED MINDMAP RULES FOR POSTERITY = |
