A derived class based on MappedSPnode < cxsc::real >. More...

Inheritance diagram for subpavings::RealMappedSPnode:

Collaboration diagram for subpavings::RealMappedSPnode:

Classes
class	Measurer
	Inner interface for types measuring nodes. More...
Public Types

typedef std::vector < RealMappedSPnode * >	Ptrs
typedef Ptrs::iterator	PtrsItr
typedef std::vector< const RealMappedSPnode * >	ConstPtrs
typedef ConstPtrs::const_iterator	ConstPtrsItr
typedef std::list < RealMappedSPnode * >	ListPtrs
typedef ListPtrs::iterator	ListPtrsItr
typedef std::list< const RealMappedSPnode * >	ListConstPtrs
typedef ListConstPtrs::const_iterator	ListConstPtrsItr
Public Member Functions
virtual	~RealMappedSPnode ()
	Destructor.
	RealMappedSPnode ()
	No-argument constructor.
	RealMappedSPnode (const ivector &v)
	initialised constructor.
	RealMappedSPnode (const LabBox &lb)
	Initialised constructor.
	RealMappedSPnode (const ivector &v, const cxsc::real &range)
	Initialised constructor.
	RealMappedSPnode (const LabBox &lb, const cxsc::real &range)
	Initialised constructor.
	RealMappedSPnode (const SPnode &spn)
	Constructor initialised with an SPnode.
	RealMappedSPnode (const SPSnode &spn)
	RealMappedSPnode (const RealMappedSPnode &other)
	Copy constructor.
	RealMappedSPnode (const MappedSPnode< cxsc::real > &other)
	Copy constructor.
RealMappedSPnode &	operator= (RealMappedSPnode rhs)
	Copy assignment operator.
RealMappedSPnode &	operator= (MappedSPnode< cxsc::real > rhs)
	Copy assignment operator.
void	replaceMe (RealMappedSPnode newNode)
	Replace the properties of this node and its descendents with the properties of another node and its descendents.
void	replaceMe (MappedSPnode< cxsc::real > newNode)
	Replace the properties of this node and its descendents with the properties of another node and its descendents.
RealMappedSPnode *	getParent () const
	Accessor for the parent of a node.
RealMappedSPnode *	getLeftChild () const
	Accessor for the left child of a node.
RealMappedSPnode *	getRightChild () const
	Accessor for the right child of a node.
bool	operator< (const RealMappedSPnode &rhs) const
	Less-than operator.
const RealMappedSPnode *	findContainingNode (const cxsc::rvector &pt, OPERATIONS_ON childInd=ON_PARENT) const
bool	hasNegativeRangeInTree () const
bool	hasInfiniteRangeInTree () const
std::pair< size_t, cxsc::real >	getNonZeroBoxSummary () const
	Get summary information on non-zero (ie value <> 0.0) leaf box numbers and volumes.
void	smearRanges (cxsc::real zeroRange, cxsc::real ratioRange)
	Smear the ranges of the tree rooted at this so that no leaf node in this has range == 0.0 but the value of getTotalAbsLeafAreaRangeWithBox() is unchanged.
virtual void	nodeExpand (int comp)
	Add two sibling child nodes to this provided this is a leaf.
virtual void	nodeExpand ()
	Add two sibling child nodes to this provided this is a leaf.
virtual cxsc::real	getMaxRangeForLeavesInTree () const
	Get maximum value of the range for any of the leaves of the tree rooted at this.
virtual cxsc::real	setRandomRange (gsl_rng *const rgsl, size_t myDepth=0)
	Set a randomly-derived range on each node of the tree rooted at this.
virtual void	marginalise (const std::vector< int > &reqDims)
	Marginalise this.
const RealMappedSPnode	makeMarginalised (const std::vector< int > &reqDims) const
	Make a marginalised version of this.
virtual void	normalise ()
	Normalise this.
const RealMappedSPnode	makeNormalised () const
	Make a normalised version of this.
cxsc::real	getL1Distance (const RealMappedSPnode &other) const
cxsc::real	getLogLikelihood (const SPSnode &spn) const
	Get a 'log likelihood' using positive values from this and counts from spn.
virtual cxsc::real	getRealAreaRangeWithBox () const
	Get the "area" of the range and the box of this.
virtual cxsc::dotprecision	getDotPrecisionAreaRangeWithBox () const
	Get the "area" of the range and the box of this as a dotprecision type.
virtual cxsc::real	getTotalLeafAreaRangeWithBox () const
	Get the total "area" for the leaves of this of the real ranges and boxes.
virtual cxsc::dotprecision	getTotalDotPrecisionLeafAreaRangeWithBox () const
	Get the total "area" of the range and the box of this as a dotprecision type.
virtual cxsc::real	getTotalAbsLeafAreaRangeWithBox () const
	Get the total absolute "area" for the leaves of this of the real ranges and boxes.
virtual cxsc::dotprecision	getTotalDotPrecisionAbsLeafAreaRangeWithBox () const
	Get the total absolute "area" of the range and the box of this as a dotprecision type.
