Categories
Lucid Builder Tutorial Lucid Builder v4

Tutorial 1 – Entering Entities and Couplets

Coming soon….

Categories
Lucid Builder v4

Lucid Pathway Key Help

Categories
Lucid Builder v4

Pathway key exports

Lucid Builder supports several export types for pathway key projects. Export options can be accessed via the main menu ‘File…Export…Export Key. Select the preferred export type via the browse dialog when setting the location and filename of the export file.

Each format is described below.

Lucid Phoenix XML

This export option will output all aspects of your key in a simple XML format that is derived from the older standalone pathway key builder Lucid Phoenix, now superseded by Lucid4. The file extension is ‘.lpxk’.

LPXK files have the following format:

<?xml version=”1.0″ encoding=”UTF-8″?>
<PhoenixKey title=”<Key Title>” CreatedIn=”<Software
that created the key
>”>
<Identity id=”<i0..i1.i.n>” name=”<Identity
Name>
” icon=”<path/graphic file>” url=”<path/HTML
file>
” />
<FilterItem name=”<Filter Name>” id=”<f01..f02..fn>“>
    <FilteredItems><Identity Id><space><IdentityId></FilteredItems>
</FilterItem>
<Steps firstStepID = “<Step Id>“>
            <Step
id=”<s0..s1..sn>” text=”<Step Description>“>
                   
<Lead stepid=”<Step Id>” leadid = “<Step
Id><Lead Id l0..l1..ln>
” goto = “<Step Id
or Identity Id>
“>
                       
    <Text><Lead Text></Text>
                   
 </Lead>
    …
</Step>
    …
</Steps>
</PhoenixKey>

CSV (comma separated values)

This format will export your couplet and entity data. It excludes media references and filter data. It’s very similar to the text export, the difference being it doesn’t contain visual formatting and is optimised for importing into applications such as Excel.

Here is an example of the CSV format:

1,”Wings absent”,2
1,”Wings present”,3
2,”Laterally compressed, 1-2 mm long”,Flea
2,”Dorsoventrally flattened, body 10-15 mm long”,Silverfish
3,”Forewings membranous”,4
3,”Forewings completely or partly thickened”,7
4,”Hindwings absent”,Fly
4,”Hindwings present”,5
5,”Wings and body covered with scales”,Moth
5,”Body without scales; if hairy, then wings clear”,6
6,”Antennae very short; wings held at right angles to body”,Dragonfly
6,”Antennae medium to long; wings folded over body”,Wasp
7,”Forewings forming close-fitting hard covers over body”,Beetle
7,”Forewings not completely thickened; some veins obvious”,8
8,”Mouthparts modified into a sucking tube”,Bug
8,”Mouthparts designed for chewing, not tube-like”,Grasshopper

SDD XML (Structured Descriptive Data)

SDD is an open international standard developed several years ago. All aspects of the pathway key data will be exported under this format. Both SDD and the LPXK formats are XML. The SDD format is much more complex as it caters for a larger range of data types. For example Lucid Matrix key projects can also be exported under this format.

For more information on the SDD format see: https://www.tdwg.org/standards/sdd/

Text

The Builder is capable of outputting the key back to a human readable text based key. This format excludes the media and filter data. This format for example could be useful where you want the key published in a paper.

Example text export:

1 “Wings absent” 2
1 “Wings present” 3
2 “Laterally compressed, 1-2 mm long” Flea
2 “Dorsoventrally flattened, body 10-15 mm long” Silverfish
3 “Forewings membranous” 4
3 “Forewings completely or partly thickened” 7
4 “Hindwings absent” Fly
4 “Hindwings present” 5
5 “Wings and body covered with scales” Moth
5 “Body without scales; if hairy, then wings clear” 6
6 “Antennae very short; wings held at right angles to body” Dragonfly
6 “Antennae medium to long; wings folded over body” Wasp
7 “Forewings forming close-fitting hard covers over body” Beetle
7 “Forewings not completely thickened; some veins obvious” 8
8 “Mouthparts modified into a sucking tube” Bug
8 “Mouthparts designed for chewing, not tube-like” Grasshopper

Categories
Lucid Builder v4

