Node Groups & Relationships

Nodes (see Node Structure and Types) form node groups, which are then connected to create a database model for the FNA keys.  There are three group types

However, they share generalized group elements.  In particular, the End Nodes for both have the same dual role that is described in Node Structure and Types. To Do: Need a diagram like on 1/11/2015 in order to include the 2 types of connector nodes and to allow for 2 layers of connector nodes - use the real diagram for Salicaceae Populus on 12/30/2015.  Need a diagram like on 1/28/2015 to show the all-inclusive sequence of nodes.  Also need to show that multiple-attribute-set connector nodes can be both external and internal to the key.

Node Group Elements -

1. Base Node
• The Base Node provides the parent taxon name or intermediate rank name; all targets in the group are members of this taxon or intermediate rank.
• If the Couplet Nodes immediately follow the Base Node, it provides the base node number for the group; this node number is used to convert the row numbers of the Couplet Nodes to the node numbers used in the database. This is the case if the Base Node is a root, connector or singleton node.
• If the Couplet Nodes are separate from the Base Node, then the base node number is one less than the first couplet node number. This is the case if the Base Node is a target node (or a couplet node with an intermediate title) in a higher level node, so that node has dual roles: it is a target node in the higher level node group and Base Node for the current node group.
• If the Base Node is a singleton parent, then there are no Couplet Nodes and the singleton node is the single End Node and immediately follows the Base Node. In this case the Base Node can be a root, connector, target with an intermediate title or a singleton node. Note that if the Base Node is a singleton node, it also acts as a singleton parent.
2. Couplet Nodes
• Singleton groups have no couplet nodes.
• Key groups have zero or more couplet nodes. With no couplet nodes, there are two target nodes. With one or more couplet nodes, the end nodes can be target or attribute set nodes.  There are special cases where a target node can be replaced by a segregate node.
• If the end nodes are attribute set nodes, then associated connector node may specify a couplet node that acts as a merge point; that is, all attributes between the Base Node and the merge point are used in common with with all attribute sets associated with that connector node.
• If there are subkeys, the master key and the subkeys are separate node groups. They are joined together by couplet or connector nodes with an intermediate titles.
3. End Nodes
• As discussed under Base Node, the End Node could be a singleton node; in all other cases, there is always more than one End Node.
• For target End Nodes, the target node also acts as a Base Node for the node at the next level.
• Attribute set nodes exist when a taxon has more than one attribute set that describe that taxon, so require an associated connector node for the taxon, which acts as the Base Node for the node at the next level.
• In each of the three End-Node cases above, instead of the End Node being the Base Node for the next level, the End Node can be a terminal taxon.

Node Creation Process - From a high level, our objective is to model the FNA using these objects:

• Root nodes
• Keys
• Connector nodes
• Alternate Key nodes
• Singletons

In more detail, all nodes can be created sequentially using the following process:

1. For each family:
1. Create the family root node, which acts as a base node
2. If level has key(s)
1. For the key (or for each alternate key):
   1. Create a multiple-attribute-set connector node for each file in the multiSpcSubclasses directory
   2. If this level has alternate keys, create an alternate key node for each key, which serves as the base node and supplies the name for the alternate key
   3. For each row in the key, create one of these node types:
   • Couplet
   • Target -- If the target is a key at the next level and does not involve a connector node, then that target node is connected directly to the key; as an example, in A Key as a Hierarchy see the diagram showing how the Caryophyllaceae key to genera is connected to the Silene key to species.
   • Attribute Set
   • Segregate
2. If this level has alternate keys, create an alternate-key connector node for each target (both single and multiple-attribute-set targets)
3. Else (level has a singleton)
1. Create a singleton node, which acts as a base node for the next level
4. Repeat B. or C. for each level, but there are no alternate keys at the species and subsp levels

Therefore, to create the Node List, one starts with the root for each family and works through each level, adding keys, connector nodes, alternate key nodes and singletons, where for each key a node is added for each row. The Node List is numbered using the class list index (cli) with values 0, 1, 2, ... (see diagram in Node Structure and Types).

This process creates nodes in the order of the keying hierarchy rather than the Naming Hierarchy. Therefore, as nodes are created that have a naming-only parent, these parent nodes have to be added on the side and linked in using the Target Subset Index, discussed in Node Structure and Types.

Additional Nodes for Alternate Keys - Six alternate keys were enumerated in Key Types and Subkeys. There must be a separate key base node for each alternative since each has separate child nodes.  Also there must be separate target, attribute set and connector nodes for each alternative key since the parent(s) of each of of these nodes is different. Finally, each target or connector node needs an alternate-key connector node, in order to distinguish the different attribute sets from the paths through each alternate key.

The node list and node numbering must take these additional nodes into account. After the user chooses which alternate key they want, this determines which of alternate nodes are to be used.