virtual cxsc::real	getTotalAbsDiffLeafAreaRangeWithBox (const RealMappedSPnode &rmsp) const
	Get the total over the leaves of the absolute value of the difference between the leaf "area" for this and for rmsp.
virtual cxsc::dotprecision	getTotalDotPrecisionAbsDiffLeafAreaRangeWithBox (const RealMappedSPnode &rmsp) const
	Get the total over the leaves of the absolute value of the difference between the leaf "area" for this and for rmsp as a dotprecision type.
Ptrs &	getLeaves (Ptrs &leaves)
	Return a reference to a container of nodes.
ConstPtrs &	getConstLeaves (ConstPtrs &leaves) const
	Return a reference to a container of const nodes.
Ptrs &	getSubLeaves (Ptrs &subleaves)
	Return a reference to a container of nodes.
ConstPtrs &	getConstSubLeaves (ConstPtrs &subleaves) const
	Return a reference to a container of const nodes.
void	swapRMSPSR (RealMappedSPnode &spn)

Detailed Description

A derived class based on MappedSPnode < cxsc::real >.

The base class MappedSPnode is a node in the representation of a mapped regular subpaving as a binary tree, where the type mapped to the nodes is a real. A node represents a box (interval vector). MappedSPnodes 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. Each node will have a single real value mapped to it.

A RealMappedSPnode provides the functionality of the MappedSPNode <real> and extended functionality appropriate for real mapped nodes, such as marginalisation.

Note that arithmetical operations with non-real operands can take place provided that there is an implicit conversion from the operand type to a cxsc::real, eg the operations this += 2 or this + 2 will give the same results as this += cxsc::real(2.0) or this + cxsc::real(2.0) respectively, because there is a implicit conversion from an integer to a cxsc::real in the cxsc library. Similarly, operations with operands of type double will also succeed.

Member Typedef Documentation

typedef std::vector<RealMappedSPnode* > subpavings::RealMappedSPnode::Ptrs

@ name Definitions for collection types for RealMappedSPnodes

Constructor & Destructor Documentation

RealMappedSPnode::RealMappedSPnode ( const ivector & v ) [explicit]

initialised constructor.

Initialised with a box. Range is set to 0.0.

  : MappedSPnode<cxsc::real>(v, real(0.0)) {}

RealMappedSPnode::RealMappedSPnode ( const LabBox & lb ) [explicit]

Initialised constructor.

Initialised with a labeled box. Range is set to 0.0.

  : MappedSPnode<cxsc::real>(lb, real(0.0)) {}

RealMappedSPnode::RealMappedSPnode	(	const ivector &	v,
		const cxsc::real &	range
	)

Initialised constructor.

Initialised with a box and and a real value for the range.

  : MappedSPnode<cxsc::real>(v, range) {}

RealMappedSPnode::RealMappedSPnode	(	const LabBox &	lb,
		const cxsc::real &	range
	)

Initialised constructor.

Initialised with a labeled box and a real value for the rangeCollection.

  : MappedSPnode<cxsc::real>(lb, range) {}

RealMappedSPnode::RealMappedSPnode ( const SPnode & spn ) [explicit]

Constructor initialised with an SPnode.

Range is set to csxc::real(0.0);

Parameters:

spn	An SPnode to copy.

Precondition:: spn must have a box.

Postcondition:: This has a subpaving identical to spn and the value mapped onto each node of this is 0.0.

{
  if (!spn.isEmpty()) { 
    theBox = new ivector( spn.getBox() );
  }
  nodeName = spn.getNodeName();
  range = 0.0;
  
  //recursion on the children
  if (spn.hasLCwithBox()) {
    nodeAddLeft(new RealMappedSPnode(
      *(spn.getLeftChild())));
  }
  else leftChild=NULL;

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

}

RealMappedSPnode::RealMappedSPnode ( const SPSnode & spn ) [explicit]

Constructor initialised with an SPSnode.

A NoBox_Error is thrown if other has no box.

Parameters:

spn	An SPSnode to copy.

Precondition:: spn must have a box.

Postcondition:: This has a subpaving identical to spn and the value mapped onto each node of this is the value of count/nodeVolume from the equivalent node in spn.

{
  if (!spn.isEmpty()) { 
    theBox = new ivector( spn.getBox() );
  }
  nodeName = spn.getNodeName();
  range = (1.0*spn.getCounter()/nodeRealVolume());
  
  //recursion on the children
  if (spn.hasLCwithBox()) {
    nodeAddLeft(new RealMappedSPnode(
      *(spn.getLeftChild())));
  }
  else leftChild=NULL;

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

}

RealMappedSPnode::RealMappedSPnode ( const RealMappedSPnode & other )

Copy constructor.

Copies from given RealMappedSPnode downwards.

{
  
  if (other.theBox != NULL) {
    theBox = new ivector( other.getBox() );
  }
  nodeName = other.getNodeName();
  range = other.getRange();
  
  //recursion on the children
  if (other.hasLCwithBox()) {
    nodeAddLeft(new RealMappedSPnode(
      *(other.getLeftChild())));
  }
  else leftChild=NULL;

  if (other.hasRCwithBox()) {
    nodeAddRight(new RealMappedSPnode(
      *(other.getRightChild())));
  }
  else rightChild=NULL;

}