Pathway key subsets

Pathway subsets are a unique feature of Lucid pathway keys and are not possible in paper based keys.

In the Lucid Player, Subsets are used to restrict the allowable entities in the key, according to their values in a score matrix associated with the key. For instance, a key to fly families of the World may include a subset that scores each family according to its distribution on the major continents. A user of the key may choose Africa from the filter set. Lucid Player then removes all families that do not occur in Africa from the key and reformats the key’s couplet tree to match the change, effectively producing a new key to the families of flies of Africa.

Unlike matrix (random access) keys, Lucid pathway keys can only have subsets associated with the Entities, not the Leads.

To create a pathway subset click the Subset icon on the main toolbar.

Lucid Builder pathway key main toolbar subset icon
Lucid Builder pathway key main toolbar subset icon

With subsets enabled this will replace the Couplets panel with the Subsets interface. To create a subset, right click within the Subset panel and select  ‘Add…Add Entity Subset’ from the pop-up context menu.

Lucid Builder pathway add subset pop-up context menu
Lucid Builder pathway add subset pop-up context menu

Next, enter your preferred Subset label. This label is what the end user of the key will see, so it should be descriptive enough to convey its purpose.

Lucid Builder pathway subset entry example
Lucid Builder pathway subset entry example

Once at least one subset has been added, scoring of the subset can occur. To enable subset scoring click the subset score toggle button on the right hand toolbar below the main key score button.

Lucid Builder pathway subset score button
Lucid Builder pathway subset score button

With subset score mode enabled an empty diamond icon will appear to the left of the entity labels.

Lucid Builder pathway subset scoring mode score diamonds
Lucid Builder pathway subset scoring mode score diamonds

Click the diamond icon to “score” or add the entity into the selected subset. Click it again to “un-score” or remove the entity from the subset.

Lucid Builder pathway subset scoring example
Lucid Builder pathway subset scoring example

To turn off subset scoring mode click the subset score button again. To return to couplet editing click the Subset icon on the main toolbar.

Categories
Lucid Builder v4

Pathway key options

The Builder has a number of settings for how a pathway key looks and operates in the Lucid Player. To adjust these options open the Key Options dialog via the main menu ‘Key…Key Options’.

Lucid Builder pathway key options dialog - Display options
Lucid Builder pathway key options dialog – Display options

Display Options

Question/Lead  Thumbnails – If selected, any thumbnails associated with the Questions and leads will be displayed within the Lucid Player. Note the user of the key will still have the option of toggling thumbnails on or off to suit their preference.

Entity Thumbnails – If selected, any thumbnails associated with the Entities will be displayed within the Lucid Player. Note the user of the key will still have the option of toggling thumbnails on or off to suit their preference.

Language

Locale – Allows the selection of a custom language file that should be loaded for the Lucid Player.

Media Options

Lucid Builder pathway key options dialog – Media options

Media options determine the default settings for media when added to the key via the Builder.

Thumbnails

Max. Dimension (px)

The maximum height and/or width the thumbnail will be created to. See the ‘Aspect Fit’ option below for additional details that effect the thumbnail creation.

Aspect Fit

If checked (default), then the thumbnail will be created keeping its aspect ratio within the maximum dimension set. This stops the thumbnail from being distorted when fitting (size) to the maximum dimension.

Lucid Builder Thumbnail Aspect Fit example
Lucid Builder Thumbnail Aspect Fit example.

Media Panel

Display Image Thumbnails

If checked, thumbnail images, rather than the filename will be displayed within the Builder’s Media Panel.

Defaults

Image Caption

The Image Caption allows you to set a default caption for images. The default caption will be applied within the Media Panel caption text box when the image is first attached. You can override the default caption by replacing it with your preferred caption text.

Image Copyright

The Image Copyright option allows you to set a default copyright label to images. You can override the default copyright label by replacing it with your preferred copyright  text within the Media Panel.

HTML Caption

The HTML Caption allows you to set a default caption for HTML pages attached to the key. The default HTML caption text will be applied within the Media Panel caption text box when the HTML file is first attached. You can override the default caption by replacing it with your preferred caption text.

Item Name as Caption

