org.gicentre.treemappa
Class TreeMapNode

java.lang.Object
  extended by org.gicentre.treemappa.TreeMapNode
All Implemented Interfaces:
java.lang.Comparable<TreeMapNode>, java.lang.Iterable<TreeMapNode>, javax.swing.tree.MutableTreeNode, javax.swing.tree.TreeNode

public class TreeMapNode
extends java.lang.Object
implements javax.swing.tree.MutableTreeNode, java.lang.Comparable<TreeMapNode>, java.lang.Iterable<TreeMapNode>

Represents a single node to be included in a tree map. Stores a label, a numeric value representing the size of the node, a numeric value representing the colour of the node and the sum of numeric size values below it in the tree.

Version:
3.0, 25th March, 2011
Author:
Jo Wood, giCentre.

Constructor Summary
TreeMapNode(java.lang.String label, double order, java.lang.Float sizeValue, java.lang.Float colourValue)
          Creates a node with the given label, order, size value and colour value.
TreeMapNode(java.lang.String label, double order, java.lang.Float sizeValue, java.lang.Float colourValue, java.awt.geom.Point2D location)
          Creates a node with the given label, order, size value, colour value and location.
 
Method Summary
 void add(TreeMapNode child)
          Adds the given child node to this one.
 java.awt.geom.Rectangle2D calcGeoBounds()
          Reports the bounding rectangle of this node in georeferenced coordinates.
 java.util.Enumeration<TreeMapNode> children()
          Reports the children of this node.
 int compareTo(TreeMapNode node)
          Compares this node with another.
 TreeMapNode findNode(java.lang.String nodeLabel)
          Performs a breadth-first search looking for the first node with the given label.
 double getAccumSize()
          Reports the accumulated numeric values of this node and its children.
 boolean getAllowsChildren()
          Reports whether this node allows children.
 double getArea()
          Reports the area of this node.
 TreeMapNode getChildAt(int index)
          Reports the child at the given index.
 int getChildCount()
          Reports the number of children held by this node.
 java.util.List<TreeMapNode> getChildren()
          Reports the children of this node.
 java.lang.Float getColourValue()
          Reports the numeric value associated with colour of node.
static java.util.Comparator<TreeMapNode> getEWComparator()
          Provides a spatial comparator that can be used for ordering nodes in an west-east direction.
 int getIndex(javax.swing.tree.TreeNode node)
          Reports the index of the given node in this node's list of children.
 java.lang.String getLabel()
          Reports the text label associated with the node.
 int getLevel()
          Reports the depth of this node.
 java.awt.geom.Point2D getLocation()
          Reports the location of this node.
 int getMaxDepth()
          Reports the maximum depth that can be found by traversing from this node downward.
 java.util.List<TreeMapNode> getNeighbours()
          Reports the nodes that are immediate neighbours of this one.
static java.util.Comparator<TreeMapNode> getNSComparator()
          Provides a spatial comparator that can be used for ordering nodes in an south-north direction.
 int getNumLeaves()
          Reports the number of leaves attached to this node and any of its descendants in the tree.
 double getOrder()
          Reports the value used to determine node order.
 TreeMapNode getParent()
          Reports the parent of this node.
 java.lang.String getPath()
          Reports the path from the root node to this one (line of antecedents).
 java.awt.geom.Rectangle2D.Double getRectangle()
          Reports the rectangle representing the tree-map coordinates of this node.
 double getSizeValue()
          Reports the numeric value associated with size of node.
 void insert(javax.swing.tree.MutableTreeNode child, int index)
          Adds the given child node to this one.
 boolean isLeaf()
          Reports whether not not this is a leaf node.
 java.util.Iterator<TreeMapNode> iterator()
          Provides an iterator that will perform a breadth-first iteration over the hierarchy starting with this node and its children.
 void remove(int index)
          Removes the child node at the given index.
 void remove(javax.swing.tree.MutableTreeNode child)
          Removes the given child node.
 void removeFromParent()
          Removes this node from its parent if it has one.
 void setLabel(java.lang.String label)
          Sets the label associated with this node.
 void setLocation(java.awt.geom.Point2D newLocation)
          Sets a new geographic location of this node.
 void setParent(javax.swing.tree.MutableTreeNode parent)
          Sets the new given parent of this node.
 void setSizeValue(java.lang.Float newSizeValue)
          Sets a new size value for this node.
 void setUserObject(java.lang.Object object)
          Would set the new user object to be carried by this node, but does nothing in this case except report an error.
 void sortAtLevel(int sortLevel)
          Sorts all nodes at the given level in the hierarchy into descending order.
 void sortChildren()
          Sorts the immediate child nodes into descending order.
 void sortChildren(java.util.Comparator<TreeMapNode> comparator)
          Sorts the immediate child nodes using the given comparator.
 void sortDescendants()
          Sorts all descendants into descending order.
 void sortDescendants(java.util.Comparator<TreeMapNode> comparator)
          Sorts all of the descendants of this node using the given comparator.
 java.lang.String toString()
          Provides a textual description of the node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TreeMapNode

