MRS  1.0
A C++ Class Library for Statistical Set Processing
Public Member Functions | Protected Member Functions | Protected Attributes
subpavings::CollatorSPnode Class Reference

A derived class based on SPnode. More...

+ Inheritance diagram for subpavings::CollatorSPnode:
+ Collaboration diagram for subpavings::CollatorSPnode:

List of all members.

Public Member Functions

 CollatorSPnode ()
 No-argument constructor.
 CollatorSPnode (ivector &v)
 Initialised constructor with box.
 CollatorSPnode (const CollatorSPnode &other)
 Copy constructor.
 CollatorSPnode (const SPSnode &spn, size_t bigN=0)
virtual ~CollatorSPnode ()
CollatorSPnode & operator= (CollatorSPnode rhs)
std::vector< const
CollatorSPnode * > & 		getConstLeaves (std::vector< const CollatorSPnode * > &leaves) const
 Get a container of all descendent leaf nodes.
virtual std::ostream & leavesAverageOutputTabs (std::ostream &os, int prec=5) const
 Output for for all leaves of a binary tree.
virtual std::ostream & nodePrint (std::ostream &os) const
std::size_t allocateRanges (const std::vector< RealVec > &rangesToAllocate, std::size_t index=0)
 Allocate collections of values to become rangeCollections to this and children.
virtual void nodeExpand (int comp)
 Expand a leaf node.
virtual void nodeExpand ()
 Expand a leaf node.
const CollatorSPnode * findContainingNode (const cxsc::rvector &pt, OPERATIONS_ON childInd=ON_PARENT) const
 Find the leaf node which would contain a data point.
void addPaving (const CollatorSPnode *const rhs)
 Add the contents of another collator to this.
void addPaving (const SPSnode *const rhs)
 Collate a statistical subpaving into this.
virtual void reduceCollation ()
CollatorSPnode & operator+= (const CollatorSPnode &add)
 Add the contents of another collator to this.
const CollatorSPnode operator+ (const CollatorSPnode &add) const
 Add the contents of two collators together.
CollatorSPnode & operator+= (const SPSnode &add)
 Add a representation of a statistical subpaving into this collation.
const CollatorSPnode operator+ (const SPSnode &add) const
 Add the contents of a collator and a statistical subpaving together.
CollatorSPnode & operator*= (cxsc::real &mult)
 Multiply this collation by a scalar.
const CollatorSPnode operator* (cxsc::real &mult) const
 Get the results of multiplying this collation by a scalar.
CollatorSPnode & operator/= (cxsc::real &div)
 Divide this collation by a scalar.
const CollatorSPnode operator/ (cxsc::real &div) const
 Get the results of dividing this collation by a scalar.
virtual void marginalise (const std::vector< int > &reqDims)
 Marginalised this.
const CollatorSPnode makeMarginalised (const std::vector< int > &reqDims) const
 Make a marginalised version of this.
virtual void normalise ()
 Normalise this.
const CollatorSPnode makeNormalised () const
 Make the normalised version of this.
virtual void average ()
 Average this.
const CollatorSPnode makeAverage () const
 Make the average of this.
void swapCollator (CollatorSPnode &spn)
 Swap this and another node.
std::string nodeStringSummary () const
 Get a string summary of this node's properties.
Accessors for links between the nodes.

Note that pointers for parent, leftChild, and rightChild are not reference counted so there could potentially be problems with the use of returned pointers (for instance, being used to delete nodes). These pointers might be better implemented with boost::shared_ptr .

CollatorSPnode * getParent () const
 Accessor for the parent of a node.
CollatorSPnode * getLeftChild () const
 Accessor for the left child of a node.
CollatorSPnode * getRightChild () const
 Accessor for the right child of a node.
virtual cxsc::real getTotalRangeCollection () const
 Get the total of the values held for all the nodes collated by this.
virtual bool isEmptyRangeCollection () const
 Get whether this node has nothing collated.
virtual std::size_t getSizeRangeCollection () const
 Get the number of subpavings collated into this.
virtual cxsc::real getTotalAbsValueTimesVol () const
 Get the total 'area' represented by this collation.
std::vector< RealVec > & getAllRangeCollections (std::vector< RealVec > &container) const
 Fill in a container of height values for this and its descendants.
virtual RealVec & getLeafNodeFHatValues (RealVec &vals) const
Get a collection of the L1 distance values

for each element of the collation against a statistical subpaving.

The L1 distance for a element of this against a statistical subpaving is defined over all the leaves of a non-minimal union of this collation and the given statistical subpaving. The L1 distance for an element in this is the sum, over these leaves, of the absolute differences between the 'height' value for that element for the leaf and the 'height' value of the statistical subpaving for the leaf (ie counter/volume normalised by total count in the whole paving), multiplied by the volume of the leaf.

Throws a NullSubpavingPointer_Error if adh is NULL.

Parameters:
adhA pointer to a statistical subpaving to calculate distances against.
containera reference to container to use to store the L1 distance values. Any contents of the given container will be discarded before new values are added.
Returns:
An ordered collection of the L1 distance values for each element of the collation against adh, in the same order as the elements are added to this collation.
Precondition:
spn should be a non-NULL pointer.
virtual RealVec getL1DistancesToAverage () const
virtual RealVec & getL1DistancesToAverage (RealVec &container) const
virtual RealVec getL1DistancesToAverage (const CollatorSPnode *const other) const
virtual RealVec & getL1DistancesToAverage (RealVec &container, const CollatorSPnode *const other) const
virtual RealVec getL1Distances (const SPSnode *const spn) const
virtual RealVec & getL1Distances (RealVec &container, const SPSnode *const spn) const
Output for all the boxes in this

But, unlike nodesAllOutput, does not do tab indentation

