Module hierarchy

A module to navigate a particular type of hierarchy.

The hierarchy consists of a set of partitioning names at various levels. For example, the hierarchy might look like this:

           3          Root partitioning; Parent of 2
           |
           2          Child of Root partitioning, Parent of 1a, 1b
          /           1a 1b        Children of 2, Parents of 0
          \ /
           0          Child of 0

This shows that the hierarchy could contain cycles; it is not a pure hierarchy. The structure of the hierarchy and the names of the partitionings are given when a Hierarchy object is initialized. The names 0, 1a, etc. are merely illustrative. Also, the hierarchy has the concept of levels. Above, there are four levels, which for discussion we will refer to as level 0, 1, 2 and 3.

The structure of the hierarchy itself is provided by an external module. An item, to be inserted into the hierarchy, is registered with a list of names, one for each partitioning in the hierarchy. The names are the names of the partitions into which each item falls in each partitioning.

It is expected that at the lowest level, each item's name will be unique; that is, it resides in a partition by itself. For example, for a chemical structure, the name at the lowest level might be its canonical SMILES. Except at the lowest level (called 0 above), the partitions are in effect mere containers. Thus, what we mean by an "item" is the sole member of a partition at the lowest level. Finally, the lowest and highest level must each consist of only a single partitioning.

Each partitioning of the hierarchy is a classification of the entire system -- a partitioning; each group of structures within a partitioning is then a efactor

The term "item" is used as a synonym for a Partition object at the lowest level of the hierarchy.

All the partitioning names must be unique and within each partitioning, all the partition names must be unique.