If the Item Name as Caption is checked then the default caption for an attached image or HTML file will be the label text of the selected item (e.g. Question, Lead or Entity). You can override the default caption by replacing it with your preferred caption text within the Media Panel.

Categories
Lucid Builder v4

Importing existing pathway keys

The Lucid Builder contains am import facility that can convert existing paper based keys into the Builder pathway format. The import function can handle the two most common types of printed dichotomous keys, bracketed and indented. If your dichotomous key is only available in a printed format, scan the key using an Optical Character Recognition (OCR) program and save the key as a text file. 

The import option is only available to use on a new empty key as import merging is not yet supported.

To import an existing key, start a new pathway key (save it) and  then select ‘Import Key’ from the main menu ‘File…Import’ option. Browse to and select the desired key file to import. Once selected the pathway import editor will load file.

Lucid Builder pathway key import dialog example showing an error within the key
Lucid Builder pathway key import dialog example showing an error within the key

Once a key has been loaded into the Pathway Editor it is analysed. If problems are found within the key, a ‘To Do’ list is generated. Each error or warning found within the key is marked with a wavy underline, red for an error and blue for a warning, at the point within the line where the error occurs (see example above).

Each couplet item must be on one line.

Each couplet item must have an identifier, question text and a destination. The second item within a couplet does not need an identifier as this can be assumed from the couplet item immediately above it.

Breakdown of a bracketed key example
Breakdown of a bracketed key example

The importer will change the colour of the text that represents each part of the couplet item that has been identified. Between each component of the couplet item – identifier, question text and destination – there must be some form of separation. The separation can be in the form of spaces, tabs or three or more repeating characters. These separators are excluded when the text key is imported to the Builder.

As errors or ‘To Do’ items are corrected within the key document window the key is re-analysed to find other errors that were hidden by previous errors. Each item within the ‘To Do’ list has a line number where the fault can be found within the document window. ‘To Do’ items can be clicked, this action takes the cursor to the line and position where the error is occurring within the key document window. Once all ‘To Do’ items have been resolved the key can then be imported back to the  Builder using the Import key option as shown below.

Lucid Builder pathway key import dialog with no errors ready for import to the Builder.

Key importer toolbar

Pathway key importer dialog toolbar
Pathway key importer dialog toolbar
Categories
Lucid Builder v4

Associating entities with leads (scoring your pathway key)

In a completed pathway key, every lead will either lead to another lead, or to an entity. No lead will lead nowhere, and no lead will lead to two or more entities.

To begin associating entities with leads place the Builder into score mode by clicking on the score toggle button.

Pathway key score mode toggle button
Pathway key score mode toggle button

When score mode is enabled, four entity window options will appear.

Lucid Builder pathway key score mode example
Lucid Builder pathway key score mode example

Assigning entities to leads can be done at any stage of the keys development. That is you don’t need to wait until you have completed the entire pathway.

Entities that haven’t yet been assigned to a lead will appear in the ‘Unassigned Entities’ list. To assign an entity, simply click it, then drag and drop it to the selected couplet lead entity list (top score list).  More than one entity can be selected and moved at once. Use the Ctrl (individual selection) or the Shift key (contiguous selection) to make your entity selections, then drag and drop to the selected couplet lead entity list. 

Assigned entities for either the selected lead or other lead(s) can be unassigned by selecting them, then drag and dropping them back to the Unassigned Entities list. It is also possible to move entities from the selected lead to the other lead(s) list and vice versa.

There is no need to score entities to every lead in the pathway, you can simply assign the entities to end leads, if preferred. Or to a preferred lead in the pathway as the key develops.

The key does not need to be completely scored before you can try it out in the player. In the event where the key has unassigned entities, these will be excluded from the key when played. When playing the key, and couplet leads that do not have any assigned entities will be shown in the Entity lists (Entities Remaining or Entities Discarded) as “INCOMPLETE KEY – ‘<lead text>‘ “. Entities should be assigned to these leads for your key to be considered complete.

Categories
Lucid Builder v4

Building and managing the couplet tree

The Couplet Tree is the core of a pathway key. It comprises couplets arranged in a tree, each couplet with two or more leads. Couplets and leads can be added, moved, removed or renamed at any time.