Parameters:
osis the stream to send to.
precis the precision used for printing.
virtual std::ostream & nodesAllPrint (std::ostream &os) const
virtual std::ostream & nodesAllPrint (std::ostream &os, int prec) const
Output the range collection for this
Parameters:
osis the stream to send to.
precis the precision used for printing.
virtual std::ostream & outputNodeRangeCollection (std::ostream &os) const
virtual std::ostream & outputNodeRangeCollection (std::ostream &os, int prec) const

Protected Member Functions

 CollatorSPnode (ivector &v, const RangeCollectionHist &rangeColl)
 Constructor initialised with a box and a collection for the rangeCollection.
virtual std::ostream & leafOutputTabs (std::ostream &os) const
virtual std::ostream & leafAverageOutputTabs (std::ostream &os, int prec=5) const
 Output for a node in a binary tree, tab-delimited.
virtual std::ostream & oneLineOutput (std::ostream &os, int level=0) const
 A quick one-line summary of a collator node.
RangeCollectionHist getRangeCollection () const
 Get a copy of the rangeCollection.
virtual cxsc::real getNodeAbsValueTimesVol () const
 Get the total area of the elements collated in this.
virtual bool checkNoNegativeTotalValues (bool checkSoFar=true) const
 Check that there are no negative values in the 'heights' represented in this collation. Return true if no negative heights found.
virtual cxsc::real getAverageRangeCollectionValue () const
 Get the average of the heights of the elments in this.
virtual RangeCollectionHist getAverageRangeCollection () const
 Get a Range Collection representing the average of the heights of the elments in this.
virtual void nodeRangeCollectionReduce ()
 Reduce the rangeCollection for this node to a single value representing the heights of the elements originally represented in this's rangeCollection.
virtual void nodeScalarMult (cxsc::real &mult)
 Multiply the rangeCollection for this node by a scalar value.
virtual void selfScalarMult (cxsc::real &mult)
 Multiply the rangeCollections for this node and its descendants by a scalar value.
virtual void nodeScalarDiv (cxsc::real &div)
 Divide the rangeCollection for this node by a scalar value.
virtual void selfScalarDiv (cxsc::real &div)
 Divide the rangeCollections for this node and its descendants by a scalar value.
virtual void _normalise ()
 Non-public version of normalise().
virtual void _normalise (const cxsc::real &normalisingConstant)
 Normalise this using given normalising constant.
virtual void _start_marginalise (const std::vector< int > &reqDims)
 Non-public version of marginalisation to have only the required dimensions.
virtual void _marginalise (const std::vector< int > &outDims)
 Non-public version of marginalisation to take out the unwanted dimensions.
virtual void _average ()
 Non-public version of average.
virtual VecDotPrec & getLeafNodeAbsDiffToAvAreaAccumulations (VecDotPrec &areaAcc) const
virtual cxsc::dotprecision & getLeafNodeAbsAreaAccumulations (cxsc::dotprecision &areaAcc) const

Protected Attributes

RangeCollectionHist rangeCollection
 A collection of ranges.

Detailed Description

A derived class based on SPnode.

The base class SPnode is a node in the representation of a regular subpaving as a binary tree. A node represents a box (interval vector). SPnodes are linked together to form the tree. The initial box of the subpaving is the box represented by the root node of the tree. A box which has been split will be represented as node with one or two children. A subpaving of [x] (union of non-overlapping sub- boxes of [x]) is represented by the leaves (degenerate/ child-less) nodes in the tree.

The CollatorSPnode class collates data from a collection of SPSnodes or objects from classes derived from SPSnode.

An entire tree structure represents a non-minimal union over the trees rooted at each node collated, ie the boxes of the leaves of the collated tree make a subpaving that is the union of the subpavings represented by each tree (tree rooted at each node) collated.

Each node has a container (the rangeCollection) that represents the ordered collection of normalised 'heights' for the SPSnodes collated, where height is defined as (1/total of counters in entire tree) * node counter/node volume. The contents of this container are represented in the order in which they are added to the collation, the value for the last one added being at the end of the collection.

In this documentation the SPSnodes collated by a CollatorSPnode are referred to as the 'elements' of the collator. The information held in each node for each element gives the 'height' of the equivalent node of that element. The 'area' in a node represented for a single element in the collation is the element 'height' multipled by the volume of the box that the node represents. The area represented for a single element in the collation over the whole tree is the sum over all the leaf nodes of the leaf node areas for that element. If no modifying operations have been applied to the rangeCollection after the collation of an SPnode then the area of the element representing that SPnode in the collection will be 1.0. Operations which modify the rangeCollection so that the total area of an element is no longer 1.0 include reduceRangeCollection(), *=, and /=. The total area represented by a collation is the sum over all its elements of the areas represented by by each element.

Constructor & Destructor Documentation

CollatorSPnode::CollatorSPnode ( ivector &  v) [explicit]

Initialised constructor with box.

Throws a MalconstructedBox_Error if v has no practical (0 or negative) dimensions.

Parameters:
vinterval vector for the box this represents.
Precondition:
v should be a proper ivector, with length >= 1. 
  : SPnode(v) {}
CollatorSPnode::CollatorSPnode ( const SPSnode &  spn,
size_t  bigN = 0 
) [explicit]

Constructor initialised with an SPSnode and a normalising constant.

The normalising constant is used to construct a NewCollatorNode from an SPSnode. The SPSnode is represented in the collation by its normalised 'height' SPS node count /(normalising constant * SPS node vol).

A NoBox_Error is thrown if spn has no box.

The given normaliser bigN defaults to 0. If a value of bigN = 0 is passed to the method, it is replaced with the counter for the ultimate ancestor of this.

If both the counter for the ultimate ancestor of this and bigN are 0, a std::logic_error exception is thrown.