public TreeMapNode(java.lang.String label,
                   double order,
                   java.lang.Float sizeValue,
                   java.lang.Float colourValue)
Creates a node with the given label, order, size value and colour value. Until this node is added to an existing tree, it is assumed to be a root leaf node.

Parameters:
label - Text label of the node.
order - Value indicating relative order of node. This value is compared with the order of any sibling nodes when sorting them. If order values are the same, nodes are sorted by size then colour value.
sizeValue - Numeric value to be associated with the size of the node or null if it is to be found from the accumulated values of its descendants. If this is a leaf node (ie it has no descendants) and sizeValue is null, its size is assumed to be 1. If this value is negative, this node is treated as a dummy node with the size of abs(sizeValue).
colourValue - Numeric value to be associated with the colour of the node or null if colour to be generated.

TreeMapNode

public TreeMapNode(java.lang.String label,
                   double order,
                   java.lang.Float sizeValue,
                   java.lang.Float colourValue,
                   java.awt.geom.Point2D location)
Creates a node with the given label, order, size value, colour value and location. Until this node is added to an existing tree, it is assumed to be a root leaf node.

Parameters:
label - Text label of the node.
order - Value indicating relative order of node. This value is compared with the order value of all sibling nodes when sorting them. If order values are the same, nodes are sorted by size then colour value.
sizeValue - Numeric value to be associated with the size of the node or null if it is to be found from the accumulated values of its descendants. If this is a leaf node (ie it has no descendants) and sizeValue is null, its size is assumed to be 1. If this value is negative, this node is treated as a dummy node with the size of abs(sizeValue).
colourValue - Numeric value to be associated with the colour of the node or null if colour to be generated.
location - Spatial location of node (can be null if not spatially referenced).
Method Detail

add

public void add(TreeMapNode child)
Adds the given child node to this one. Note that once a child has been added, connected TreeMapNodes may not return correct values for getLevel() or getMaxDepth() until either updateTree() or TreeMappa's buildTreeMap() method has been called.

Parameters:
child - Child node to add.

findNode

public TreeMapNode findNode(java.lang.String nodeLabel)
Performs a breadth-first search looking for the first node with the given label. Note that this search does not consider this node itself, but starts with its children.

Parameters:
nodeLabel - Text to search for.
Returns:
Highest level node matching the given label, or null if no match found.

sortChildren

public void sortChildren()
Sorts the immediate child nodes into descending order.


sortChildren

public void sortChildren(java.util.Comparator<TreeMapNode> comparator)
Sorts the immediate child nodes using the given comparator. This allows custom sorting of nodes, for example by alphabetical order of label.

Parameters:
comparator - Comparator to use to compare a pair of TreeMapNodes.

sortDescendants

public void sortDescendants(java.util.Comparator<TreeMapNode> comparator)
Sorts all of the descendants of this node using the given comparator. This allows custom sorting of nodes, for example by alphabetical order of label.

Parameters:
comparator - Comparator to use to compare a pair of TreeMapNodes.

sortDescendants

public void sortDescendants()
Sorts all descendants into descending order.


sortAtLevel

public void sortAtLevel(int sortLevel)
Sorts all nodes at the given level in the hierarchy into descending order.

Parameters:
sortLevel - Hierarchy level at which to apply sorting, where 0 is root level.

getPath

public java.lang.String getPath()
Reports the path from the root node to this one (line of antecedents).

Returns:
Text representing path to this node.

toString

public java.lang.String toString()
Provides a textual description of the node.

Overrides:
toString in class java.lang.Object
Returns:
Text representation of the node.

getLabel

public java.lang.String getLabel()
Reports the text label associated with the node.

Returns:
Text label of the node.

