eu.etaxonomy.cdm.model.description

Class PolytomousKeyNode

java.lang.Object

eu.etaxonomy.cdm.model.common.CdmBase

eu.etaxonomy.cdm.model.common.VersionableEntity

eu.etaxonomy.cdm.model.description.PolytomousKeyNode

All Implemented Interfaces:

ICdmBase, IMultiLanguageTextHolder, ISelfDescriptive, IVersionableEntity, java.io.Serializable, java.lang.Cloneable

@Entity
public class PolytomousKeyNode
extends VersionableEntity
implements IMultiLanguageTextHolder

This class represents a node within a polytomous key structure. The structure of such a key is a directed tree like acyclic graph of PolytomousKeyNodes. A PolytomousKeyNode represents both the node and the edges that lead to this node, therefore an extra class representing the edges does not exist.
The attribute representing the edge leading from its parent node to this node is the statement, attributes leading to the child nodes are either the question or the feature. While statements are required, questions and features are optional and do typically not exist in classical keys. Both, questions and features, will be "answered" by the statements of the child nodes, where questions are usually free text used in manually created keys while features are typically used in automatically created keys based on structured descriptive data. Only one of them should be defined in a node. However, if both exist the question should always be given priority over the feature.
Typically a node either links to its child nodes (subnodes) or represents a link to a taxon. The later, if taken as part of the tree, are usually the leaves of the represented tree like structure (taxonomically they are the end point of the decision process).
However, there are exceptions to this simple structure:

Subnodes and taxon link
In rare cases a node can have both, subnodes and a link to a taxon. In this case the taxonomic determination process may be either terminated at the given taxon or can proceed with the children if a more accurate determination is wanted. This may be the case e.g. in a key that generally covers all taxa of rank species and at the same time allows identification of subspecies or varieties of these taxa. Other nodes:
A node may not only link to its subnodes or to a taxon but it may also link to another node (with a different parent) of either the same key or another key.
NOTE: If an otherNode represents a node of the same tree the key does not represent a strict tree structure anymore. However, as this is a rare case we will still use this term at some places. Subkey:
A node may also link to another key (subkey) as a whole, which is equal to an otherNode link to the root node of the other key. In this case the path in the decision graph spans over multiple keys. This structure is typically used when a key covers taxa down to a certain rank, whereas taxa below this rank are covered by extra keys (e.g. a parent key may cover all taxa of rank species while subspecies and varieties are covered by a subkeys for each of these species. Another usecase for subkeys is the existence of an alternative key for a certain part of the decision tree. Multiple taxa
Some nodes in legacy keys do link to multiple taxa, meaning that the key ambigous at this point. To represent such nodes one must use child nodes with empty statements for each such taxon (in all other cases - except for root nodes - the statement is required). Applications that do visualize the key should handle such a node-subnode structure as one node with multiple taxon links. This complicated data structure has been chosen for this rare to avoid a more complicated List structure for the standard case. The root node of the key may represent the entry point question or feature but does naturally neither have a statement nor a linked taxon as there is no prior decision yet.

Notes

A polytomous key node can be referenced from multiple other nodes via the otherNode attribute of the other nodes. Therefore, though we speek about a "decision tree" structure a node does not necessarily have only one parent. However, nodes are mainly represented in a tree structure and therefore do have a defined parent which is the "main" parent. But when implementing visualizing or editing tools one should keep in mind that this parent may not be the only node linking the child node.

Since:

13-Oct-2010

Author:

a.mueller

See Also:

Serialized Form