Parameters:
spnAn SPSnode to collate into this.
bigNthe normalising constant, defaulting to 0.
Precondition:
spn must have a box. 
{
  if ( spn.isEmpty() ) {
    throw NoBox_Error(
      "CollatorSPnode::CollatorSPnode(const SPSnode&, size_t)");
  }
  
  /* recursion means that this is repeated if bigN == 0, but 
   * it would be very unusual for a root with bigN == 0 to have 
   * children*/
  if ( bigN == 0) {
    bigN = spn.getRootCounter();
  }
  
  theBox = NULL;  
  nodeName = spn.getNodeName();
  
  cxsc::real nodeValue(0.0);
  
  if (bigN == 0 && spn.getCounter() != 0) { // should never happen
    
    throw std::logic_error(
    "CollatorSPnode::CollatorSPnode(const SPSnode&, size_t) : error with counter");
  }
  // allow 0 value for bigN if the spn counter is also 0 -> node value is 0
  if (bigN != 0 && spn.getCounter() != 0) {
    
    nodeValue = (1.0 * spn.getCounter())/
            (1.0 * bigN * spn.nodeRealVolume());
    
  }
  
  rangeCollection = RangeCollectionHist( nodeValue );
  theBox = new ivector(spn.getBox());
  
  //recursion on the children
  if (spn.hasLCwithBox()) {
    nodeAddLeft(new CollatorSPnode(*spn.getLeftChild(), bigN));
  }
  else leftChild=NULL;

  if (spn.hasRCwithBox()) {
    nodeAddRight(new CollatorSPnode(*spn.getRightChild(), bigN));
  }
  else rightChild=NULL;

}
CollatorSPnode::~CollatorSPnode ( ) [virtual]

Destructor. 

{}

Member Function Documentation

void CollatorSPnode::_normalise ( const cxsc::real &  normalisingConstant) [protected, virtual]

Normalise this using given normalising constant.

Parameters:
normalisingConstantto normalise this and its descendants. 
{
  // if this is a root we use its value x vol as normaliser
  
  // normalise ourselves
  // just need to divide range collection by normalising constant
  rangeCollection.reduce();  // reduce to one value
  rangeCollection /= normalisingConstant;
  
  // recurse on left child
  if ( hasLCwithBox() ) {
    getLeftChild()->_normalise(normalisingConstant);
  }
  
  // recurse on right child
  if ( hasRCwithBox() ) {
    getRightChild()->_normalise(normalisingConstant);
  }
  
}
void CollatorSPnode::addPaving ( const CollatorSPnode *const  rhs)

Add the contents of another collator to this.

Tree structures are combined using a non-minimal union and the rangeCollection for the subpaving pointed to by rhs is appended to the end of this's rangeCollection. The effect is as though all the statistical subpavings collated by the subpaving pointed to by rhs had been collated into this.

If rhs points to NULL, or the collation pointed to by rhs has no box, this is unchanged by the operation.

Throws an IncompatibleDimensions_Error if both this and the subpaving pointed to by rhs have boxes and the dimensions or sizes of those boxes are not the same.

Parameters:
rhspointer to the root of the collator to be added to this.
Precondition:
If both this and the subpaving pointed to by rhs have boxes, those boxes should have the same dimensions and sizes.
Postcondition:
The tree structure (subpaving structure) for this becomes the result of the non-minimal union of the tree structure (subpaving) for this and the tree structure (subpaving) for the subpaving pointed to by rhs. The rangeCollection for the subpaving pointed to by rhs is appended to the end of the original rangeCollection for this. 
{
  // if rhs is  NULL or rhs is empty, do nothing
  if (rhs != NULL && !rhs->isEmpty()) {
    
    // this is not empty, boxes don't match
    if (!isEmpty() && getBox() != rhs->getBox() ) {
      throw IncompatibleDimensions_Error(
      "CollatorSPnode::addPaving(const CollatorSPnode * const)");
    }
    
    // gtee that rhs is non null and not empty, but this could be empty
    _lazyCollationNonMinimalUnion(rhs);
  }
}
void CollatorSPnode::addPaving ( const SPSnode *const  rhs)

Collate a statistical subpaving into this.

Tree structures are combined using a non-minimal union and information giving a 'height' value for the equivalent node in the subpaving pointed to by rhs is appended to the end of this's rangeCollection.

If rhs points to NULL or has no box, this is unchanged by the operation.

Throws an IncompatibleDimensions_Error if both this and the subpaving pointed to by rhs have boxes and the dimensions or sizes of those boxes are not the same.

Parameters:
rhspointer to the root of the statistical subpaving to be added to this.
Precondition:
If both this and the subpaving pointed to by rhs have boxes, those boxes should have the same dimensions and sizes.
Postcondition:
The tree structure (subpaving structure) for this becomes the result of the non-minimal union of the tree structure (subpaving) for this and the tree structure (subpaving) for the subpaving pointed to by rhs. Information giving 'height' for the subpaving pointed to by rhs is appended to the end of the original rangeCollection for this. 
{
  // if rhs is  NULL or rhs is empty, do nothing
  if (rhs != NULL && !rhs->isEmpty()) {
  
    // make the sps node into a collator
    CollatorSPnode temp(*rhs);
    
    // add temp to this
    addPaving(&temp);
  }
}
std::size_t CollatorSPnode::allocateRanges ( const std::vector< RealVec > &  rangesToAllocate,
std::size_t  index = 0 
)

Allocate collections of values to become rangeCollections to this and children.

Allocation order is this , left child and its decsendents, then right child and its descendents.

Used for testing.

Throws a std::invalid_argument exception if the number of elements in rangesToAllocate is less than the number of elements collated in this.

