A wrapper or manager for an BooleanValueMappedSPnode tree to be used for function image estimation using boolean-mapped subpaving boxes. More...

Public Member Functions
	FunctionImageEstimatorBooleanValue (const ivector &v, const MappedFobj &f, const cxsc::interval &crit, int lab=0)
	Initialised constructor.
	FunctionImageEstimatorBooleanValue (const SPnode &spn, const MappedFobj &f, const cxsc::interval &crit, int lab=0)
	Initialised constructor.
	FunctionImageEstimatorBooleanValue (const FunctionImageEstimatorBooleanValue &other)
	Copy constructor.
	~FunctionImageEstimatorBooleanValue ()
	Destructor.
const MappedFobj &	getFobjReference () const
	Get the reference to the function object used by this.
cxsc::interval	getCriterion () const
	Get the image range criterion for this.
int	getLabel () const
	Get the label.
void	setLabel (int lab)
	Set the label.
bool	hasSubPaving () const
	Get whether this has a subpaving to manage.
cxsc::ivector	getRootBox () const
	Get the box of the subpaving managed by this.
bool	getRootRangeValue () const
	Get the value on the root of the subpaving managed by this.
int	getDimensions () const
	get the dimensions of the subpaving this manages.
cxsc::real	getDomainVolume () const
	get volume of the root box of the subpaving this manages.
size_t	getRootLeaves () const
	Gets number of leaf nodes in the root paving.
IntVec	getLeafLevels () const
std::string	getLeafLevelsString () const
subpavings::SpatialObjectRepresentationBV	makeSpatialObjectRepresentationBV () const
	Make a SpatialObjectRepresentationBV out of this estimator.
void	bruteForceEstimate (cxsc::real tolerance)
	Create an estimate of the function described by fobj using a depth-first brute force approach.
bool	splitToShape (std::string instruction)
	Split an estimator to a specified shape.
cxsc::real	getTotalTrueArea () const
	Get the total "area" of the function image being estimated by this.
std::ostream &	outputToStreamTabs (std::ostream &os, int prec=5) const
	Output the subpaving managed by this to a given stream.
std::ostream &	outputRootToStreamTabs (std::ostream &os, int prec=5) const
	Output all nodes of the subpaving managed by this to a given stream.
void	outputLog (const std::string &s, int i, int prec=5) const
	Append current state of estimator to a txt log file.
std::string	stringSummary () const
	Get a string summary of this estimator's properties.

void	outputToTxtTabs (const std::string &s, int prec=5) const
	Output the subpaving managed by this to a txt file.
void	outputToTxtTabs (const std::string &s, int prec, bool confirm) const

void	outputRootToTxt (const std::string &s, int prec=5) const
	Output details of full sample (from root) to txt file.
void	outputRootToTxt (const std::string &s, int prec, bool confirm) const

Detailed Description

A wrapper or manager for an BooleanValueMappedSPnode tree to be used for function image estimation using boolean-mapped subpaving boxes.

The box of the root of the subpaving managed by a FunctionImageEstimatorBooleanValue can be thought of as the domain and the boxes of the leaves of the subpaving can be thought of as the pieces in the partition of that domain for the current function image. The boolean value on each piece indicates whether that piece is part of the image of function on the domain.

Constructor & Destructor Documentation

FunctionImageEstimatorBooleanValue::FunctionImageEstimatorBooleanValue	(	const ivector &	v,
		const MappedFobj &	f,
		const cxsc::interval &	crit,
		int	lab = `0`
	)

Initialised constructor.

Initialised with domain box.

Throws a MalconstructedBox_Error if the box is not suitable as the basis of a subpaving (eg, box has no dimensions, or the box has a thin interval on at least one dimension).

Ideal constructor when the support domain of the function is set a priori.

Parameters:

v	The box to use for the subpaving to be managed.
f	The function whose image is to be estimated by this.
crit	The interval in which the image must fall.
lab	The label for this (defaults to 0).

Postcondition:: The estimator constructed has subpaving that consists of single leaf node (the root) with a box like v) and the range on that single node is the the interval image of v under the function represented by f.

         : rootPaving(NULL), fobj(f), criterion(crit), label(lab)
{
    try {
        // check the box here
        if (!checkBox(v)) {
      throw subpavings::MalconstructedBox_Error(
      "FunctionImageEstimatorBooleanValue::FunctionImageEstimatorBooleanValue(const ivector&, const MappedFobj&, int lab)");
    }
        rootPaving = new BooleanValueMappedSPnode(v);
    
    BooleanValueImageEstimator estimator(fobj, crit);
    rootPaving->acceptSPValueVisitor(estimator);
  }
    catch (exception const& e) {
    constructor_error_handler();
    }
}

FunctionImageEstimatorBooleanValue::FunctionImageEstimatorBooleanValue	(	const SPnode &	spn,
		const MappedFobj &	f,
		const cxsc::interval &	crit,
		int	lab = `0`
	)