getOrder

public double getOrder()
Reports the value used to determine node order. The smaller the value, the higher up in the list of siblings this node will appear. If two sibling nodes have the same order value, the average order of their descendants is used, if they are the same, their areas and then their colour values are compared to determine order.

Returns:
Value used to determine node order of siblings.

getSizeValue

public double getSizeValue()
Reports the numeric value associated with size of node.

Returns:
Numeric value associated with size of the node.

getColourValue

public java.lang.Float getColourValue()
Reports the numeric value associated with colour of node. Can be null, if colour generation is automatic.

Returns:
Numeric value associated with colour of the node.

getAccumSize

public double getAccumSize()
Reports the accumulated numeric values of this node and its children.

Returns:
Accumulated numeric values.

getArea

public double getArea()
Reports the area of this node. This should be approximately proportional to the accumulated numeric value for this node and its children, but takes into account any borders between nodes.

Returns:
Area of node.

getLocation

public java.awt.geom.Point2D getLocation()
Reports the location of this node. This may be null if the node has no spatial reference.

Returns:
Spatial location of node.

calcGeoBounds

public java.awt.geom.Rectangle2D calcGeoBounds()
Reports the bounding rectangle of this node in georeferenced coordinates. This method searches all this node's children in order to find the bounds, so should only be called when necessary. If the node does not have spatial referencing, the same value as getRect() is returned (ie the pixel coordinates of the node).

Returns:
Bounds of this node.

getLevel

public int getLevel()
Reports the depth of this node. 0 is the root node, 1 is a child of the root, 2 is a grandchild etc.

Returns:
Level of node.

getMaxDepth

public int getMaxDepth()
Reports the maximum depth that can be found by traversing from this node downward. Maximum depth will always be the level of this node if a leaf or at least this level+1 if this is a branch node.

Returns:
Maximum depth of node and/or its descendants.

getNumLeaves

public int getNumLeaves()
Reports the number of leaves attached to this node and any of its descendants in the tree. If this node is a leaf, will always return 1, if not it will return a value of at least 1.

Returns:
Number of leaves from this point downward in the tree.

setLabel

public void setLabel(java.lang.String label)
Sets the label associated with this node.

Parameters:
label - New label.

setSizeValue

public void setSizeValue(java.lang.Float newSizeValue)
Sets a new size value for this node. Note that changing a node's size value will not effect the topology of the tree, but will affect the future geomoetry associated with each node. To recalculate the geometry a call to TreeMappa's buildTreeMap() method will be necessary.

Parameters:
newSizeValue - Numeric value to be associated with the size of the node or null if it is to be found from the accumulated values of its descendants. If this is a leaf node (ie it has no descendants) and sizeValue is null, its size is assumed to be 1. If this value is negative, this node is treated as a dummy node with the size of abs(sizeValue).

setLocation

public void setLocation(java.awt.geom.Point2D newLocation)
Sets a new geographic location of this node. Note that changing a node's location will not effect the topology of the tree, but will affect the future geomoetry associated with each node. To recalculate the geometry a call to TreeMappa's buildTreeMap() method will be necessary.

Parameters:
newLocation - New location to be associated with the node or null if it is to be found from the mean centre of its descendants. If this is a leaf node (ie it has no descendants) and location is null, it is assumed this node has no location.

getRectangle

public java.awt.geom.Rectangle2D.Double getRectangle()
Reports the rectangle representing the tree-map coordinates of this node. Note that this geometry may not be consistent with the current properties of the tree if it has not been rebuilt with TreeMappa's buildTreeMap() method since a change to any of this node's properties that might affect geometry.

Returns:
Rectangle representing the tree-map coordinates of this node.

getChildren

public java.util.List<TreeMapNode> getChildren()
Reports the children of this node.

Returns:
This node's children.

getNeighbours

public java.util.List<TreeMapNode> getNeighbours()
Reports the nodes that are immediate neighbours of this one. Neighbours are only stored for those between nodes at the same level in the hierarchy as this node's level.

Returns:
This node's adjacent neighbours or null if adjacency has not been calculated. This will return an empty collection if adjacency has been calculated but this node has no siblings.

compareTo

public int compareTo(TreeMapNode node)
Compares this node with another. Used for sorting nodes using the rules in the following order:
  1. Compare the 'order' value of the two nodes. If they are equal then,
  2. Compare the average order of the two nodes' descendants. If they are equal then,
  3. Compare the 'size' values of the two nodes. If they are equal then,
  4. Compare the accumulated size of the two nodes' descendants. If they are equal then,
  5. Compare the colour values (but not the colours themselves) of the two nodes. If they are equal or either undefined then,
  6. Compare the labels of the two node alphabetically. If they are equal then,
  7. Compare the hash codes of the two nodes
  8. Nodes will therefore only be considered equal if they are identical object references.
    For alternative ordering of nodes (e.g. alphabetical ordering of node labels), provide a Comparator object when calling sortChildren() or sortDescendants().

    Specified by:
    compareTo in interface java.lang.Comparable<TreeMapNode>
    Parameters:
    node - Node with which to compare this one.
    Returns:
    Comparative order of this and the other object.

insert

public void insert(javax.swing.tree.MutableTreeNode child,
                   int index)
Adds the given child node to this one.

Specified by:
insert in interface javax.swing.tree.MutableTreeNode
Parameters:
child - Child node to add.
index - Position in list of children to add.

remove

public void remove(int index)
Removes the child node at the given index.

Specified by:
remove in interface javax.swing.tree.MutableTreeNode
Parameters:
index - Position in list of children to remove.

remove

public void remove(javax.swing.tree.MutableTreeNode child)
Removes the given child node.

Specified by:
remove in interface javax.swing.tree.MutableTreeNode
Parameters:
child - Child node to remove.

removeFromParent

public void removeFromParent()
Removes this node from its parent if it has one.

Specified by:
removeFromParent in interface javax.swing.tree.MutableTreeNode

setParent

public void setParent(javax.swing.tree.MutableTreeNode parent)
Sets the new given parent of this node.

Specified by:
setParent in interface javax.swing.tree.MutableTreeNode
Parameters:
parent - New parent to link with this one.

setUserObject

public void setUserObject(java.lang.Object object)
Would set the new user object to be carried by this node, but does nothing in this case except report an error.

Specified by:
setUserObject in interface javax.swing.tree.MutableTreeNode
Parameters:
object - Object to store (ignored).

children

public java.util.Enumeration<TreeMapNode> children()
Reports the children of this node.

Specified by:
children in interface javax.swing.tree.TreeNode
Returns:
Children associated with this node.

getAllowsChildren

public boolean getAllowsChildren()
Reports whether this node allows children. Always returns true.

Specified by:
getAllowsChildren in interface javax.swing.tree.TreeNode
Returns:
Always true as this node allows children to be added.

getChildAt

public TreeMapNode getChildAt(int index)
Reports the child at the given index.

Specified by:
getChildAt in interface javax.swing.tree.TreeNode
Parameters:
index - Index representing position of the child.

getChildCount

public int getChildCount()
Reports the number of children held by this node.

Specified by:
getChildCount in interface javax.swing.tree.TreeNode
Returns:
Number of children of this node.

getIndex

public int getIndex(javax.swing.tree.TreeNode node)
Reports the index of the given node in this node's list of children.

Specified by:
getIndex in interface javax.swing.tree.TreeNode
Parameters:
node - Node to search for.
Returns:
Index of the first occurrence of the given node in this node's children or -1 if object not found.

getParent

public TreeMapNode getParent()
Reports the parent of this node.

Specified by:
getParent in interface javax.swing.tree.TreeNode
Returns:
This node's parent or null if no parent.

isLeaf

public boolean isLeaf()
Reports whether not not this is a leaf node. A leaf is defined as a node without any children.

Specified by:
isLeaf in interface javax.swing.tree.TreeNode
Returns:
True if this node does not have any children.

iterator

public java.util.Iterator<TreeMapNode> iterator()
Provides an iterator that will perform a breadth-first iteration over the hierarchy starting with this node and its children.

Specified by:
iterator in interface java.lang.Iterable<TreeMapNode>
Returns:
Iterator capable of performing a breadth-first search though the hierarchy.

getEWComparator

public static java.util.Comparator<TreeMapNode> getEWComparator()
Provides a spatial comparator that can be used for ordering nodes in an west-east direction.

Returns:
East-west comparator.

getNSComparator

public static java.util.Comparator<TreeMapNode> getNSComparator()
Provides a spatial comparator that can be used for ordering nodes in an south-north direction.

Returns:
North-south comparator.


treeMappa V.3.0.1, API documentation generated 4th April, 2011