RealMappedSPnode::RealMappedSPnode ( const MappedSPnode< cxsc::real > & other )

Copy constructor.

Copies from a given MappedSPnode<cxsc::real> node downwards.

{
  if (!other.isEmpty()) {
    theBox = new ivector( other.getBox() );
  }
  nodeName = other.getNodeName();
  range = other.getRange();
  
  //recursion on the children
  if (other.hasLCwithBox()) {
    nodeAddLeft(new RealMappedSPnode(
      *(other.getLeftChild())));
  }
  else leftChild=NULL;

  if (other.hasRCwithBox()) {
    nodeAddRight(new RealMappedSPnode(
      *(other.getRightChild())));
  }
  else rightChild=NULL;
}

Member Function Documentation

const RealMappedSPnode * RealMappedSPnode::findContainingNode	(	const cxsc::rvector &	pt,
		OPERATIONS_ON	childInd = `ON_PARENT`
	)		const

Get a pointer to the leaf node descendent of this whose box contains the point pt.

Returns:: NULL if no leaf node descendent of this contains pt, otherwise a pointer to the leaf node descendent of this whose box contains the point pt.

{
  if ( isEmpty() ) {
    throw NoBox_Error(
    "RealMappedSPnode::findContainingNode(const cxsc::rvector&, OPERATIONS_ON)");
  }
  // start at the top
  const RealMappedSPnode* 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(hasRCwithBox()){
        
        retObj =
        (getRightChild())->findContainingNode(
          pt, ON_RIGHT);
        
      }
      // only try left if we did not find on the right
      if(retObj == NULL && hasLCwithBox()) {
        retObj =
        (getLeftChild())->findContainingNode(
          pt, ON_LEFT);
        
      }
    }

  } // end if node contains

  // will return null if does not contain the data
  
  return retObj;
}

RealMappedSPnode::ConstPtrs & RealMappedSPnode::getConstLeaves ( RealMappedSPnode::ConstPtrs & leaves ) const

Return a reference to a container of const nodes.

Contents of container are the leaves descended from this, or this if this is a leaf, left to right order.

{
  //if children, recurse on the children
  if (hasLCwithBox()) {
    getLeftChild()->getConstLeaves(leaves);
  }

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

  if ( isLeaf() ) { // this is a leaf
    leaves.push_back(this);
  }
  return leaves;
}

RealMappedSPnode::ConstPtrs & RealMappedSPnode::getConstSubLeaves ( RealMappedSPnode::ConstPtrs & subleaves ) const

Return a reference to a container of const nodes.

Contents of container are the sub-leaves descended from this, or this if this is a sub-leaf, left to right order.

A sub-leaf (aka "cherry") is a node with two leaf child nodes.

{
  if (isSubLeaf()) { // this is a subleaf
    subleaves.push_back(this);
  }
  //if children, recurse on the children
  else if (!isLeaf()) {
    getLeftChild()->getConstSubLeaves(subleaves);
    getRightChild()->getConstSubLeaves(subleaves);
  }

  
  return subleaves;
  
}

cxsc::dotprecision RealMappedSPnode::getDotPrecisionAreaRangeWithBox ( ) const [virtual]

Get the "area" of the range and the box of this as a dotprecision type.

The "area" returned should be the dotprecision product of the volume of the box represented by this and the real range of this. But note that if the range is cxsc::Infinity, the dotprecision result is the same as dotprecision(0.0). This is due to the working of the cxsc library. The results can therefore be highly misleading if the range is cxsc::Infinity

Returns:: dotprecision product of volume of box represented by this and real range of this.

Precondition:: Range of this is not cxsc::Infinity.; this must have a boxe.

{
  cxsc::dotprecision result(0.0);
  cxsc::accumulate(result, getRange(), nodeRealVolume());
  return result;
}

cxsc::real RealMappedSPnode::getL1Distance ( const RealMappedSPnode & other ) const

Gets the L1 distance between this and another RealMappedSPnode.

The L1 distance is defined as the sum of the absolute values of the differences in 'area' represented by the leaf nodes of this and the other paving. The 'area' represented by a leaf node is the absolute value mapped to that leaf node multiplied by the volume of the box associated with the node.

Throws the following exceptions:

Throws a NoBox_Error if either this or by other have no box.
Throws a IncompatibleDimensions_Error if the dimensions and sizes of the boxes of this and other are not the same.

Note:: This will not attempt to adjust for any difference in total integral between this and other: the L1 distance is simply taken as the difference between the 'areas' of the leaf boxes.; If this or other has leaf nodes with infinite ranges then the L1 distance between them will be infinite (cxsc::Infinity).

Parameters:

other the root of a RealMappedSPnode tree to calculate the L1 distance against.

Precondition:: Both this and other must have boxes and those boxes must be the same.

Postcondition:: this will be unchanged.