Initialised constructor.

Initialised with a subpaving.

Parameters:

spn	A subpaving to copy as the subpaving to be managed.
f	The function whose image is to be estimated by this.
crit	The interval in which the image must fall.
lab	The label for this (defaults to 0).

Precondition:: spn has a box.

Postcondition:: The estimator constructed has label lab, a subpaving that that is a copy of spn and the range on each box in that subpaving is the interval image of that box under the function represented by f.

         : rootPaving(NULL), fobj(f), criterion(crit), label(lab)
{
    try {
        // check spn has box
    if (spn.isEmpty()) {
      throw subpavings::NoBox_Error(
      "FunctionImageEstimatorBooleanValue::FunctionImageEstimatorBooleanValue(const SPnode&, MappedFobj&, int lab");
    }
        rootPaving = new BooleanValueMappedSPnode(spn);
    
    BooleanValueImageEstimator estimator(fobj, crit);
    rootPaving->acceptSPValueVisitor(estimator);
  }
    catch (exception const& e) {
    constructor_error_handler();
    }
}

Member Function Documentation

void FunctionImageEstimatorBooleanValue::bruteForceEstimate ( cxsc::real tolerance )

Create an estimate of the function described by fobj using a depth-first brute force approach.

The over all aim to create an estimate of the described by fobj such that each of the leaf nodes of the subpaving managed by this has a box associated with it that meets the interval image tolerance requirement specified by tolerance.

The interval image tolerance requirement is that the diameter of the interval image of the box associated with any leaf node of of the subpaving managed by this should be less than or equal to the tolerance.

But in some cases this can result in boxes being split beyond the limits of the real number screen. If a split of a leaf node that does not meet the interval image tolerance requirement would result in the child nodes' volumes being < the value of the cxsc::MinReal (the smallest representable real number) then that leaf will not be split.

This means that after the operation, the subpaving managed by this may have leaf nodes where the interval image tolerance requirement is not met.

This operation works depth first, ie working from a leaf root it will successively split the root then the root's left child and that child's, left child, etc. It will only start splitting the right child of any node already split when all the descendents of the left child meet the interval image tolerance requirement (or they cannot be split further). This may cause the machine to run out of memory before the process is completed.

Note:: If this operation is applied to this when the subpaving managed by this already has leaf nodes which exceed the interval image tolerance requirement, those leaf nodes will be left unaltered by this operation.

Parameters:

tolerance describes the tolerance to be used in making the estimate.

Precondition:: hasSubPaving() == true.; tol >= cxsc::MinReal.

Postcondition:: the leaf nodes of the subpaving managed by this have a range which is the interval image of the box of the node under the function represented by this and either the interval image tolerance requirement is met for each leaf node or that leaf node is not splittable.

{
  string errorMsg(
    "FunctionImageEstimatorBooleanValue::bruteForceEstimate(cxsc::real)");
  if (!hasSubPaving()) {
    throw NullSubpavingPointer_Error(errorMsg);
  }
  
  BooleanValueImageExpanderEstimator estimator(fobj, criterion,
                  tolerance);

  getSubPaving()->acceptSPExpandVisitor(estimator);

}

cxsc::interval FunctionImageEstimatorBooleanValue::getCriterion ( ) const

Get the image range criterion for this.

Returns:: the criterion for this.

{return criterion;}

int FunctionImageEstimatorBooleanValue::getDimensions ( ) const

get the dimensions of the subpaving this manages.

Returns:: 0 if this does not have a subpaving, else returns the dimensions of the subpaving.

{
  int retValue = 0;
  if (hasSubPaving()) {
    retValue = getSubPaving()->getDimension();
  }
  return retValue;
}

cxsc::real FunctionImageEstimatorBooleanValue::getDomainVolume ( ) const

get volume of the root box of the subpaving this manages.

Returns:: volume of the root box of the subpaving this manages, or 0.0 if this has no subpaving.

{
  real retValue(0.0);
  if (hasSubPaving()) {
    retValue = getSubPaving()->nodeRealVolume();
  }
  return retValue;
}

const MappedFobj & FunctionImageEstimatorBooleanValue::getFobjReference ( ) const

Get the reference to the function object used by this.

Returns:: the function object reference used by this.

{return fobj;}

int FunctionImageEstimatorBooleanValue::getLabel ( ) const

Get the label.

Returns:: the label for this.

{return label;}

IntVec FunctionImageEstimatorBooleanValue::getLeafLevels ( ) const

Get a vector of the leaf node levels.

Root is level 0, next level down is 1, etc.

Returns:: a vector of leaf levels, left to right order,

{
    IntVec levels; // empty container

    if (hasSubPaving()) {
        getSubPaving()->getLeafNodeLevels(levels, 0);
        //levels has now been filled in
    }
    return levels;
}