To begin creating a couplet, first right click in the Couplet window and select ‘Add’ from the pop-up context menu.

Add a new couplet lead pop-up context menu
Add a new couplet lead pop-up context menu

Edit the text of the lead and/or the couplet question

In a key using the question-answer form for couplets, use the couplet questions for the question text and the couplet leads for the answer text; in a key using the coupleted statement form, ignore the couplet question and use the couplet leads for the statements.

Lucid Builder pathway couplet tree diagram
Lucid Builder pathway couplet tree diagram

Moving questions or leads

The Lucid Builder has in-built rules for rearranging leads that will help you maintain a logical key structure. 

Move a question or lead by selecting the element and dragging it to the desired position. The Builder will prevent the element from being dropped to an illogical place. Depending on where the element is drop the builder will confirm the intended position.

Dragging a lead on to another lead within the same question will reorder its position.

Renaming

To rename an element within the couplet tree right click on it and select the rename option from the pop-up context menu. Or use the keyboard shortcut (F2). Once you have edited the text of the element press the enter key to confirm the change.

Deleting

To delete a question or lead either right click on it and select the delete option within the pop-up context menu. Or simply press delete key on your keyboard. The Builder will ask to confirm the deletion. 

Care should be taken when deleting. If the element being delete contains child elements then all the underlying elements will also be deleted.

If you make a mistake deleting an element use the undo function (Ctrl + z) to restore the deleted element(s).

Filtering couplets

If your pathway key isn’t using the Couplet Question nodes you can hide these by using the couplet filter option. Right click within the Couplet area and select ‘Filter…Filter Couplets’ from the pop-up context menu.

Categories
Lucid Builder v4

Starting a new pathway key

To start a new pathway key project, select the new key option, via the toolbar (first icon) or via the File…New menu option. The sub menu allows the selection of either key type.

A key type selector dialog will be presented, if the toolbar new key option or keyboard shortcut is used.

Lucid Builder key type selector dialog

Select the ‘Pathway Key’ option to proceed. The Builder will then modify its interface ready for pathway key construction.

Building and managing the couplet tree

Importing a pathway key

Categories
Lucid Builder v4

Dichotomous (pathway) key construction

Lucid v4 now supports the creation, deployment, maintenance and playing of interactive pathway keys (also often called dichotomous keys). Pathway keys are one of two main types of identification keys. The other type, matrix keys (also often called interactive or random-access keys) are also supported by Lucid.

A pathway key is a traditional form of identification guide that takes the form of a series of questions or statements, each question or statement leading to either another question or statement, or to a result (an identified taxon or entity). Pathway keys are so named because the questions or statements are arranged in the form of a branching pathway, each branch ultimately leading to an identification. At each branching point a question with two or more answers, or two or more statements, are presented. The answer or statement that best describes the entity (taxon or other thing) being identified is chosen at each step.

There are several traditional ways of writing pathway keys, but all have the same basic structure.

An example of a simple couplet statement key.

Statements are written in groups (couplets), each with a go-to. Choose which statement of the couplet is correct for the specimen to be identified, then go to the couplet number indicated.

1.   Flowers blue……………………………2
1a. Flowers red…………………………….3

2.   Fruits fleshy………………..Species 1
2a. Fruits woody……………….Species 2

3.   Trees…………………………..Species 3
3a. Shrubs……………………………………4

4.   Leaves hairy………………..Species 4
4a. Leaves not hairy………….Species 5

The same key written as a simple indented statement key

Statements in a group (couplets) have the same indent level. Choose which statement of the couplet is correct for the specimen to be identified, then go to the couplet immediately below

Flowers blue
    Fruits fleshy…………………..Species 1
    Fruits woody………………….Species 2
Flowers red
    Trees…………………………….Species 3
    Shrubs
      Leaves hairy………………..Species 4
      Leaves not hairy…………..Species 5

The same key written as a branching tree with questions and answers

Begin at the top of the key with the first question, choose which answer is correct for the specimen to be identified, then follow the arrow to the next question.

Pathway key written as a branching tree
Pathway key written as a branching tree.