Parameters:
rangesToAllocateis a collection of ranges to allocate.
indexis the index of the range in rangesToAllocate to this.
Returns:
the index of the next range in the collection to be allocated.
Precondition:
rangesToAllocate should have the same number of ranges in as there are elements in this collation. 
{
  if (index >= rangesToAllocate.size()) {
    throw std::invalid_argument(
    "CollatorSPnode::allocateRanges(  const vector< RealVec >&, size_t) : range allocations too short");
  }

  rangeCollection = RangeCollectionHist(rangesToAllocate[index]);

  size_t newIndex = index+1;
  if (hasLCwithBox()) {
    newIndex = getLeftChild()->allocateRanges(rangesToAllocate, newIndex);
  }
  if (hasRCwithBox()) {
    newIndex = getRightChild()->allocateRanges(rangesToAllocate, newIndex);
  }

  // have done all the children
  // if this is the root, want to check we have used all the allocations
  if (NULL == getParent()) {
    if (newIndex < rangesToAllocate.size()) {
      std::cerr << "Warning - there are more ranges in the ranges to ";
      std::cerr << "allocate than there are nodes in the tree" << std::endl;
    }
  }

  return newIndex;
}
void CollatorSPnode::average ( ) [virtual]

Average this.

Averaging means changing the rangeCollection to represent the average 'height' over the elements previously in the collation. ie. the rangeCollection for a node becomes a single value representing a height that is the average height over all the elements previously in the collation.

Note:
average() will give the same result as normalise() if applied to a node where each element has total area = 1 (i.e the total area represented by all elements in the collation is equal to the number of elements in the collation), but not if those elements do not each have area 1.0.

Throws the following exceptions:

Precondition:
this is a root node with at least one element collated.
Postcondition:
this will have the same tree structure as before and the collation will include one element representing the average of the heights of the elements previously in the collation. 
{
    if ( getParent() != NULL ) {
      throw NonRootNode_Error(
      "CollatorSPnode::average()");
    }
    
    _average();
}
const CollatorSPnode * CollatorSPnode::findContainingNode ( const cxsc::rvector &  pt,
OPERATIONS_ON  childInd = ON_PARENT 
) const

Find the leaf node which would contain a data point.

Note:
for efficiency, there is no check that the data point given has the same dimension as this; the results of trying this operation with a point with incompatible dimensions are undefined.

Throws a NoBox_Error if this is empty.

Parameters:
pta data point.
childIndan indicator for whether the current node is a treated as a left or right child or a root. Defaults to ON_PARENT.
Returns:
a pointer to the node which would contain the point, or NULL if no node contains the point.
Precondition:
This should have a box to check for containment against. 
{
  if ( isEmpty() ) {
    throw NoBox_Error(
    "CollatorSPnode::findContainingNode(const cxsc::rvector&, OPERATIONS_ON)");
  }
  // start at the top
  const CollatorSPnode* retObj = NULL;
  
  if(nodeContains(pt, childInd)) {
    
    if(isLeaf()) {

      // give this node as return value
      retObj = this;

    } // end of isLeaf

    // if not a leaf and contains data
    // recurse on the children if any
    else {

      if(rightChild!=NULL && !rightChild->isEmpty()){
        
        retObj =
        (getRightChild())->findContainingNode(
          pt, ON_RIGHT);
        
      }
      // only try left if we did not find on the right
      if(retObj == NULL && leftChild!=NULL &&
                !leftChild->isEmpty()) {
        retObj =
        (getLeftChild())->findContainingNode(
          pt, ON_LEFT);
        
      }
    }

  } // end if node contains

  // will return null if does not contain the data
  
  return retObj;
}
std::vector< RealVec > & CollatorSPnode::getAllRangeCollections ( std::vector< RealVec > &  container) const

Fill in a container of height values for this and its descendants.

Fills in order this, left child and descendents, right child and descendants.

Returns:
The container, filled in for this and its descendants. 
{
  // fill in me and then recurse, left then right
  container.push_back( rangeCollection.getRangeCollectionValues() );
  
  if (hasLCwithBox()) getLeftChild()->getAllRangeCollections(container);
  if (hasRCwithBox()) getRightChild()->getAllRangeCollections(container);
  
  return container;
}
std::vector< const CollatorSPnode * > & CollatorSPnode::getConstLeaves ( std::vector< const CollatorSPnode * > &  leaves) const

Get a container of all descendent leaf nodes.

Will contain just this if this is a leaf.

Parameters:
leavesa reference to a container of node pointers to fill in.
Returns:
a reference to the container leaves filled with pointers to leaf nodes. 
{
  //if children, recurse on the children
  if (hasLCwithBox()) {
    getLeftChild()->getConstLeaves(leaves);
  }

  if (hasRCwithBox()) {
    getRightChild()->getConstLeaves(leaves);
  }

  // this is a leaf
  if (!hasLCwithBox() && !hasRCwithBox()) { 
    leaves.push_back(this);
  }
  return leaves;
}
cxsc::dotprecision & CollatorSPnode::getLeafNodeAbsAreaAccumulations ( cxsc::dotprecision &  areaAcc) const [protected, virtual]

Accumulates absolute value of leaf node areas.

One dot precision in vector for each histogram in collation. Accumulate results for over all the leaf descendents of this. 

{
  if (getLeftChild() != NULL) {
    areaAcc = getLeftChild()->getLeafNodeAbsAreaAccumulations(areaAcc);
  }
  if (getRightChild() != NULL) {
    areaAcc = getRightChild()->getLeafNodeAbsAreaAccumulations(areaAcc);
  }
  // add on our absolute value x vol if we are a leaf
  if ( isLeaf() ) {

    cxsc::real vol = nodeRealVolume();
    
    //RealVec ranges = rangeCollection.getRangeCollectionValues();
    
    cxsc::accumulate( areaAcc, cxsc::abs( getTotalRangeCollection() ), 
                  nodeRealVolume() );
  }
    
  return areaAcc;
}
VecDotPrec & CollatorSPnode::getLeafNodeAbsDiffToAvAreaAccumulations ( VecDotPrec &  areaAcc) const [protected, virtual]

Accumulates absolute value of differences of leaf node areas to the leaf node area of the average over the collation.

One dot precision in vector for each histogram in collation. Accumulate results for over all the leaf descendents of this. 

