Difference between revisions of "Parameterfile1"

From Linear Mixed Models Toolbox
Jump to navigation Jump to search
 
(20 intermediate revisions by the same user not shown)
Line 4: Line 4:
xml structure used for {{lmt}} in less then half an hour. Please consult the Internet to find
xml structure used for {{lmt}} in less then half an hour. Please consult the Internet to find
suitable introduction into [https://www.w3schools.com/xml/ xml]. Bare in mind that the {{lmt}} parameter file is case sensitive, that is <code>Hello</code> is not the same as <code>hello</code>.
suitable introduction into [https://www.w3schools.com/xml/ xml]. Bare in mind that the {{lmt}} parameter file is case sensitive, that is <code>Hello</code> is not the same as <code>hello</code>.
For writing and editing the {{lmt}} parameter file it is strongly advised to use an editor which supports [https://en.wikipedia.org/wiki/Syntax_highlighting syntax highlighting], [https://en.wikipedia.org/wiki/Bracket_matching bracket matching], [https://en.wikipedia.org/wiki/Code_folding code folding] and [https://en.wikipedia.org/wiki/Autocomplete#In_source_code_editors code completion].


== Unsupported xml features ==
== Unsupported xml features ==


Currently unsupported xml features are [https://www.tutorialspoint.com/xml/xml_character_entities.htm character entities] and complete empty-element tags. Further, [https://www.tutorialspoint.com/xml/xml_tags start tags] and [https://www.tutorialspoint.com/xml/xml_tags end tags] must not occur in the same line of the parameter file.
{{lmt}}'s xml parsing capabilities are geared towards conveying information about linear mixed models, '''not''' to exchange information with other xml supporting software. Therefore, {{lmt}} only supports a particular set of xml features.
 
Currently unsupported xml features are [https://www.tutorialspoint.com/xml/xml_character_entities.htm character entities], [https://www.tutorialspoint.com/xml/xml_namespaces.htm name spaces] and complete empty-element tags. Further, [https://www.tutorialspoint.com/xml/xml_tags start tags] and [https://www.tutorialspoint.com/xml/xml_tags end tags] '''must not occur''' in the same line of the parameter file.


== Parameter file terminology ==
== Parameter file terminology ==


The {{lmt}} parameter file has only two major structural components: [https://www.tutorialspoint.com/xml/xml_tags tags] and key strings. The content of each tag can be another tag or a key string.
The {{lmt}} parameter file has only two major structural components: [https://www.tutorialspoint.com/xml/xml_elements elements] and key strings. The content of each element can be one ore several other elements and one or several key strings.


=== Tag names ===
=== Element names ===


The tag name is the character string between the arrow brackets of a tag. For example, the tag name of {{cc|<hello>}} is {{cc|hello}}. Depending on the specific location and function of a tag the name can be hard-coded or user-defined(u.d.). U.d. tag names can be as short as possible. e.g. a single character, but must not contain any white space. While a tag name my contain any [https://en.wikipedia.org/wiki/ASCII ascii] character it is strongly recommended to use only [https://en.wikipedia.org/wiki/Alphanumeric alpha-numeric] characters and underscores.
An [https://www.tutorialspoint.com/xml/xml_elements element] starts at the [https://www.tutorialspoint.com/xml/xml_tags start tag] and ends at [https://www.tutorialspoint.com/xml/xml_tags end tag] and it's name is the character string between the arrow brackets of the tags. For example, the element name of {{cc|<hello>}} is {{cc|hello}}. Depending on the specific location and function of a element the name can be hard-coded or user-defined(u.d.). U.d. element names can be as short as possible. e.g. a single character, but must not contain any white space. While an element name my contain any [https://en.wikipedia.org/wiki/ASCII ascii] character it is strongly recommended to use only [https://en.wikipedia.org/wiki/Alphanumeric alpha-numeric] characters and underscores.


=== Key strings ===
=== Key strings ===
Line 22: Line 26:
* a single or a comma-separated list of numeric values.
* a single or a comma-separated list of numeric values.


=== Parsing logic ===
== Parsing logic ==


{{lmt}} parse the parameter file starting at the compulsory {{cc|<root>}} tag. Nested tags can be either automatic-compulsory, automatic-optional and nominated. Automatic-optional tags will be searched for by default and are evaluated if they are present. Their absence will not case an error message at parsing time. However, that does not mean that the information they should provide is not necessary later on and it's absence may cause an error stop. Automatic-compulsory tags will be search for by default and their absence will cause an error stop. Nominated tags are always compulsory but are only searched for if they have been nominated by a key string variable, where the key string variable becomes the tag name.
{{lmt}} parse the parameter file starting at the compulsory {{cc|<root>}} element. Nested elements can be either {{cc|automatic-compulsory}}, {{cc|automatic-optional}} or {{cc|nominated}}. {{cc|Automatic-optional}} elements will be searched for by default and are evaluated if they are present. Their absence will not cause an error message at parsing time. However, that does not mean that the information they should provide is not necessary later on and it's absence may cause an error stop. {{cc|Automatic-compulsory}} elements will be searched for by default and their absence will cause an error stop. {{cc|Nominated}} elements are always compulsory but are only searched for if they have been nominated by a key string variable, where the key string variable becomes the element name.


Depending on the host tag key strings can be optional or compulsory.
Depending on the host element key strings can be optional or compulsory.


<syntaxhighlight lang="xml" line>
<syntaxhighlight lang="xml" line>
Line 44: Line 48:
</syntaxhighlight>
</syntaxhighlight>


In the above example nested tags {{cc|<nest_1>}} and {{cc|<nest_2>}} maybe optional or compulsory, but both are automatic, that is {{lmt}} will evaluate them only if the are present. Tag {{cc|<x>}}, nested in tag {{cc|<nest_2>}}, is automatic and may be optional or compulsory as well. However, tags {{cc|<y>}} and {{cc|<z>}} are nominated and therefore compulsory. The nomination is triggered by providing key string {{cc|other: y,z}} where the variable {{cc|y,z}} provides a comma-separated list of names of the nominated tags. That is, after evaluating key string {{cc|others: y,z}} {{lmt}} will search for tags {{cc|<y>}} and {{cc|<z>}}, and their absence will cause an error stop.
In the above example nested elements {{cc|<nest_1>}} and {{cc|<nest_2>}} maybe optional or compulsory, but both are automatic, that is {{lmt}} will evaluate them only if the are present. Element {{cc|<x>}}, nested in element {{cc|<nest_2>}}, is automatic and may be optional or compulsory as well. However, elements {{cc|<y>}} and {{cc|<z>}} are nominated and therefore compulsory. The nomination is triggered by providing key string {{cc|other: y,z}} where the variable {{cc|y,z}} provides a comma-separated list of names of the nominated elements. That is, after evaluating key string {{cc|others: y,z}} {{lmt}} will search for elements {{cc|<y>}} and {{cc|<z>}}, and their absence will cause an error stop.
 
Note that non-sense and wrongly named key strings and elements will '''NOT''' cause an error stop as long as the parameter file content yields a sound description of the task and provides all necessary ingredients. Further, {{cc|automatic-optional}} elements are evaluated even if they are not required for the task. This can lead to an unneccesary high demand for hard-ware resources and a substantially increased processing time. See [[Parameter_file_elements#.3CH.3E|here]] for an example.
 
== Group of mutually exclusive information sources ==


=== Group of mutually exclusive information source ===
For the sake of flexibility the user can supply the same information in several different ways to {{lmt}}. For instance, information can be embedded in an element or provided via a file where a key string variable contains the file name, e.g. {{cc| file: filename}}. In such a case, the key string and the element form a '''Group of mutually exclusive information sources (GIS)'''. The name already implies that {{lmt}} will accept only one source of information and if it finds more than one source will stop with an error message.


For the sake of flexibility the user can supply the same information in several different ways to {{lmt}}. For instance, information can be embedded in a tag for provided via a file where the variable of key string variable contains the file name . In such a case, the key string and the tag form a '''Group of mutually exclusive information sources (GIS)'''. The name already implies that {{lmt}} will accept only one source of information and if it finds more than one source will stop with an error message.
== Escaping element content formatting rules ==
 
As pointed out above [[#Key strings|key strings]] are the only accept element content beside nested elements, and key strings must comply with a formatting rule. However, it is sometimes desirable to supply other information in an element where that information may not comply with the formatting rule. In order to do so the element content can be globally escaped by adding an [https://www.tutorialspoint.com/xml/xml_attributes attribute] to the opening tag. However, this implies that by providing an attribute the whole element content is escaped, not just a single line.
 
For example
<syntaxhighlight lang="xml" line>
<root>
  <nest_1 attribute="eligible_attribute">
    you and me
  </nest_1>
</root>
</syntaxhighlight>
the content of {{cc|nest_1}} does not comply with the formatting rule {{cc|keyword:variable}} as there is a colon missing. However, due to the attribute no error stop will occur.

Latest revision as of 10:08, 4 January 2021

The lmt parameter file must in written in “eXtensible Markeup Language” (xml). For under- standing the examples you may want to get a jump start in xml file structure first. Don’t be scared. Even without any previous knowledge you’ll be able to understand the xml structure used for lmt in less then half an hour. Please consult the Internet to find suitable introduction into xml. Bare in mind that the lmt parameter file is case sensitive, that is Hello is not the same as hello.

For writing and editing the lmt parameter file it is strongly advised to use an editor which supports syntax highlighting, bracket matching, code folding and code completion.

Unsupported xml features

lmt's xml parsing capabilities are geared towards conveying information about linear mixed models, not to exchange information with other xml supporting software. Therefore, lmt only supports a particular set of xml features.

Currently unsupported xml features are character entities, name spaces and complete empty-element tags. Further, start tags and end tags must not occur in the same line of the parameter file.

Parameter file terminology

The lmt parameter file has only two major structural components: elements and key strings. The content of each element can be one ore several other elements and one or several key strings.

Element names

An element starts at the start tag and ends at end tag and it's name is the character string between the arrow brackets of the tags. For example, the element name of <hello> is hello . Depending on the specific location and function of a element the name can be hard-coded or user-defined(u.d.). U.d. element names can be as short as possible. e.g. a single character, but must not contain any white space. While an element name my contain any ascii character it is strongly recommended to use only alpha-numeric characters and underscores.

Key strings

Key strings have always the format keyword:variable . Keyword is a character string which is either hard coded or user defined. The spelling is therefore defined by the hardcoded value, or by the user, but must be abide by in any case. Variable refers to a

  • a single character string, or comma-separated list of strings which may be hardcoded or user-defined, or
  • a single or a comma-separated list of numeric values.

Parsing logic

lmt parse the parameter file starting at the compulsory <root> element. Nested elements can be either automatic-compulsory , automatic-optional or nominated . Automatic-optional elements will be searched for by default and are evaluated if they are present. Their absence will not cause an error message at parsing time. However, that does not mean that the information they should provide is not necessary later on and it's absence may cause an error stop. Automatic-compulsory elements will be searched for by default and their absence will cause an error stop. Nominated elements are always compulsory but are only searched for if they have been nominated by a key string variable, where the key string variable becomes the element name.

Depending on the host element key strings can be optional or compulsory.

<root>
  <nest_1>
  </nest_1>
  <nest_2>
    <x>
    </x>
    others: y,z
    <y>
    </y>
    <z>
    </z>
  </nest_2>
</root>

In the above example nested elements <nest_1> and <nest_2> maybe optional or compulsory, but both are automatic, that is lmt will evaluate them only if the are present. Element <x> , nested in element <nest_2> , is automatic and may be optional or compulsory as well. However, elements <y> and <z> are nominated and therefore compulsory. The nomination is triggered by providing key string other: y,z where the variable y,z provides a comma-separated list of names of the nominated elements. That is, after evaluating key string others: y,z lmt will search for elements <y> and <z> , and their absence will cause an error stop.

Note that non-sense and wrongly named key strings and elements will NOT cause an error stop as long as the parameter file content yields a sound description of the task and provides all necessary ingredients. Further, automatic-optional elements are evaluated even if they are not required for the task. This can lead to an unneccesary high demand for hard-ware resources and a substantially increased processing time. See here for an example.

Group of mutually exclusive information sources

For the sake of flexibility the user can supply the same information in several different ways to lmt. For instance, information can be embedded in an element or provided via a file where a key string variable contains the file name, e.g. file: filename . In such a case, the key string and the element form a Group of mutually exclusive information sources (GIS). The name already implies that lmt will accept only one source of information and if it finds more than one source will stop with an error message.

Escaping element content formatting rules

As pointed out above key strings are the only accept element content beside nested elements, and key strings must comply with a formatting rule. However, it is sometimes desirable to supply other information in an element where that information may not comply with the formatting rule. In order to do so the element content can be globally escaped by adding an attribute to the opening tag. However, this implies that by providing an attribute the whole element content is escaped, not just a single line.

For example

<root>
  <nest_1 attribute="eligible_attribute">
    you and me
  </nest_1>
</root>

the content of nest_1 does not comply with the formatting rule keyword:variable as there is a colon missing. However, due to the attribute no error stop will occur.