std::string FunctionImageEstimatorBooleanValue::getLeafLevelsString ( ) const

Get a string of the leaf node levels.

Root is level 0, next level down is 1, etc. Example return string "3,3,2,1"

Returns:: a comma separated string of leaf levels, left to right order

{
    string retValue = "";
    if (hasSubPaving())
        retValue = getSubPaving()->getLeafNodeLevelsString();

    return retValue;
}

cxsc::ivector FunctionImageEstimatorBooleanValue::getRootBox ( ) const

Get the box of the subpaving managed by this.

Note:: with the present constructors, it is impossible for this to have a subpaving but for the subpaving to have no box.

Returns:: copy of the box of the subpaving managed by this.

Precondition:: hasSubPaving() == true.

{
  if (!hasSubPaving()) {
    throw NullSubpavingPointer_Error(
          "FunctionImageEstimatorBooleanValue::getRootBox()");
  }
  return getSubPaving()->getBox();
}

size_t FunctionImageEstimatorBooleanValue::getRootLeaves ( ) const

Gets number of leaf nodes in the root paving.

Throws NullSubpavingPointer_Error is the subpaving that this manages is a NULL pointer.

Returns:: the total number of leaves in the subpaving managed.

Precondition:: hasSubPaving() == true.

{
  if (!hasSubPaving()) {
    throw NullSubpavingPointer_Error("FunctionImageEstimatorBooleanValue::getRootLeaves()");
    
  }
  return getSubPaving()->getNumberLeaves();
}

bool FunctionImageEstimatorBooleanValue::getRootRangeValue ( ) const

Get the value on the root of the subpaving managed by this.

Note:: with the present constructors, it is impossible for this to have a subpaving but for the subpaving to have no box.

Returns:: value on the root of the subpaving managed by this.

Precondition:: hasSubPaving() == true.

{
  if (!hasSubPaving()) {
    throw NullSubpavingPointer_Error(
          "FunctionImageEstimatorBooleanValue::getRootRangeDiameter()");
  }
  return getSubPaving()->getRange();
}

cxsc::real FunctionImageEstimatorBooleanValue::getTotalTrueArea ( ) const

Get the total "area" of the function image being estimated by this.

Returns:: total of the true-valued volume of the subpaving estimating the image function.

Precondition:: This must have a subpaving to manage.

{
  if (!hasSubPaving()) {
    throw NullSubpavingPointer_Error(
    "FunctionImageEstimatorBooleanValue::getTotalAreaOfIntervalBand()");
  }
  return getSubPaving()->getTotalLeafTrueAreaOnBox();
}

bool FunctionImageEstimatorBooleanValue::hasSubPaving ( ) const

Get whether this has a subpaving to manage.

Note:: with the present constructors, it is impossible for this to have a subpaving but for the subpaving to have no box.

Returns:: true if this has a subpaving to manage. false otherwise.

{
    return ( getSubPaving() != NULL );
}

subpavings::SpatialObjectRepresentationBV FunctionImageEstimatorBooleanValue::makeSpatialObjectRepresentationBV ( ) const

Make a SpatialObjectRepresentationBV out of this estimator.

Returns:: A SpatialObjectRepresentationBV with the same subpaving as this with. The function values mapped onto each node of the for the returned object are the values mapped to the nodes of this estimator under the function image represented by this. The PiecewiseConstantFunction created will have the same label as this.

{
  return SpatialObjectRepresentationBV(*getSubPaving(), getLabel());
}

void FunctionImageEstimatorBooleanValue::outputLog	(	const std::string &	s,
		int	i,
		int	prec = `5`
	)		const

Append current state of estimator to a txt log file.

Format is a tab-delimited file of numeric data. Output includes node contributions to unscaled EMP under COPERR and AIC and the changes in EMP that would result from splitting the node.

Parameters:

s	the name of the txt file to send output to.
i	the number of pass (ie, 0, 1, 2, 3 etc) in process.
prec	the precision for output formatting. ie, number of decimal places.

{
    // To add output of the FunctionImageEstimatorBooleanValue object to file
    ofstream os(s.c_str(), ios::app);         // append
    if (os.is_open()) {
    
    os << std::endl;
        os << "Pass " << i << std::endl; // numbering
        getSubPaving()->leavesOutputTabs(os, prec); // the output
    
    os.close();
    }
    else {
        std::cerr << "Error: could not open file named "
            << s << std::endl << std::endl;
    }
}

std::ostream & FunctionImageEstimatorBooleanValue::outputRootToStreamTabs	(	std::ostream &	os,
		int	prec = `5`
	)		const

Output all nodes of the subpaving managed by this to a given stream.

Format is a tab-delimited data giving details of all nodes.

Parameters:

os	is a reference to the stream to output to.
prec	the precision for output formatting. ie, number of decimal places, defaulting to 5.