{
  if (getLeftChild() != NULL) {
    areaAcc = getLeftChild()->getLeafNodeAbsDiffToAvAreaAccumulations(areaAcc);
  }
  if (getRightChild() != NULL) {
    areaAcc = getRightChild()->getLeafNodeAbsDiffToAvAreaAccumulations(areaAcc);
  }
  // add on our absolute differences to av x vol if we are a leaf
  if ( isLeaf() ) {

    cxsc::real vol = nodeRealVolume();
    
    RealVec ranges = rangeCollection.getAbsDiffsToAverageRangeCollection();
    
    RealVecItr it = ranges.begin();
    VecDotPrecIt dpit;

    for (dpit = areaAcc.begin(); dpit < areaAcc.end(); dpit++) {

      cxsc::accumulate((*dpit), (*it), vol);

      it++;
    }
  }

  return areaAcc;
}
CollatorSPnode * CollatorSPnode::getLeftChild ( ) const

Accessor for the left child of a node.

Returns a pointer to leftChild node.

Reimplemented from subpavings::SPnode.

{ return (CollatorSPnode*) leftChild; }
CollatorSPnode * CollatorSPnode::getParent ( ) const

Accessor for the parent of a node.

Returns a pointer to parent node.

Reimplemented from subpavings::SPnode.

{ return (CollatorSPnode*) parent; }
CollatorSPnode * CollatorSPnode::getRightChild ( ) const

Accessor for the right child of a node.

Returns a pointer to rightChild node.

Reimplemented from subpavings::SPnode.

{ return (CollatorSPnode*) rightChild; }
cxsc::real CollatorSPnode::getTotalAbsValueTimesVol ( ) const [virtual]

Get the total 'area' represented by this collation.

The total area represented by the collation is defined as the the sum of (sum of [absolute] height values in collation) x vols for leaf nodes for which this is ancestor.

Returns:
The total 'area' represented by this. 
{
  // if everything is positive, value x vol for this is equal
  // to sum of leaf node values x vols
  cxsc::real result = getNodeAbsValueTimesVol();
  
  // but if not, and not a leaf, we have to accumulate the absolute values
  if (!isLeaf() && !checkNoNegativeTotalValues() ) {
    // start with an empty dot precision
    // as many copies of empty reals as there are histograms in collation
    cxsc::dotprecision accs(0.0);
    
    // use to accumulate leaf node absolute areas
    accs = getLeafNodeAbsAreaAccumulations(accs);
    
    result = cxsc::rnd( accs );
  }
  return result;
}
bool CollatorSPnode::isEmptyRangeCollection ( ) const [virtual]

Get whether this node has nothing collated.

Returns:
true if this has nothing collated, false otherwise. 
{ return rangeCollection.isEmpty(); }
std::ostream & CollatorSPnode::leafAverageOutputTabs ( std::ostream &  os,
int  prec = 5 
) const [protected, virtual]

Output for a node in a binary tree, tab-delimited.

Output intended for a txt file, in numeric form only. Outputs the average over the summary.

Replaces the format that that the cxsc::<< operator produces for interval vectors. The format used here produces alpha-numeric tab-delimited data. The format for an n-dimensional interval vector is