{
  if ( isEmpty() || other.isEmpty() ) {
    throw NoBox_Error(
      "RealMappedSPnode::getL1Distance(const RealMappedSPnode&)");
  }
  
  if ( getBox() != other.getBox() ) {
    throw IncompatibleDimensions_Error(
      "RealMappedSPnode::getL1Distance(const RealMappedSPnode&)");
  }
  
  
  
  cxsc::dotprecision retDP(0.0);
  
  if (this != & other) retDP = _getL1distance(retDP, &other);
  
  return cxsc::rnd(retDP);
    
}

RealMappedSPnode::Ptrs & RealMappedSPnode::getLeaves ( RealMappedSPnode::Ptrs & leaves )

Return a reference to a container of nodes.

Contents of container are the leaves descended from this, or this if this is a leaf, left to right order.

{
  //if children, recurse on the children
  if (hasLCwithBox()) {
    getLeftChild()->getLeaves(leaves);
  }

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

  if ( isLeaf() ) { // this is a leaf
    leaves.push_back(this);
  }
  return leaves;
}

RealMappedSPnode * RealMappedSPnode::getLeftChild ( ) const

Accessor for the left child of a node.

Returns a copy of the pointer to leftChild node.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{ return (RealMappedSPnode*) leftChild; }

cxsc::real RealMappedSPnode::getLogLikelihood ( const SPSnode & spn ) const

Get a 'log likelihood' using positive values from this and counts from spn.

Treats the rages mapped onto the nodes of this like function values and uses the counts from spn together with these values to calculate a 'log-likelihood'.

If range < 0.0 (including -infinity) is encountered for any leaf where spn has points, the method will return cxsc::SignalingNaN. Otherwise if range == 0.0 is encountered for any leaf where spn has points, the method will return -cxsc::Infinity. Otherwise if range == infinity is encountered for any leaf where spn has points, the method will return -cxsc::Infinity.

Parameters:

spn	is the root of an SPSnode tree which provides information about counts.

Returns:: the sum over the leaf nodes with positive values in the intersection of the tree rooted at this and the tree rooted at spn of the product of the log of the value on the leaf descendent of this and the count on the corresponding leaf descendent of spn. Returns cxsc::SignalingNaN if negative ranges are encountered, else returns -cxsc::Infinity if zero ranges are encountered, else returns cxsc::Infinity if any infinite ranges are encountered.

Precondition:: this and spn are both non-empty and both have the same box.

{
  if ( isEmpty() || spn.isEmpty() ) {
    throw NoBox_Error(
      "RealMappedSPnode::getLogLikelihood(const SPSnode&)");
  }
  
  if ( getBox() != spn.getBox() ) {
    throw IncompatibleDimensions_Error(
      "RealMappedSPnode::getLogLikelihood(const SPSnode&)");
  }
  cxsc::real result(0.0);
  
  if (spn.getCounter() > 0) {
    
    cxsc::dotprecision loglik(0.0);
    
    int isnan = 0;
    int isposinf =0;
    int isneginf =0; // all these 3 changed by ref
    
    _getLogLikelihood(loglik, isnan, isposinf, isneginf, &spn);
    
    /*nan if nan flag is set*/
    if (isnan ) result = cxsc::SignalingNaN;
    else result = cxsc::rnd(loglik);
    /* result could be -inf if there are 0 ranges in tree where spn 
     * has points or inf if there are inf ranges in tree where spn has points*/ 
  }

  return result;
}

cxsc::real RealMappedSPnode::getMaxRangeForLeavesInTree ( ) const [virtual]

Get maximum value of the range for any of the leaves of the tree rooted at this.

Returns the range of this if this is a leaf.

Returns:: maximum value of the range for any of the leaves of the tree rooted at this.

{
  if (isLeaf()) {
    return getRange();
  }
  else {
    cxsc::real rLC = getLeftChild()->getMaxRangeForLeavesInTree();
    cxsc::real rRC = getRightChild()->getMaxRangeForLeavesInTree();
    return (rLC > rRC? rLC : rRC);
  }
}

std::pair< size_t, cxsc::real > RealMappedSPnode::getNonZeroBoxSummary ( ) const

Get summary information on non-zero (ie value <> 0.0) leaf box numbers and volumes.

Returns:: A pair, where the first value in the pair is the total number of non-zero leaf boxes in the tree rooted at this, and the second value is the proportion of the total volume of this that is in the non-zero leaf boxes in the tree rooted at this.

{
  if(isEmpty()) 
    throw NoBox_Error("RealMappedSPnode::getNonZeroBoxSummary");
    
  size_t nNonZeroBoxes = 0;
  real vNonZeroBoxVolumes(0.0);
  
  accumulateNonZeroBoxSummary(nNonZeroBoxes, vNonZeroBoxVolumes);
  
  return std::pair <size_t, real >(nNonZeroBoxes, 
                vNonZeroBoxVolumes/nodeRealVolume());
  
}

RealMappedSPnode * RealMappedSPnode::getParent ( ) const

Accessor for the parent of a node.