Returns:: a reference to the given stream.

{
  if (hasSubPaving()) {
    
    getSubPaving()->nodesAllOutput(os, 1, prec); // the output
    
  }
  
    return os;
}

void FunctionImageEstimatorBooleanValue::outputRootToTxt	(	const std::string &	s,
		int	prec = `5`
	)		const

Output details of full sample (from root) to txt file.

Format is a mixture of alpha and numeric data.

Parameters:

s	the name of the txt file to send output to.
prec	the precision for output formatting. ie, number of decimal places.
confirm	is a boolean controlling whether confirmation goes to console output.

{
  outputRootToTxt(s, prec, false);
}

std::ostream & FunctionImageEstimatorBooleanValue::outputToStreamTabs	(	std::ostream &	os,
		int	prec = `5`
	)		const

Output the subpaving managed by this to a given stream.

Format is a tab-delimited data giving details of leaf nodes.

Parameters:

os	is a reference to the stream to output the histogramm to.
prec	the precision for output formatting. ie, number of decimal places.

Returns:: a reference to the given stream.

{
  if (hasSubPaving()) {
    
    // have to use cxsc io manipulators
    os << cxsc::SaveOpt;
    os << cxsc::Variable << cxsc::SetPrecision(prec+2,prec);

    getSubPaving()->leavesOutputTabs(os); // the output
    
    os << cxsc::RestoreOpt;
  }
  
    return os;
}

void FunctionImageEstimatorBooleanValue::outputToTxtTabs	(	const std::string &	s,
		int	prec = `5`
	)		const

Output the subpaving managed by this to a txt file.

Format is a tab-delimited file of numeric data starting with nodeName, then the node box volume, then the node counter, then the description of the node box as a tab-delimited list of interval upper and lower bounds.

Parameters:

s	the name of the txt file to send output to.
prec	the precision for output formatting. ie, number of decimal places.
confirm	is a boolean controlling whether confirmation goes to console output.

{
  outputToTxtTabs(s, prec, false);
}

bool FunctionImageEstimatorBooleanValue::splitToShape ( std::string instruction )

Split an estimator to a specified shape.

Throws a NullSubpavings_Error if the subpaving that this manages is a NULL pointer.

Throws a NoBox_Error if the subpaving box is empty.

Prints a message to the standard error output if the instruction could not be carried out.

Parameters:

instruction specifies the required shape, eg "3, 3, 2, 1"

Returns:: true if the split was successful, false otherwise

Precondition:: hasSubPaving() == true.

Postcondition:: this has subpaving with shape specified by instruction and the value mapped to each node in the subpaving is the interval image of that node's box under the function represented by this.

{
  
  // checks:  is there a root paving, is the string properly formed?
  if (!hasSubPaving()) {
    throw NullSubpavingPointer_Error(
        "FunctionImageEstimatorBooleanValue::splitToShape()");
  }
  bool success = false;
  BooleanValueMappedSPnode temp(*getSubPaving()); // copy to temp
  try {
    if (instruction.length() == 0) {
      throw std::invalid_argument(
        "FunctionImageEstimatorBooleanValue::splitToShape() : No instruction");
    }

    std::string legal(", 0123456789");
    if (instruction.find_first_not_of(legal) != std::string::npos) {
      throw std::invalid_argument(
        "FunctionImageEstimatorBooleanValue::splitToShape() : Illegal character");
    }

    // all seems to be okay, we can start splitting the root paving
    
    success = getSubPaving()->splitRootToShape(instruction);
    
    
    /* ALSO NEED to set the interval ranges using fobj */
    BooleanValueImageEstimator estimator(fobj, criterion);
    rootPaving->acceptSPValueVisitor(estimator);

    if (!success) {
      
      handleSplitToShapeError(temp);
     }
     
  }
  catch (std::invalid_argument const& ia) {
    cerr << ia.what() << endl;
    handleSplitToShapeError(temp);
    success = false;
  }
  catch (std::logic_error const& le) {
    cerr << le.what() << endl;
    handleSplitToShapeError(temp);
    success = false;
  }
  return success;
  // any other exceptions are unhandled
}

std::string FunctionImageEstimatorBooleanValue::stringSummary ( ) const

Get a string summary of this estimator's properties.

A string description of this. Includes the address of the subpaving managed but not details of that subpaving.

Returns:: the string summary.

{
  std::ostringstream oss;
  
  oss << "This address = " << (this) << endl;
  oss << "Reference to function object is  = " << (&fobj) << endl;
  
  if (hasSubPaving()) oss << "Address of subpaving is " << getSubPaving() << endl;
  else oss << "Subpaving is NULL" << endl;
  
  return oss.str();
}

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

functionimage_estimator_booleanvalue.hpp
functionimage_estimator_booleanvalue.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation