Applies to Matrix key projects
The Lucid Builder can be used to produce natural language descriptions of the Entities in the key, as well as descriptive tables and listings of Features.
Natural language is handled using the Descriptions panel, accessed by clicking on its tab located on the left hand side of the Builder window.
The Descriptions panel has four sections:
Wording Section is used to specify the wording of features and states to be used when generating natural language descriptions.
Score Modifiers are used to enter text modifiers for scores, to be inserted before or after the appropriate score string in the natural language description.
Description displays a chunk of a natural language description, relevant to the currently selected feature.
Export is used to export full natural language descriptions to an output file, and to transform the output using predefined template files.
The following topics describe the operations of each element of the Descriptions panel in more detail.
Specifying wording to be used in Natural Language Descriptions
It will often be the case that the best wording for a feature or state in the context of the list of features and states in the key is not the best wording in the context of a natural language description. For example, a key to fungi may have the following feature:
It is clear from the context of the feature Translucent striations that it refers to the margin of the pileus. However, a description string for this feature would read:
“Translucent striations absent”
This may be adequate in some circumstances, but not in others. The Wording panel allows you to modify this description string so it would read instead:
“Pileus margin not translucent-striate”
To do this, select the state absent, and set the wording for the feature and state as follows:
How it works: the wording “Pileus margin” is used for the description of this feature in place
of “Translucent striations”; the wording “not translucent-striate” is used in place of “absent”.
Similarly, setting the wording for the state “present” to “translucent-striate” will result in a description string (for an entity scored as present) that reads “Pileus margin translucent-striate”.
Note
The Description panel displays only a short string from a description, for the current feature. The wordings set using the Wordings panel will affect both short single-feature descriptions and full-length descriptions.
Modifying a score using text modifiers
Sometimes it is useful to modify an individual score in a natural language description. Lucid already supports two important modifiers – rare and misinterpreted – in its scoring, and these are handled in descriptions automatically. For example, the following scoring for an entity will produce the accompanying description.
How it works: the wording “Pileus overall shape” is used for the description of this feature in place of “Overall shape”. Since the state “cylindrical to parabolic” is scored using the “By Misinterpretation score”, the string “by misinterpretation” in parentheses is added after the score; since the state “infundibuliform” is scores using the Rarely Present score, the string “rarely” in parentheses is added after the score.
If other modifiers are needed in a description, use the Modifiers panel on the Descriptions tab. A modifier can be inserted before or after the state string in the description. For example, the following scoring and modifiers will produce the accompanying description.
How it works: the wording “Pileus” is used for the description of this feature in place of “Translucent striations”; the wording “translucent-striate” is used for the state instead of “present”. The modifier “obscurely” is inserted before “translucent-striate”, and the modifier “on the very margin” is inserted after.
Note
The Score Modifiers edit boxes are unavailable unless the key is in score mode.
How it works: the wording “Pileus” is used for the description of this feature in place of “Translucent striations”; the wording “not translucent striate” is used for the state “absent”, while the wording “translucent striate” is used for the state of “present; since Ignore score in description is checked for the state “Absent”, the feature description is “Pileus translucent-striate” instead of “Pileus not translucent-striate (by misinterpretation) or translucent-striate”.
Text Features
New to version 4, a Text Feature is a special Feature that is used to help generate descriptions, rather than being output as a part of the identification or diagnostic key.
A Text Feature is indicated by the icon. The Text Feature can be treated in the same way as a regular Feature as far as the Description property options. The main difference is scoring of a Text Feature. A Text Feature is only treated as Present or Absent with or without a Text Score. When applying a score (using any score type option) present is indicated by a text value. While no text present as the score value indicates absent. Below shows an example of a Text Score value.
Tip
While the Text Feature was designed primarily for use in generating descriptions, it could be applied to a multitude of other uses where you want to store text values against Entities or Specimens. E.g. Notes, catalogue numbers etc.
Exporting Natural Language Descriptions
The following diagram shows the process of description creation in Lucid:
Exporting xml output files without an Output Template or Transform File
On the Descriptions Panel, click the Export button. An export dialog will appear, select or enter the name of a new Output File. Once the Output File has been defined click dialogs save button. Next, select to either export just the selected Entities or descriptions for all Entities within the key.Note
When creating an Output File an ‘.xml’ file extension will be automatically added, if not entered.
Once the export has been completed the description result will be displayed in the Lucid browser window. Or for non-Windows users your preferred web browser.
How this works
When no Output Template has been defined Lucid will automatically build one. The automatically generated Output Template will include all features within the key and is based on the author entered Feature/State tree. The Builder then applies the default ‘Sentence’ Transform File to produce the descriptive result. As you may notice the automatic description is unlikely to be an optimised written description, though this does depend on the keys features and/or the amount of customisation done within the Wording properties of the description panel. To build truly optimised descriptive text you should define an Output Template via the Template Editor and select or customise your preferred Transform File.
Tip
The output file is not designed to be a “human readable” description, rather think of it as a data file. However if you wish to view this file it can be opened using programs such as XMLSpy or your preferred text editor.
Exporting html files using Transform Files
Using a Transform file in the description generation process allows you to format the presentation of the description in just about any way you can image. The Transform file uses an open W3C defined transformation language called Extensible Stylesheet Language (XSL).
For more information on XSL please see: https://en.wikipedia.org/wiki/Extensible_Stylesheet_Language
We have provided several default example Transform files we feel would be useful when generating descriptions. They are:
The Sentence transform, creates each description comprising a single paragraph. This is the default template when no other template is defined.
The Sentence-Media, identical to the above Sentence transform but includes images in the description. The images are sourced from the images attached to the keys Entities.
The Paragraph transform, creates a description with each feature in a separate paragraph. Grouping features provide headings to sets of paragraphs.
The Paragraph-Sentence transform, creates a description with groups of features in separate paragraphs, with features within the group joined into sentences.
The Paragraph-Sentence-Media, identical to the Paragraph-Sentence transform above but includes images within the description. The images are sourced from the images attached to the key’s Entities.
The Table transform creates a tabular description, with rows for each entity and columns comprising grouping features as headers.
To create descriptions with a preferred Transform Template File, but without defining an Output Template, select your preferred Transform Template via the Description settings within the Key Options dialog, accessible via the Key menu. After saving the Description options return to the Description panel and click the Export button. Select or enter the name of a new Output File. Export either the selected entities or all entities. The description file will be created in the same folder where the Output File was defined and will be named the same except the file extension will be ‘.html’ rather than the Output Files ‘.xml’ extension. After the export has taken place Lucid will offer to open the description file in your preferred web browser.
Tip
The supplied Transform Template files can be found in the Lucid install folder under the following sub folders:
<Lucid Install Folder>\resource\transform\
Transform Template files have a ‘.xsl’ file extension.
Note
Subfolders within the transform folder contain additional supporting files associated with the Transform Template file such as CSS files, JavaScript’s and additional page graphics. Lucid will automatically copy the supporting folder needed for the export destination. The supporting folder name must be the same as the Transform Template file for this to occur.
Using Output Templates to customise descriptions
An Output Template is an XML file that provides customisation options for descriptions. Using an Output Template allows features to be included or excluded from descriptions, rearranged, grouped into sentences, paragraphs and table columns, and formatted using italics, bold etc.
Since Lucid 3.5 we have included an Output Template Editor that allows the easy creation of Output Templates, which previously had to be built “by hand” in version 3.4.
The Output Template Editor
To access the Output Template Editor click the Edit button within the Descriptions panel.
If no Output Template has been associated with the key previously then the Output Template Editor will offer to automatically build a default template based on the current open keys structure. An automatically generated template will reflect the current feature tree as closely as possible within the Feature Group, Feature and Feature Item structure of the editor.
Template Editor Features
Menus
File Menu
New Template (Ctrl+n /⌘+n)
Creates a new empty template. Prior to a new template being created, if an existing template is in use, you will be asked to save and close the current template or cancel the creation of the new template.
Open (Ctrl +n/ ⌘+n)
Opens an existing template file from the folder system.
Note
Template file extensions are ‘.xml’.
Save (Ctrl+s/ ⌘+s)
Saves the current open template. If the template is new and has not been saved before then the Save function will ask you to select a folder and filename for the template. Otherwise the save function will save to the current template file, overwriting any previous data.
Tip
To avoid confusion with other XML files we suggest that you adopt a naming convention such as:
<keyname>_template_v<variant number, date, or note>.xml
E.g. ‘Key to fungi_template_v22082009.xml’
Save As
Saves the current template in use but allows you to specify a new filename and location for the template. If you select to save over an existing template file a warning dialog will be displayed and confirmation asked before this action is performed.
Preview (ctrl+p/ ⌘+p)
The preview function will take the current template, key data, generate an Output file, and then apply a Transform file. The Sentence Transform is applied by default, if none is selected. It then creates a description for preview. This preview file will then be loaded into the Lucid Browser window: for OSX and Linux users this will be your default web browser.
Before rendering the preview the option to either view descriptions for all Entities or for only those currently selected within the Builder will be given.
The Output file and Description Preview file will be created in the same folder as the template file and will use the same name. The addition of ‘_preview’ is added to the Description Preview Filename. As the preview file is HTML based the file will have ‘.html’ file extension, while the Output file will have an ‘.xml’ file extension.
Tip
You can quickly switch Transformation files via the dropdown box located on the Template Editor Tool bar.
Exit
Closes the Template Editor window. If required, the ‘Save/Save As’ function will be offered on exit.
Edit Menu
Cut (ctrl+x/ ⌘+x)
The cut operation allows either a Feature Group, Feature, Feature Item or text elements to be cut from the Description Template. The cut item is then available within the Paste clipboard. See the Paste function for further details on pasting cut or copied items.
Copy (ctrl+c/ ⌘+c)
The copy operation allows the copying of various element types within the Template Editor such as Feature Group, Feature, Feature Item or text element. The copied item then becomes available to the Paste Clipboard. See the Paste function for further details on pasting cut or copied items.
Paste (ctrl+v/ ⌘+v)
The Paste operation takes the current item from the Paste clipboard and transfers it to the selected location within the Template Editor. Depending on what has been cut or copied causes the template editor to enforce rules on the Paste operation that prevent illogical operations from occurring. For instance, the Paste option will become unavailable if you copied a Feature Item and tried to paste it at the same level as a Feature group.
Delete (Delete key)
The Delete operation will remove a selected item from the Description Template tree or in text boxes found in the Description property area. The delete option will only become available where it is valid to delete a selected item.
Tip
Care should be taken when using the Delete operation particularly when deleting higher level nodes within the Description Template tree, as all sub nodes will be deleted along with the parent node. No warning is currently given post the delete option being selected, nor is there an undo feature available with the delete operation.
Generate (ctrl+g/ ⌘+g)
The generate operation will automatically create a template based on the current key structure. An automatically generated template will reflect the current key’s Feature tree as closely as possible within the Feature Group, Feature, Feature Item structure of the editor. This automatically generated template can then be further developed and customised, if desired. See Manually Building a Template for further information on this.
Preferences
The Preferences option opens the Description Options dialog. These same preference options can be also set via the Key Options..Descriptions tab found in the Builder. The two description settings allow you to set a default Output template and Transform file for the key. Once set, these defaults will be used when the key is opened. This removes the need for the Output Template and Transform File to be reselected each time you wish to generate your descriptions.
Template Editor Tool Bar
New Template (Ctrl+n /⌘+n)
Creates a new empty template. Prior to a new template being created, if an existing template is in use, you will be asked to save and close the template or cancel the creation of the new template.
Open Template (ctrl +n/ ⌘+n)
Opens an existing template file from the folder system. Template file extensions are ‘.xml’.
Save Template (ctrl+s/ ⌘+s)
Saves the current open template. If the template is new and has not been saved before then the Save function will ask you to select a folder and filename for the template. Otherwise the save function will save to the current template file, overwriting any previous data.
Tip
To avoid confusion with other XML files we suggest that you adopt a naming convention such as:
<keyname>_template_v<variant number, date, or note>.xml
E.g. ‘Key to fungi_template_v22082009.xml’
Expand Template Tree
This function will expand all nodes within the Template tree.
Collapse Template Tree
This function will collapse all nodes within the Template tree to the Feature Group level.
Transformation Template Selection Dropdown
This dropdown box allows the quick selection of available transformation templates. Available Transform Templates are located in the \resource\transform\ folder.
Preview Template
The Preview Template button (Green arrow) generates a preview copy of the description and automatically opens the description within the Lucid Browser window (Window’s Users), or within your default web browser (OSX & Linux users). Selecting to preview your description will trigger the save function if the template has been modified since the last save operation. Additionally an option will be offered to preview the selected entity or entities within the key or to preview the descriptions for all entities.
Help
Opens this help file describing the Template Editor functions.
Manually Building a Template
While the Template Builder’s automatic generation of a Template is quick and convenient, there will be times where it is desirable to manually build a Template or adjust an automatically generated one.
To start the process of constructing a Template right click on the default “Description Template” root node. A context pop-up menu will appear.
Note
This pop-up menu options will change depending on the type of node selected during the building process.
From the ‘Description Template’ root node the only option available from the pop-up menu is to add a Feature Group node. Select this option. A new node will be added below the ‘Description Template’ node called ‘undefined’.
Tip
Undefined nodes will appear in a light grey colour to show their status of having no defined name label.
Select the newly created ‘undefined’ Feature Group node. The Option panel on the right will allow you to enter a name for the Feature Group. E.g. Cap.
Tip
F2 can be used to rename a selected tree node.
Additional options can be set on the Feature Group node. See Template Editor Options Panel – Feature Group Selection for information on these.
Next, right click on the Feature Group node. The context pop-up menu will appear again, though this time it will contain more options
In particular, to either add another Feature Group node or to add a Feature. In this instance select to add a Feature. A new node below the Feature Group node will appear. It also will be called ‘undefined’ by default.
Note
Features can only be created under a Feature Group node.
Select the undefined Feature node. The option panel to the right will then update to reflect the options available for the Feature node type. Enter a name for the Feature. E.g. shape.
Additional options can be set on the Feature node. See Template Editor Options Panel – Feature Selection for information on these.
Next, we need to add a Feature Item. Feature Items provide the mapping back to the desired Feature within the key. It is this mapped key’s scored Feature States for a given Entity that is used to build the description text. Mapping the Feature Item to the desired keys Feature can be done in two ways;
- Right click on the Feature Item, from the pop-up menu select the ‘Select Feature’ option.
- From the Options panel click within the Path text box.
Note
Only Features can be selected within the selected Feature Path dialog. Grouping Features and States cannot be selected. Once a valid Feature has been selected the OK button within the Select Feature Path dialog will become available.
To remove the Feature path mapping select the Feature, click on the Path label within the properties section. This will load the Select Feature Path dialog. Select the Clear button. This will remove the current Feature mapping. An empty Path label in the properties panel indicates no Feature mapping.
Organising the Description Template Tree
The order of Features Groups and Features within the Description template is important as this order is reflected in the description text that is generated.
Nodes within the Template Editor can be reorganised in a similar way Features can be in the Builders’ Feature tree. Nodes can be reordered and moved about by drag and drop with the mouse or through cut, copy and paste functions. The Template Editor enforces a set of rules when reordering and moving nodes to avoid mistakes during these operations.
For example, Feature Groups are enforced at the highest level within the template tree. You cannot have Feature Groups within Feature Groups. Features can only exist under a Feature Group. Feature Items can only exist under a Feature. Based on these simple rules you can move or copy Features to other Feature groups, or move or copy Feature Items to other Features.
To reorder a nodes position within its hierarchical level use the ctrl key while performing the drag and drop operation.
Note
The ctrl key is not needed when moving a node.
Template Editor Options Panel
The Template Editor Option panel allows you to adjust a number of parameters that effect the output of the description text. The options presented can change depending on the selection within the Description Template tree. Each of these options are outlined below.
Description Template – Selection of the root node
Options
Ignore Uncertains
Checking this option will remove all Features from the description where they have been scored as uncertain.
Ignore Misinterpretations
Checking this option will remove all Features from the description where they have been scored as either “Common and Misinterpreted” or “Rare and Misinterpreted”.
Feature Group Selection
Name
The Name textbox allows you to change the Feature Group label text. The Feature Group label forms part of the description text, unless it is turned off (see Use Name in Description below).
Use Name in Description
Checking this option will remove the Feature Group text label from the description.
Format
Allows simple formatting options to be applied to the Feature Group label such as bold, italics and underline.
Options – Ignore Uncertains
Checking this option will remove the Feature Group label and all children items from the description where the entity was scored as uncertain for the Feature Group.
Tip
To remove all uncertain features completely from a description select the Description Template root note and select this option.
Options – Ignore Misinterpretations
Checking this option will remove the Feature Group label and all children items from the description where the entity has been scored as either “Common and Misinterpreted” or “Rare and Misinterpreted”.
Tip: To remove all misinterpreted features completely from a description select the Description Template root note and select this option.
Leading Text
Text
Additional text can be added to the description prior to the Feature label.
For example, without leading text the description would be written:
<Feature Group Name text> <Feature Name text>
With leading text it would be:
<Feature Group Name text> <Leading Text> <Feature Name text>
Format
Allows simple formatting options to be applied to the Leading Text label such as bold, italics and underline.
Trailing Text
Text
Additional text can be appended to the Feature label text within the description.
For example, without trailing text the description would be written:
<Feature Group Name text> <Feature Name text>
With trailing text it would be:
<Feature Group Name text> <Feature Name text> <Trailing Text>
Format
Allows simple formatting options to be applied to the Trailing Text label such as bold, italics, underline.
Feature Selection
Name
The Name textbox allows you to change the Feature label text. The Feature label forms part of the description text, unless it is turned off (see Use Name in Description below).
Use Name in Description
Checking this option will remove the Feature text label from the description.
Format
Allows simple formatting options to be applied to the Feature label such as bold, italics and underline.
Prefix
When a Feature Group has multiple Features each Feature within the description will be separated with a comma by default. The Prefix option allows you to override this separator.
Note
A prefix only starts to be applied on the second Feature within the Feature Group. A Prefix defined on the first Feature within the Feature group will be ignored.
An example without a defined Prefix the description output would look like:
<Feature Group Name text> <Feature Name text> <Feature Item text>, {Prefix – Comma by default} <Feature Name text> <Feature Item text>, {Prefix – Comma by default} …
With a Prefix defined as a semi-colon (;) the description output would look like:
<Feature Group Name text> <Feature Name text> <Feature Item text>; <Feature Name text> <Feature Item text>; …
Tip
If you need to include a space prior to the prefix you can use the HTML code for a space “ ”. For example, to include a space prior to a dash (-) prefix:
-
A space will be automatically included post the prefix.
Options – Ignore Uncertains
Checking this option will remove the Feature from the description where the entity was scored as uncertain for the Feature.
Tip
To remove all uncertain features completely from a description select the Description Template root note and select this option.
Options – Ignore Misinterpretations
Checking this option will remove the Feature from the description where the entity has been scored as either “Common and Misinterpreted” or “Rare and Misinterpreted”.
Tip
To remove all misinterpreted features completely from a description select the Description Template root note and select this option.
Leading Text
Text
Additional text can be added to the description prior to the Feature text.
For example, without leading text the description would be written:
<Feature Group Name text> <Feature Name text> <Feature State(s) text>
With leading text it would be:
<Feature Group Name text> <Feature Name text> <Leading Text> <Feature State(s) text>
Format
Allows simple formatting options to be applied to the Leading Text label such as bold, italics and underline.
Trailing Text
Text
Additional text can be appended to the Feature text within the description.
For example, without trailing text the description would be written:
<Feature Group Name text> <Feature Name text> <Feature State(s) text>
With trailing text it would be:
<Feature Group Name text> <Feature Name text> <Feature State(s) text> <Trailing Text>
Format
Allows simple formatting options to be applied to the Trailing Text label such as bold, italics and underline.
Feature Item Selection
Path
The Path is the mapping location to the Feature within the key. Clicking on the path text within the options panel will open the Feature Path Selection dialog, which will allow you to map to a feature within the key. The scored state(s) of this Feature will be output in the description.
Format
Allows simple formatting options to be applied to the Feature state text label such as bold, italics and underline.
Conjunction
Where multiple States of a Feature have been scored the state text will be joined by a comma the conjunction between the second last and last state is where the conjunction is applied. The default conjunction is “or”.
For example using the default “Or” option,
<Feature Group Name text> <Feature Name text> <Feature State>, <Feature State> or <Feature State>.
Using the “And” conjunction would give:
<Feature Group Name text> <Feature Name text> <Feature State>, <Feature State> and <Feature State>.