Returns a copy of the pointer to parent node.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{ return (RealMappedSPnode*) parent; }

cxsc::real RealMappedSPnode::getRealAreaRangeWithBox ( ) const [virtual]

Get the "area" of the range and the box of this.

The "area" returned is calculated as the volume of the box represented by this multiplied by the real range of this (which can also be seen as the volume of the box represented by this with another dimension equal to an interval that has Inf 0 and Sup equal to the range of this).

Returns:: volume of box represented by this multiplied by real range of this.

Precondition:: this must have a boxe.

{
  return getRange() * nodeRealVolume();
}

RealMappedSPnode * RealMappedSPnode::getRightChild ( ) const

Accessor for the right child of a node.

Returns a copy of the pointer to rightChild node.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{ return (RealMappedSPnode*) rightChild; }

RealMappedSPnode::Ptrs & RealMappedSPnode::getSubLeaves ( RealMappedSPnode::Ptrs & subleaves )

Return a reference to a container of nodes.

Contents of container are the sub-leaves descended from this, or this if this is a sub-leaf, left to right order.

A sub-leaf (aka "cherry") is a node with two leaf child nodes.

{
  if (isSubLeaf()) { // this is a subleaf
    subleaves.push_back(this);
  }
  
  //if children, recurse on the children
  else if (!isLeaf()) {
    getLeftChild()->getSubLeaves(subleaves);
    getRightChild()->getSubLeaves(subleaves);
  }

  return subleaves;
  
}

cxsc::real RealMappedSPnode::getTotalAbsDiffLeafAreaRangeWithBox ( const RealMappedSPnode & rmsp ) const [virtual]

Get the total over the leaves of the absolute value of the difference between the leaf "area" for this and for rmsp.

For each leaf descendent of the subpaving union of this and rmsp the "area" returned is calculated as the volume of the box represented multiplied by the absolute value of the difference between the range on that leaf for this and for rmsp real.

This method should return the same as if the method getTotalAbsLeafAreaRangeWithBox() was called on a node which is the difference between this and rmsp (ie *this - rmsp).

If there are an infinite ranges in the tree rooted at this, or rmps, the method will return cxsc::Infinity.

Parameters:

rmsp	the RealMappedSPnode to calculate the difference against.

Returns:: total over the leaves of the union of this and rmsp of the absolute value of the difference between the leaf "area" for this and for rmsp (returns cxsc::Infinity if hasInfiniteRangeInTree() or if rmsp.hasInfiniteRangeInTree()).

Precondition:: this and rmsp have the same box.; all leaf descendents of this and rmsp must have boxes.

{
  cxsc::real total = cxsc::Infinity;
  
  if (!hasInfiniteRangeInTree() && !rmsp.hasInfiniteRangeInTree()) {
    RealMappedSPnode diff = *this - rmsp;
    total = diff.getTotalAbsLeafAreaRangeWithBox();
    
  }
  return total;
}

cxsc::real RealMappedSPnode::getTotalAbsLeafAreaRangeWithBox ( ) const [virtual]

Get the total absolute "area" for the leaves of this of the real ranges and boxes.

For each leaf descendent of this the "area" returned is calculated as the volume of the box represented multiplied by the absolute value of the real range of the node (which can also be seen as the volume of the box represented with another dimension equal to an interval that has Inf 0 and Sup equal to the range of the node).

If there are an infinite ranges in the tree rooted at this, the method will return cxsc::Infinity.

Returns:: total over all leaf descendents of this of abs(volume of box represented multiplied by real range) (returns cxsc::Infinity if hasInfiniteRangeInTree()).

Precondition:: all leaf descendents of this must have boxes.

{
  cxsc::real total = cxsc::Infinity;
  
  if (!hasInfiniteRangeInTree()) {
    total = rnd(getTotalDotPrecisionAbsLeafAreaRangeWithBox());
  }
  
  return total;
}

cxsc::dotprecision RealMappedSPnode::getTotalDotPrecisionAbsDiffLeafAreaRangeWithBox ( const RealMappedSPnode & rmsp ) const [virtual]

Get the total over the leaves of the absolute value of the difference between the leaf "area" for this and for rmsp as a dotprecision type.

For each leaf descendent of the subpaving union of this and rmsp the "area" returned is calculated as the volume of the box represented multiplied by the absolute value of the difference between the range on that leaf for this and for rmsp real. But note that if the range of a leaf node of this or rmsp is cxsc::Infinity, the dotprecision result for that leaf is the same as dotprecision(0.0). This is due to the working of the cxsc library. The results can therefore be highly misleading if any leaf node in this or rmsp has range cxsc::Infinity.

This method should return the same as if the method getTotalDotPrecisionAbsLeafAreaRangeWithBox() was called on a node which is the difference between this and rmsp (ie *this - rmsp).

Parameters:

rmsp	the RealMappedSPnode to calculate the difference against.

Returns:: dotprecision sum over the leaves of the union of this and rmsp of the absolute value of the difference between the leaf "area" for this and for rmsp.

