DKey

DKey
About DKey
DKey software is an editor of dichotomous taxonomic keys. It can be used by taxonomic experts to create keys or by users of printed keys to make them more user friendly. DKey is a free alternative to Lucid Phoenix.

Main features of DKey

  • importing existing keys in text format
  • combining keys
  • moving couplets
  • copying couplets
  • removing couplets
  • renumbering couplets
  • making taxonomic keys user friendly

What DKey is not
DKey does not generate the key automatically using data matrix. The key needs to be created by the user.

Dichotomous taxonomic key
Dichotomous taxonomic key consists of a series of consecutively numbered couplets. Each couplet consist of two parts called leads. At the end of each lead there is a reference, which can be either a number pointing to other couplet or a text indicating a name of a species or other taxonomic group. The two types of reference are called here "pointer" and "endpoint", respectively.
couplet, lead, pointer, endpoint
Identification based on dichotomous key starts at couplet number one and it is stepwise. At each step a user reads both leads of a couplet and chooses one of them which better fits the identified individual. If a chosen lead is associated with a pointer then the user goes to another couplet which is the next step of identification. The identification is finished when the chosen couplet is associated with an endpoint.

User interface
DKey has a graphical user interface:
DKey, main window
The key is displayed in a table with couplets represented by rows. There are three columns: the first column displays key number, the second column displays first lead and the third column displays the second lead. The table can be used to edit key by adding, removing, copying and moving couplets. Content of the couplet can also be changed using Edit couplet

Image integration
If you want to display images in the key browser ensure that in the key text there is keyword "Fig." before each figure name. Moreover, in the same directory as the .dk.txt file (containing the key) for each image name there need to be an image with the same file name but pre-appended with "fig-". For example, if in a couplet there is text "(Fig. 1a, 1b)", in the same directory there should be two image files: "fig-1a.png" and "fig-1b.png". Apart from providing the image with appropriate image name, the user does not need to make any action to make the images visible in the key browser.
At the moment there are supported two image file extensions ".png" and ".jpg"

Installation

  • Download the ZIP file: dkey-1_0.zip
  • Unpack the ZIP file and copy DKey directory to your hard drive.
  • Run the DKey.exe

At the moment there are executables only for Windows operating system. If you are using macOS or Linux you need to compile the software yourself. The source code is available at: https://github.com/DrawWing/DKey
Please let me know if you have problems with using the software of if you have managed to compile the software for other operating systems.

Licence
DKey software is licensed under the GNU General Public License, version 3. That means you are free to download, reuse, modify, and distribute the software under the terms of this licence.

Menu File
New key
Use this menu entry to creating the first dummy couplet. Select the couplet by clicking it and use Edit couplet to enter real information. In order to add more couplets select the couplet and use Insert couplet below. Finally, save the key using Save.

Open
Use this menu entry to open key in ".dk.txt" format. If you do not have your own key yet you can open a key provided with the software in directory "example". If the key is not in ".dk.txt" format you need to use Import.

Import
Use this menu entry to open a key saved in .txt file. The key can be in various formats including: bracketed and indented, however, the format needs to be consistent in the whole imported key. You need to prepare the file for import. Each lead should be in separate line. There should be a tab character before each reference (endpoint or pointer). For example of indented key see below a fragment of key to genera of Anthomyiida by Elberg (1988).
Elberg 1988 Anthomyiidae key
After editing it should look like this.
Elberg 1988 Anthomyiidae key
Red dots represent spaces and red arrows tab characters. This is a screenshot from Notepad++. I recommend this software for editing text files. In order to make the tab characters visible in Notepad++ use View -> Show Symbol -> Show White Space and TAB.