nodeName [tab] volume [tabl] average summary [tab] Inf(ivector[1]) [tab] Sup(ivector[1].[tab] . . [tab] Inf(ivector[n]) [tab] Sup(ivector[n]

Parameters:
osis the stream to send to
precis the precision used for printing, defaulting to 5 
{
  if( !isEmpty() ) { // do nothing if there is no box

    ivector thisBox = *theBox; // copy theBox

    // output the nodeName, nodeVolume
    os << nodeName;

    os << cxsc::SaveOpt;
    os << cxsc::Variable << cxsc::SetPrecision(prec+2,prec);
    
    os << "\t" << nodeRealVolume();
    // followed by the average
    os << "\t";
    rangeCollection.outputAverage(os, prec);

    // followed by intervals making up box using Inf & Sup
    // ie unlike cxsc output, there is no [  ] around them
    for (int i= Lb(thisBox); i <= Ub(thisBox) ; i++) {

      os << "\t" << Inf(thisBox[i])
        << "\t" << Sup(thisBox[i]);
    }
    os << cxsc::RestoreOpt;
  }
}
std::ostream & CollatorSPnode::leafOutputTabs ( std::ostream &  os) const [protected, virtual]

Print the details of a single leaf node, using tab delimiters

Parameters:
osis the stream to send to.

Reimplemented from subpavings::SPnode.

{
  if( !isEmpty() ) { // do nothing if there is no box

    ivector thisBox = *theBox; // copy theBox

    // output the nodeName, nodeVolume
    os << nodeName;
    
    os << "\t" << nodeRealVolume() << "\t";

    // followed by the rangeCollection
    rangeCollection.outputTabs(os);

    // followed by intervals making up box using Inf & Sup
    // ie unlike cxsc output, there is no [  ] around them
    for (int i= Lb(thisBox); i <= Ub(thisBox) ; i++) {

      os << "\t" << Inf(thisBox[i])
        << "\t" << Sup(thisBox[i]);
    }
  }
}
std::ostream & CollatorSPnode::leavesAverageOutputTabs ( std::ostream &  os,
int  prec = 5 
) const [virtual]

Output for for all leaves of a binary tree.

Output intended for a txt file, in numeric form only.

Outputs the average over the summary for each leaf.

Parameters:
osis the stream to send to.
precis the precision used for printing, defaulting to 5. 
{
  // uses  member function leafAverageOutputTabs for node output
  if (!(isEmpty()) && isLeaf()) { // this is a non-empty leaf
    leafAverageOutputTabs(os, prec);
    return (os << "\n");
  }

  //recurse on the children
  if (getLeftChild()!=NULL) {
    getLeftChild()->leavesAverageOutputTabs(os, prec);
  }

  if (getRightChild()!=NULL) {
    getRightChild()->leavesAverageOutputTabs(os, prec);
  }

}
const CollatorSPnode CollatorSPnode::makeAverage ( ) const

Make the average of this.

Averaging means making a rangeCollection to represent the average 'height' over the elements averaged. ie. the rangeCollection for a node is a single value representing a height that is the average height over all the elements in the collation to be averaged.

Throws an UnfulfillableRequest_Error if this has nothing collated.

Returns:
a collator with the same tree structure as this and a rangeCollection with one element representing the average of the heights of the elements in the equivalent node of this.
Precondition:
this has at least one element collated. 
{
  CollatorSPnode result = (*this);
  result._average();
  return result;

}
const CollatorSPnode CollatorSPnode::makeMarginalised ( const std::vector< int > &  reqDims) const

Make a marginalised version of this.

Makes a new collator that this the marginal of this, marginalising to take out the unwanted dimensions and adjust the rangeCollection for this so that for each element in the collation, sum of (node vol x 'height' collated) is the same as for this, and hence that the overall sum over all leaves of (node vol x accumulated 'heights' collated) is the same as this.

Note:
allowed dimensions start at 1, ie dimensions to marginalise on can include 1, 2, ... d where d = dimensions of this.

Throws the following exceptions:

  • Throws a NoBox_Error if this is empty (has no box).
  • Throws an std::invalid_argument if the required dimensions reqDim is empty or contains dimensions outside the range of the dimensions of this.
Parameters:
reqDimsis a vector of the dimensions to include in marginal.
Returns:
A collator with a subpaving that is the result of the marginalisation of the subpaving of this to include only the required dimensions and a rangeCollection with the same number of elements as this but where each 'height' is adjusted to preserve the area given the change in the volume of the subpaving box that the node represents compared to that in this.
Precondition:
reqDims must be compatible with current dimensions and this must have a box. 
{
  CollatorSPnode result = *this;

  result._start_marginalise(reqDims);
  
  return result;
}
const CollatorSPnode CollatorSPnode::makeNormalised ( ) const

Make the normalised version of this.

Normalising means changing the rangeCollection to represent the (normalised) 'height' of a single statistical subpaving. ie. the rangeCollection for a node becomes a single value such that the sum over all leaf nodes of the leaf node areas (node volume x 'height') is 1.0.

Note:
makeNormalised() will give the same result as makeAverage() if applied to a node where each element has total area = 1 (i.e the total area represented by all elements in the collation is equal to the number of elements in the collation), but not if those elements do not each have area 1.0

Throws the following exceptions:

Returns:
A collator with the same tree structure (subpaving) as this and one element in its collation such that the area represented by that element is 1.0.
Precondition:
this must have a box and at least one element collated and getTotalAbsValueTimesVol() != 0. 
{
  
  CollatorSPnode result = *this;

  result._normalise();
  
  return result;
}
void CollatorSPnode::marginalise ( const std::vector< int > &  reqDims) [virtual]

Marginalised this.

Marginalises to take out the unwanted dimensions and adjust the rangeCollection so that for each element in the collation, sum of (node vol x 'height' collated) is the same as before marginalisation, and hence that the overall sum over all leaves of (node vol x accumulated 'heights' collated) is the same as before marginalisation.

Note:
allowed dimensions start at 1, ie dimensions to marginalise on can include 1, 2, ... d where d = dimensions of this.

Throws the following exceptions:

  • Throws a NonRootNode_Error if this has a parent (ie. is not a root node).
  • Throws a NoBox_Error if this is empty (has no box).
  • Throws an std::invalid_argument if the required dimensions reqDim is empty or contains dimensions outside the range of the dimensions of this.
Parameters:
reqDimsis a vector of the dimensions to include in marginal.
Precondition:
reqDims must be compatible with current dimensions and this must be a root node (have no parent) with a box.
Postcondition:
This will have a tree structure that is the result of the marginalisation of the original subpaving to include only the required dimensions and will have a rangeCollection with the same number of elements as before marginalisation but where each 'height' is adjusted to preserve the area given the change in the volume of the subpaving box that the node represents. 
{
  if ( getParent() != NULL ) {
    throw NonRootNode_Error(
      "CollatorSPnode::marginalise(const std::vector<int>&)");
  }
  
  _start_marginalise(reqDims);
}
void CollatorSPnode::nodeExpand ( int  comp) [virtual]

Expand a leaf node.

Expand a leaf node to have two children and pass rangeCollection down to children.

Throws a NoBox_Error if this is empty.

Parameters:
compis the dimension on which to to bisect theBox.
Precondition:
this should be non-empty.

Reimplemented from subpavings::SPnode.

{
  
  // can only expand if there is a box
  if ( isEmpty() ) {
    throw NoBox_Error("CollatorSPnode::nodeExpand(int)");
  }

  // only do something if this node is a leaf
  if (isLeaf()) {
    
    CollatorSPnode* newLC = NULL;
    CollatorSPnode* newRC = NULL;
    
    try {
      // ivectors to become boxes for new children
      ivector lC, rC;
      // Call Lower() and Upper() to put split boxes
      // into lC and rC respectively
      Lower(getBox(), lC, comp);
      Upper(getBox(), rC, comp);
      
      // make and add the new children
      newLC = new CollatorSPnode(lC, rangeCollection);
      newRC = new CollatorSPnode(rC, rangeCollection);
      
      nodeAddLeft(newLC);
      nodeAddRight(newRC);
      // both children get the same rangeCollection as this

      //name the new children
      getLeftChild()->setNodeName(nodeName + "L");
      getRightChild()->setNodeName(nodeName + "R");

    }
    catch(std::exception& e) {
      // overkill, but try to deal with all eventualities...
      try {
        if (getLeftChild() != NULL) {
          delete (getLeftChild());
          leftChild = NULL;
        }
        
        if (getRightChild() != NULL) {
          delete (getRightChild());
          rightChild = NULL;
        }
        if (newLC != NULL) {
          delete newLC;
          newLC = NULL;
        }
        if (newRC != NULL) {
          delete newRC;
          newRC = NULL;
        }
      }
      catch(std::exception& e) {} //catch and swallow
      
      throw; // rethrow original exception
    }
  }
}
void CollatorSPnode::nodeExpand ( ) [virtual]

Expand a leaf node.

Expand a leaf node to have two children and pass rangeCollection down to children.

Finds the splitting dimension.

Reimplemented from subpavings::SPnode.

{
  int maxdiamcomp; // variable to hold first longest dimension
  double temp = ::MaxDiam(getBox(), maxdiamcomp);
  nodeExpand(maxdiamcomp); // complete nodeExpand
  
}
std::ostream & CollatorSPnode::nodePrint ( std::ostream &  os) const [virtual]

Print the details of a specific node in a subpaving

Parameters:
osis the stream to send to.

Reimplemented from subpavings::SPnode.

{
  // output for box in form:
  // box, volume, summary data

  if( !isEmpty() ) { // do nothing if there is no box
    
    ivector thisBox = *theBox; // copy theBox

    os << nodeName << "\tBox is:\t";

    for (int i = Lb(thisBox); i <= Ub(thisBox) ; i++) {
      // c-xsc default output for intervals
      os << "\t" << thisBox[i];   }

    os << "\tBox volume is:\t" << nodeRealVolume();
    os << "\trange data:\t" ;

    rangeCollection.outputTabs(os);

  }
  return os;
}
void CollatorSPnode::nodeRangeCollectionReduce ( ) [protected, virtual]

Reduce the rangeCollection for this node to a single value representing the heights of the elements originally represented in this's rangeCollection.

Non-recursive: operates on this node only, not descendants. 

{
    rangeCollection.reduce();
}
void CollatorSPnode::nodeScalarDiv ( cxsc::real &  div) [protected, virtual]

Divide the rangeCollection for this node by a scalar value.

Non-recursive: operates on this node only, not descendants. 

{
  if (!isEmpty()) {
    rangeCollection/=(div);
  }
}
void CollatorSPnode::nodeScalarMult ( cxsc::real &  mult) [protected, virtual]

Multiply the rangeCollection for this node by a scalar value.

Non-recursive: operates on this node only, not descendants. 

{
  if (!isEmpty()) {
    rangeCollection*=(mult);
    
  }
}
std::string CollatorSPnode::nodeStringSummary ( ) const [virtual]

Get a string summary of this node's properties.

Just this node, not this and its descendents.

Returns:
the string summary.

Reimplemented from subpavings::SPnode.

{
  std::ostringstream oss;
  
  oss << "I am " << getNodeName() << "(address " << this << "),\n";
  oss << "Dimension is " << getDimension() << ", address of box is " << theBox << "\n"; 
  oss << "address of rangeCollection is " << &rangeCollection << ", rangeCollection is ";
  outputNodeRangeCollection(oss) << "\n";
  oss << "my parent is ";
  if (getParent() != NULL) oss << getParent()->getNodeName();
  else oss << "NULL"; 
  oss << ", my left child is ";
  if (getLeftChild() != NULL) oss << getLeftChild()->getNodeName();
  else oss << "NULL"; 
  oss << ", my right child is ";
  if (getRightChild() != NULL) oss << getRightChild()->getNodeName();
  else oss << "NULL";
  
  return oss.str();
  
}
void CollatorSPnode::normalise ( ) [virtual]

Normalise this.

Normalising means changing the rangeCollection to represent the (normalised) 'height' of a single statistical subpaving. ie. the rangeCollection for a node becomes a single value such that the sum over all leaf nodes of the leaf node areas (node volume x 'height') is 1.0.

Note:
normalise() will give the same result as average if applied to a node where each element has total area = 1 (i.e the total area represented by all elements in the collation is equal to the number of elements in the collation), but not if those elements do not each have area 1.0

Throws the following exceptions:

Precondition:
this must be a root node (have no parent) with a box and at least one element collated and getTotalAbsValueTimesVol() != 0
Postcondition:
this will have the same tree structure as before and the collation will include one element and the area represented by that element will be 1.0. 
{
  if ( getParent() != NULL ) {
    throw NonRootNode_Error(
      "CollatorSPnode::normalise()");
  }
  
  _normalise();
  
}
const CollatorSPnode CollatorSPnode::operator* ( cxsc::real &  mult) const

Get the results of multiplying this collation by a scalar.

Each element in the rangeCollection for of the collation returned is the result of changing the rangeCollection of this so that each element represents a 'height' mult x the 'height' it represented before the operation.

Parameters:
multthe scalar multiplier to apply.
Returns:
A collation which has the same tree structure (subpaving structure) as this. Each element in the rangeCollection of the collation returned is the result of changing the rangeCollection of this so that each element represents a 'height' mult x the 'height' it represented before the operation. 
{
  CollatorSPnode result = *this;     
  result *= mult;            
  return result;
}
CollatorSPnode & CollatorSPnode::operator*= ( cxsc::real &  mult)

Multiply this collation by a scalar.

Each element in the rangeCollection for this is changed to represent a 'height' mult x the 'height' it represented before the operation.

Parameters:
multthe scalar multiplier to apply to this.
Postcondition:
The tree structure (subpaving structure) for this is unchanged. Each element in the rangeCollection for this is changed to represent a 'height' mult x the 'height' it represented before the operation. 
{
  selfScalarMult(mult);
  return *this;
}
const CollatorSPnode CollatorSPnode::operator+ ( const CollatorSPnode &  add) const

Add the contents of two collators together.

The collator returned has a tree structures (subpaving) that is teh non-minimal union of the trees of this and add. The collator returned has a rangeCollection that is the result of appending the rangeCollection for add to the end of this's rangeCollection.

Throws an IncompatibleDimensions_Error if both this and add have boxes and the dimensions or sizes of those boxes are not the same.

Parameters:
addthe root of the collator to be added to this.
Returns:
a collator with a tree structure (subpaving structure) that is the result of the non-minimal union of the tree structure (subpaving) for this and the tree structure (subpaving) for add. The rangeCollection for the collator returned is the result of appending the rangeCollection of add to the end of the rangeCollection for this.
Precondition:
If both this and rhs have boxes, those boxes should have the same dimensions and sizes. 
{
  CollatorSPnode result =(*this);
  
  result+= add;
  
  return result;
}
const CollatorSPnode CollatorSPnode::operator+ ( const SPSnode &  add) const

Add the contents of a collator and a statistical subpaving together.

The tree structures of the result is the non-minimal union of the tree structures of this and add. The rangeCollection of the result contains information about the 'height' of the equivalent node to this in add appended to the end of this's rangeCollection.

Throws an IncompatibleDimensions_Error if both this and add have boxes and the dimensions or sizes of those boxes are not the same.

Parameters:
addthe root of the statistical subpaving to be added to this.
Returns:
the result of adding a representation of the statistical subpaving add to this collation.
Precondition:
If both this and rhs have boxes, those boxes should have the same dimensions and sizes. 
{
  CollatorSPnode result =(*this);
  
  result+= add;
  
  return result;
}
CollatorSPnode & CollatorSPnode::operator+= ( const CollatorSPnode &  add)

Add the contents of another collator to this.

Tree structures are combined using a non-minimal union and the rangeCollection for add is appended to the end of this's rangeCollection. The effect is as though all the statistical subpavings collated by add had been collated into this.

Throws an IncompatibleDimensions_Error if both this and add have boxes and the dimensions or sizes of those boxes are not the same.

Parameters:
addthe root of the collator to be added to this.
Precondition:
If both this and rhs have boxes, those boxes should have the same dimensions and sizes.
Postcondition:
The tree structure (subpaving structure) for this becomes the result of the non-minimal union of the tree structure (subpaving) for this and the tree structure (subpaving) for add. The rangeCollection for add is appended to the end of the original rangeCollection for this. 
{
  this->addPaving(&add);
  return *this;
  
}
CollatorSPnode & CollatorSPnode::operator+= ( const SPSnode &  add)

Add a representation of a statistical subpaving into this collation.

Tree structures are combined using a non-minimal union and information about the 'height' of the equivalent node to this in add is appended to the end of this's rangeCollection.

Throws an IncompatibleDimensions_Error if both this and add have boxes and the dimensions or sizes of those boxes are not the same.

Parameters:
addthe root of the statistical subpaving to be added to this.
Precondition:
If both this and rhs have boxes, those boxes should have the same dimensions and sizes.
Postcondition:
The tree structure (subpaving structure) for this becomes the result of the non-minimal union of the tree structure (subpaving) for this and the tree structure (subpaving) for add. Information about the 'height' of the equivalent node to this in add is appended to the end of this's rangeCollection. 
{
  this->addPaving(&add);
  return *this;
}
const CollatorSPnode CollatorSPnode::operator/ ( cxsc::real &  div) const

Get the results of dividing this collation by a scalar.

Each element in the rangeCollection for of the collation returned is the result of changing the rangeCollection of this so that each element represents a 'height' = the 'height' it represented before the operation divided by div.

Throws a std::invalid_argument exception if div == 0.0.

Parameters:
divthe scalar divisor to apply.
Returns:
A collation which has the same tree structure (subpaving structure) as this. Each element in the rangeCollection of the collation returned is the result of changing the rangeCollection of this so that each element represents a 'height' = the 'height' it represented before the operation divided by div.
Precondition:
div != 0.0. 
{
  CollatorSPnode result = *this;     
  result /= div;            
  return result;
}
CollatorSPnode & CollatorSPnode::operator/= ( cxsc::real &  div)

Divide this collation by a scalar.

Each element in the rangeCollection for this is changed to represent the 'height' it represented before the operation divided by div.

Throws a std::invalid_argument exception if div == 0.0.

Parameters:
divthe scalar divisor to apply to this.
Precondition:
div != 0.0.
Postcondition:
The tree structure (subpaving structure) for this is unchanged. Each element in the rangeCollection for this is changed to represent a 'height' = the 'height' it represented before the operation divided by div. 
{
    selfScalarDiv(div);
    return *this;
}
CollatorSPnode & CollatorSPnode::operator= ( CollatorSPnode  rhs)

Copy assignment operator. 

{
  rhs.swapCollator(*this);
  return *this;
}
void CollatorSPnode::reduceCollation ( ) [virtual]

Reduce the rangeCollection of this to represent the sum of the heights of the statistical subpavings collated.

Postcondition:
If the before the operation the rangeCollection had > 1 values, then afterwars the rangeCollection will contain one value representing the sum of the heights of the statistical subpavings collated. If before the operation the rangeCollection had <= 1 elements, then is unchanged by the operation. 
{
  // reduce the range collection on this node
  nodeRangeCollectionReduce();
  // recurse on children
  if (hasLCwithBox())
    getLeftChild()->reduceCollation();
  if (hasRCwithBox())
    getRightChild()->reduceCollation();
}
void CollatorSPnode::swapCollator ( CollatorSPnode &  spn)

Swap this and another node.

Swaps all the data members of this with the other node.

Parameters:
spna reference to the node to swap with
Postcondition:
this is identical,in terms of its data members, to spn before the swap, and spn is identical to this after the swap. 
{
  /* theBox, parent, leftChild,
        rightChild and nodeName are inherited from base class */
    SPnode::swap(spn); // use the base version
    
    std::swap(rangeCollection, spn.rangeCollection);
        
}
The documentation for this class was generated from the following files:
 All Classes Namespaces Functions Variables Typedefs Enumerations Friends