Precondition:: this and rmsp have the same box.; !hasInfiniteRangeInTree() and !rmsp.hasInfiniteRangeInTree().; all leaf descendents of this and rmsp must have boxes.

{
  RealMappedSPnode diff = *this - rmsp;
  return diff.getTotalDotPrecisionAbsLeafAreaRangeWithBox();
}

cxsc::dotprecision RealMappedSPnode::getTotalDotPrecisionAbsLeafAreaRangeWithBox ( ) const [virtual]

Get the total absolute "area" of the range and the box of this as a dotprecision type.

The "area" returned should be the sum over all the leaves of this of the absolute value of the dotprecision product of the volume of the box represented by the leaf node and the real range of the leaf note. But note that if the range of a leaf node is cxsc::Infinity, the dotprecision result for that leaf is the same as dotprecision(0.0). This is due to the working of the cxsc library. The results can therefore be highly misleading if any leaf node has range cxsc::Infinity.

Returns:: dotprecision sum over leaf nodes of absolute value of the dotprecision product of volume of box represented by the leaf and the range of the leaf.

Precondition:: !hasInfiniteRangeInTree().; all leaf descendents of this must have boxes.

{
  if (isLeaf()) return cxsc::abs(getDotPrecisionAreaRangeWithBox());
  else {
    
    return ( getLeftChild()->getTotalDotPrecisionAbsLeafAreaRangeWithBox()
      + getRightChild()->getTotalDotPrecisionAbsLeafAreaRangeWithBox() );
    
  }
}

cxsc::dotprecision RealMappedSPnode::getTotalDotPrecisionLeafAreaRangeWithBox ( ) const [virtual]

Get the total "area" of the range and the box of this as a dotprecision type.

The "area" returned should be the sum over all the leaves of this of the dotprecision product of the volume of the box represented by the leaf node and the real range of the leaf note. But note that if the range of a leaf node is cxsc::Infinity, the dotprecision result for that leaf is the same as dotprecision(0.0). This is due to the working of the cxsc library. The results can therefore be highly misleading if any leaf node has range cxsc::Infinity.

Returns:: dotprecision sum over leaf nodes of dotprecision product of volume of box represented by the leaf and the range of the leaf.

Precondition:: !hasInfiniteRangeInTree().; all leaf descendents of this must have boxes.

{
  if (isLeaf()) return getDotPrecisionAreaRangeWithBox();
  else {
    return ( getLeftChild()->getTotalDotPrecisionLeafAreaRangeWithBox()
      + getRightChild()->getTotalDotPrecisionLeafAreaRangeWithBox() );
  }
}

cxsc::real RealMappedSPnode::getTotalLeafAreaRangeWithBox ( ) const [virtual]

Get the total "area" for the leaves of this of the real ranges and boxes.

For each leaf descendent of this the "area" returned is calculated as the volume of the box represented multiplied by the real range of the node (which can also be seen as the volume of the box represented with another dimension equal to an interval that has Inf 0 and Sup equal to the range of the node).

If there are an infinite ranges in the tree rooted at this, the method will return cxsc::Infinity.

Returns:: total over all leaf descendents of this of (volume of box represented multiplied by real range) (returns cxsc::Infinity if hasInfiniteRangeInTree()).

Precondition:: all leaf descendents of this must have boxes.

{
  cxsc::real total = cxsc::Infinity;
  
  if (!hasInfiniteRangeInTree()) {
    total = rnd(getTotalDotPrecisionLeafAreaRangeWithBox());
  }
  
  return total;

}

bool RealMappedSPnode::hasInfiniteRangeInTree ( ) const

Get whether there is an infinite range in the tree rooted at this. The tree rooted at this includes this node, subterminal nodes and leaf nodes).

Returns:: true if the tree rooted at this has a node with an infinite range (ie range cxsc::Infinity) .

{
  bool retValue = false;
  if (range == cxsc::Infinity) {
    retValue = true;
  }
  else if (!isLeaf()) {
    retValue = getLeftChild()->hasInfiniteRangeInTree();
    if (!retValue) retValue = getRightChild()->hasInfiniteRangeInTree();
  }
  return retValue;
  
}

bool RealMappedSPnode::hasNegativeRangeInTree ( ) const

Get whether there is a negative range in the tree rooted at this. The tree rooted at this includes this node, subterminal nodes and leaf nodes).

Returns:: true if the tree rooted at this has a node with a negative range.

{
  bool retValue = false;
  if (range < real(0.0)) {
    retValue = true;
  }
  else if (!isLeaf()) {
    retValue = getLeftChild()->hasNegativeRangeInTree();
    if (!retValue) retValue = getRightChild()->hasNegativeRangeInTree();
  }
  return retValue;
  
}

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

Make a marginalised version of this.

Makes a new RealMappedSPnode tree that s the marginal of this, marginalising to take out the unwanted dimensions and adjust the range so that node vol x range is the same as before, and does this recursively for all children so that after the marginalisation the sum over all leaves of (node vol x range) of the new tree is the same as for 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:

reqDims is a vector of the dimensions to include in marginal.

Returns:: A RealMappedSPnode with a subpaving that is the result of the marginalisation of the subpaving of this to include only the required dimensions and a range adjusted to preserve the range x node volume 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.

{
  RealMappedSPnode result = *this;

  result._start_marginalise(reqDims);
  
  return result;
}

const RealMappedSPnode RealMappedSPnode::makeNormalised ( ) const

Make a normalised version of this.

Makes a new RealMappedSPnode tree that is the normalised version of this, ie has the same subpaving but the total over all leaf nodes of the sum of (box volumes x range) is 1.0.

Throws the following exceptions:

Throws a NoBox_Error if this is empty (has no box).
Throws an std::runtime_error if this has no 'area', ie getTotalAbsLeafAreaRangeWithBox() <= 0.
Throws an std::runtime_error if this has no 'area', ie getTotalAbsLeafAreaRangeWithBox() == Infinity.

Returns:: A RealMappedSPnode with a subpaving that is the the same as the subpaving of this this with ranges such that the total over all leaf nodes of the sum of (box volumes x range) is 1.0.

Precondition:: this must have a box and getTotalAbsLeafAreaRangeWithBox() != 0 and getTotalAbsLeafAreaRangeWithBox() != Infinity.

{
  RealMappedSPnode result = *this;

  result._normalise();
  
  return result;
}

void RealMappedSPnode::marginalise ( const std::vector< int > & reqDims ) [virtual]

Marginalise this.

Marginalises to take out the unwanted dimensions and adjust the range so that node vol x range is the same as before marginalisation, and does this recursively for all children of this so that after the marginalisation the sum over all leaves of (node vol x range) 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:

reqDims is 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 range adjusted to preserve the total range x volume given the change in the volume of the subpaving box that the node represents.

{
  if ( getParent() != NULL ) {
    throw NonRootNode_Error(
      "RealMappedSPnode::marginalise(const std::vector<int>&)");
  }
  
  _start_marginalise(reqDims);
}

void RealMappedSPnode::nodeExpand ( int comp ) [virtual]

Add two sibling child nodes to this provided this is a leaf.