Only dichotomous keys will be imported properly. If the key is polytomous it should be converted to dichotomous before import. For example of conversion of polytomous key to dichotomous key see below a fragment of key to genera of Agathidinae by Sharkey et al 2009.
Sharkey et al 2009 Agathidinae key
The same key fragment after editing
Sharkey et al 2009 Agathidinae key
Please notice that before editing there was three leads in couplet number two. In order to make the key compatible with dichotomous key a new couplet was added. In the key there was originally 16 couplets, therefore, the new couplet was given number 17 in order to make the couplet numbers unique. Now the key is not consecutively numbered but this problem can be easily solved by after import to DKey using Renumber key.
It is recommended to use Find errors after import. If there are errors it is often easier to edit the imported file and import again instead of editing couplets.
In order to test the import you can use the text file "Sharkey2009Agathidinae-for_import.txt" in directory "example".

Append
Use this menu entry to combine two keys. The appended key is added at the end of currently opened one. Only the couplet numbers and pointers are modified in the appended key; the user needs to modify pointers in order to connect the two combined keys in a logical way. Only append can be used to transfer couplets between keys; all other editing options (copy, move) can be done only within one key.

Save, Save as
Use those menu entries to save change made in the key to the file. Save and make new versions of your key often as the editing operations cannot be undone. If results of any operation are not what you have expected you can go back to the previously saved version.

Export
Use this menu entry to export the key as text ready for publication or linked hypertext. The hypertext in html format can be used to make the key available to others, for example by uploading to web server. In this format user can click links in order to move between couples. The key in html format can be opened with any web browser.

Menu Edit
Cut
Use this menu entry to move couplets within one key. The selected couplets will be removed and can be inserted in new position using Paste below.

Copy
Use this menu entry to copy couplets within one key. The selected couplets will be copied and can be inserted in new position using Paste below.

Paste below
Use this menu entry to paste couplets selected earlier using Cut or Copy. Paste operation works only within one key. If you need to transfer couplets between keys use Append instead. After this operation numbering can be not consecutive.

Edit couplet
Use this menu entry to edit a couplet. A small window will appear which can be used to modify content of a couplet.
DKey, edit couplet
Instead of using menu you can double click a couplet in order to edit it.

Insert couplet below
Use this menu entry to insert dummy couplet. Select the couplet by clicking it and use Edit couplet to enter real information. After this operation numbering can be not consecutive.

Remove couplets
Use this menu entry to remove a couplet. After this operation numbering can be not consecutive.

Swap leads
Use this menu entry to replace the first lead with the second lead and vice versa.

Renumber key
Use this menu entry to make the couplet's numbers consecutive. The pointers are changed accordingly in order to maintain integrity of the key. When couplets are inserted, removed, moved or copied the key is not renumbered automatically and its consecutive numbering can be temporally broken. The user decides when the renumbering occurs. This make it easier to keep track of changes made. Moreover, the renumbering can take a noticeable time in case of large keys. Therefore, in case of several editing operations it is better to make one renumbering when all the editing is finished. The renumbering should be done before the key is exported or displayed in the key browser.

Menu Debug
Find errors
Use this menu entry to check the key for presence of errors. Among others it is verified if the numbering is unique and consecutive. The errors are listed in separate window.
DKey, find errors

Menu View
Key browser
Use this menu entry to see a new window with the key browser.
DKey, key browser
Key browser consist of five windows. The two top windows contain the two leads of the couplet and images associated with the leads. If a lead is associated with a pointer there is a link to the pointed couplet. By clicking the link user goes to the pointed couplet.
The three bottom windows of the key browser contain: path, remaining endpoints and excluded endpoints. The path or history of identification contains list of couplets leading to the current couplet. The remaining endpoints contains list of taxa which can be reached from the current couplet. The excluded endpoints contains list of taxa which cannot be reached from the current couplet. At the beginning of identification, when couplet number one is displayed, the path window and excluded endpoints window are empty, on the other hand the remaining endpoints window contains all the taxa covered by the key. By following steps of the identification and visiting couplets the lists in path window and excluded endpoints window are growing and the list in remaining endpoints window is shrinking until there is only two endpoints.

Hypertext in table
Use this menu entry to see a new window with the key in format of linked hypertext.
DKey, hypertext
If a lead is associated with a pointer there is a link to the pointed couplet. By clicking the link user goes to the pointed couplet.