Each new child gets half of the box associated with this, splitting the box in half normal to dimension set by comp.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{
  // can only expand if there is a box
  if (NULL == theBox) {
    throw NoBox_Error("RealMappedSPnode::nodeExpand(int)");
  }

  // only do something if this node is a leaf
  if (isLeaf()) {
    
    RealMappedSPnode* newLC = NULL;
    RealMappedSPnode* 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 RealMappedSPnode(lC, range);
      newRC = new RealMappedSPnode(rC, range);
      
      nodeAddLeft(newLC);
      nodeAddRight(newRC);
      // both children get the same range as this
      
      //name the new children
      getLeftChild()->setNodeName(nodeName + "L");
      getRightChild()->setNodeName(nodeName + "R");

      // new children have summary from this
    }
    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 RealMappedSPnode::nodeExpand ( ) [virtual]

Add two sibling child nodes to this provided this is a leaf.

Each new child gets half of the box associated with this, splitting the box in half normal to the first longest dimension of the box associated with this.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{
  int maxdiamcomp; // variable to hold first longest dimension
  double temp = ::MaxDiam(getBox(), maxdiamcomp);
  nodeExpand(maxdiamcomp); // complete nodeExpand
}

void RealMappedSPnode::normalise ( ) [virtual]

Normalise this.

Normalising means changing the range of each node so that the total over all leaf nodes of the sum of (box volumes xabs(range)) is 1.0.

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::runtime_error if this has no 'area', ie getTotalAbsLeafAreaRangeWithBox() <= 0.
Throws an std::runtime_error if this has no 'area', ie getTotalAbsLeafAreaRangeWithBox() == Infinity.

Precondition:: this must be a root node (have no parent) with a box and getTotalAbsLeafAreaRangeWithBox() != 0 and getTotalAbsLeafAreaRangeWithBox() != Infinity.

Postcondition:: this will have the same tree structure as before and the ranges on the nodes will be adjusted so that getTotalAbsLeafAreaRangeWithBox() = 1.0.

{
  if ( getParent() != NULL ) {
    throw NonRootNode_Error(
      "RealMappedSPnode::normalise()");
  }
  _normalise();
}

bool RealMappedSPnode::operator< ( const RealMappedSPnode & rhs ) const

Less-than operator.

Returns:: true iff the range of this is < range of rhs.

{
  return (getRange() < rhs.getRange());
}

RealMappedSPnode & RealMappedSPnode::operator= ( RealMappedSPnode rhs )

Copy assignment operator.

Copies from given RealMappedSPnode downwards.

{
  rhs.swapRMSPSR(*this); // make sure we use our version of swap
  return(*this);
}

RealMappedSPnode & RealMappedSPnode::operator= ( MappedSPnode< cxsc::real > rhs )

Copy assignment operator.

Copies from a given MappedSPnode<cxsc::real> node downwards.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{
  rhs.swapMSPSR(*this); // make sure we use our version of swap
  return(*this);
}

void RealMappedSPnode::replaceMe ( RealMappedSPnode newNode )

Replace the properties of this node and its descendents with the properties of another node and its descendents.

Copies newNode node downwards into this, but keeps the relationship of this with its parent, ie if this is a node in a tree, the part of the tree rooted at this is made identical to newNode but the relationship to the rest of the tree,through the link between this and its parent, is retained.

{
  
  RealMappedSPnode* pNode = getParent();
  newNode.swapRMSPSR(*this);
  
  if (NULL != pNode) {
    
    this->parent = pNode;
  }
}

void RealMappedSPnode::replaceMe ( MappedSPnode< cxsc::real > newNode )

Replace the properties of this node and its descendents with the properties of another node and its descendents.

Copies newNode node downwards into this, but keeps the relationship of this with its parent, ie if this is a node in a tree, the part of the tree rooted at this is made identical to newNode but the relationship to the rest of the tree,through the link between this and its parent, is retained.

Reimplemented from subpavings::MappedSPnode< cxsc::real >.

{
  
  RealMappedSPnode* pNode = getParent();
  newNode.swapMSPSR(*this);
  
  if (NULL != pNode) {
    
    this->parent = pNode;
  }
}

cxsc::real RealMappedSPnode::setRandomRange	(	gsl_rng *const	rgsl,
		size_t	myDepth = `0`
	)		`[virtual]`

Set a randomly-derived range on each node of the tree rooted at this.

The ranges for each leaf node are random. The random range set is some random value in the range (0.0, 1.0] multiplied by 2 times the depth of the node if the depth of the node is > 0 (ie the root has no children it will just get a random value in the range (0.0, 1.0]). Other than in the case of a leaf root node, this emulates what might happen in histogram where random numbers of points fall into each bin - random relative frequency (0.0, 1.0] - and the bin height would be relative frequency/volume, and volume divides by two every time we go one deeper in the tree.

The range set on a non-leaf node is the average of the ranges of the children.

Returns the new range set on this.

Parameters:

rgsl	a pseudo-random number generator used to generate random ranges.
myDepth	the depth of this node, defaulting to 0 (root).

Returns:: If this is a leaf, return a random range. If this is not a leaf, return the average of the ranges of the children.

{
  if (isLeaf() ) {
    /* randomly generate a range in (0.0, 1.0]
     * this would be a bit like n/N */
    
    double rand = 1.0-gsl_rng_uniform(rgsl);
    
    cxsc::real newRange( rand );
    /* if depth > 0, adjust for how deep we are, ie n/(Nvol) -
     * (as we get deeper volume divides by 2 each time)
     * but not normalised by total vol*/
    if (myDepth) newRange*=(2.0*myDepth);
    range = newRange;
  }
  else { // not a leaf
    cxsc::real newRange(0.0);
    
    // recurse first
    if (NULL != leftChild) newRange 
        += getLeftChild()->setRandomRange(rgsl, myDepth+1);
    if (NULL != rightChild) newRange 
        += getRightChild()->setRandomRange(rgsl, myDepth+1);
    
    range = newRange * 0.5;
    
  }
  // return the range on this
  return range;
  
}

void RealMappedSPnode::smearRanges	(	cxsc::real	zeroRange,
		cxsc::real	ratioRange
	)

Smear the ranges of the tree rooted at this so that no leaf node in this has range == 0.0 but the value of getTotalAbsLeafAreaRangeWithBox() is unchanged.

Leaf nodes with range == 0.0 will get range zeroRange. Leaf nodes with range <> 0.0 will get their range reduced in by a proportion calculated so that over the whole tree the value of getTotalAbsLeafAreaRangeWithBox() is unchanged. Internal nodes will have their ranges changed in proportion to the change in the sum of the range of their children.

Parameters:

zeroRange	range to be given to leaf nodes with range == 0.0.
ratioRange	Leaf nodes with range == 0.0 get a new range = range(1 - ratioRange*).

Precondition:: this is a root node with a box.; zeroRange > 0.0.; 0.0 < ratioRange < 1.0.

Postcondition:: The tree rooted at this has the same value of getTotalAbsLeafAreaRangeWithBox() as before the operation but any node that had zero range before the operation now has range = zeroRange.

{
  if(parent != NULL) 
    throw NonRootNode_Error("RealMappedSPnode::smearRanges(cxsc::real, cxsc::real)");
  
  if(isEmpty()) 
    throw NoBox_Error("RealMappedSPnode::smearRanges(cxsc::real, cxsc::real)");
    
  if(!(zeroRange > 0.0))  
    throw std::invalid_argument("RealMappedSPnode::smearRanges(cxsc::real, cxsc::real)");
  
  if(!((ratioRange > 0.0) && (ratioRange < 1.0)) ) 
    throw std::invalid_argument("RealMappedSPnode::smearRanges(cxsc::real, cxsc::real)");
  
  _smearRanges(zeroRange, ratioRange);

}

The documentation for this class was generated from the following files:

realmappedspnode.hpp
realmappedspnode.cpp

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation