subpavings::CarverSEB Class Reference

A static class for doing carving-SEB RPQ routines. More...

List of all members.

Static Public Member Functions
Find some of the best starting points.
Fills hists with pointers to histograms created as the keep best from carvingStarts+1 attempts at a combined carving-SEB rpq. Best is defined in terms of highest log-posterior mass. Note: The maximum leaves in the carving queue (specified using evaluatorCarving) and carvingStarts are regarded as initial values only: may be adjusted within the method and the search proces repeated. Any pointers in hists at the end of the routine are pointers to objects in dynamic memory (ie, newed). These objects will need to be deleted at the end of the routine using them. Parameters: adh is the histogram to use to find the best staritiong points. hists is a container to fill with pointers to AdaptiveHistogram found during the operation. Note that these are on the heap and will need to be deleted. evaluatorCarving is the PrioritySplitQueueEvaluator to use to control the carving queue. It should specify the maximum number of leaves to which to attempt the carving queue. evaluatorSEB is the PrioritySplitQueueEvaluator to use to control the SEB queue. It should specify the maximum number of leaves to which to attempt the SEB queue and also the SEB-related stopping criteria, the maximum number of points in any leaf below which no further splitting will take place. logPrior the prior to uses to evaluate the log-posterior. minPoints the minimum number of points in a node to control which nodes are considered to be splittable. minVol the minimum volume that should be in any leaf node of any AdaptiveHistogram in hists after the operation. carvingStarts is the number of different lengths of the carving queue to use before the SEB queue. In addition to carvingStarts attempts, one attempt with no carving at all is always made, i.e, setting carvingStarts = 0 will mean that just one attempt straight from the root with a SEB queue will be made. keep is the number of histogram pointers to try to store in hists. stopOnMaxPosterior is an indicator for whether the search for maximum posterior points should continue until evaluatorSEB's maximum leaves is reached or terminate once it seems clear that a maximum has been found. If false, the search will continue until a evaluatorSEB's maximum leaves is reached. If true the search may continue for some relatively short number of states past a local maximum to ensure that it it appears to be a global maximum. postFileName is the filename to which to output the log from the carving queue. If this is the empty string ("") no log will be output. checkPostFileNameBase is the base for the filenames to which to output the log from the creation of each histogram found to be pointed to in hists carving queue. If this is the empty string ("") no log will be output. prec is the precision to use when outputting logs. seed is the seed to use for the carver-SEB RPQ process. Defaults to 1234. Postcondition: hists will contain pointers to the maximum posterior states found. It is not guaranteed that there will be keep of these, or indeed that there will be any.
static std::vector < AdaptiveHistogram * > &	findStartingPoints (AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, int carvingStarts, size_t keepBest, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version without minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPoints (AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, int carvingStarts, size_t keepBest, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version with minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPointsBest (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, int carvingStarts, size_t keep, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version without minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPointsBest (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, int carvingStarts, size_t keep, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version with minVol argument.
Find the most spread-out starting points.
Fills hists with pointers to histograms created as the keep most spread out maximums from carvingStarts+1 attempts at a combined carving-SEB rpq. Spread is defined in terms of the number of leaves in the histograms. Note: The maximum leaves in the carving queue (specified using evaluatorCarving) and carvingStarts are regarded as initial values only: if no maximums are found using these values they may be adjusted within the method and the search proces repeated. Any pointers in hists at the end of the routine are pointers to objects in dynamic memory (ie, newed). These objects will need to be deleted at the end of the routine using them. Parameters: adh is the histogram to use to find the best staritiong points. hists is a container to fill with pointers to AdaptiveHistogram found during the operation. Note that these are on the heap and will need to be deleted. evaluatorCarving is the PrioritySplitQueueEvaluator to use to control the carving queue. It should specify the maximum number of leaves to which to attempt the carving queue. evaluatorSEB is the PrioritySplitQueueEvaluator to use to control the SEB queue. It should specify the maximum number of leaves to which to attempt the SEB queue and also the SEB-related stopping criteria, the maximum number of points in any leaf below which no further splitting will take place. logPrior the prior to uses to evaluate the log-posterior. minPoints the minimum number of points in a node to control which nodes are considered to be splittable. minVol the minimum volume that should be in any leaf node of any AdaptiveHistogram in hists after the operation. carvingStarts is the number of different lengths of the carving queue to use before the SEB queue. In addition to carvingStarts attempts, one attempt with no carving at all is always made, i.e, setting carvingStarts = 0 will mean that just one attempt straight from the root with a SEB queue will be made. keep is the number of histogram pointers to try to store in hists. stopOnMaxPosterior is an indicator for whether the search for maximum posterior points should continue until evaluatorSEB's maximum leaves is reached or terminate once it seems clear that a maximum has been found. If false, the search will continue until a evaluatorSEB's maximum leaves is reached. If true the search may continue for some relatively short number of states past a local maximum to ensure that it it appears to be a global maximum. postFileName is the filename to which to output the log from the carving queue. If this is the empty string ("") no log will be output. checkPostFileNameBase is the base for the filenames to which to output the log from the creation of each histogram found to be pointed to in hists carving queue. If this is the empty string ("") no log will be output. prec is the precision to use when outputting logs. seed is the seed to use for the carver-SEB RPQ process. Defaults to 1234. Postcondition: hists will contain pointers to the well-spread-out states found. It is not guaranteed that there will be keep of these, or indeed that there will be any.
static std::vector < AdaptiveHistogram * > &	findStartingPointsMaxLeafSpread (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, int carvingStarts, size_t keep, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version without minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPointsMaxLeafSpread (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, int carvingStarts, size_t keep, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version with minVol argument.
Find some well spread-out starting points.
Fills hists with pointers to histograms created as the keep most spread out maximums from carvingStarts+1 attempts at a combined carving-SEB rpq. Spread is defined in terms of the number of leaves in the histograms. Note: The maximum leaves in the carving queue (specified using evaluatorCarving) and carvingStarts are regarded as initial values only: if no maximums are found using these values they may be adjusted within the method and the search proces repeated. Any pointers in hists at the end of the routine are pointers to objects in dynamic memory (ie, newed). These objects will need to be deleted at the end of the routine using them. Parameters: adh is the histogram to use to find the best staritiong points. hists is a container to fill with pointers to AdaptiveHistogram found during the operation. Note that these are on the heap and will need to be deleted. evaluatorCarving is the PrioritySplitQueueEvaluator to use to control the carving queue. It should specify the maximum number of leaves to which to attempt the carving queue. evaluatorSEB is the PrioritySplitQueueEvaluator to use to control the SEB queue. It should specify the maximum number of leaves to which to attempt the SEB queue and also the SEB-related stopping criteria, the maximum number of points in any leaf below which no further splitting will take place. logPrior the prior to uses to evaluate the log-posterior. minPoints the minimum number of points in a node to control which nodes are considered to be splittable. minVol the minimum volume that should be in any leaf node of any AdaptiveHistogram in hists after the operation. carvingStarts is the number of different lengths of the carving queue to use before the SEB queue. In addition to carvingStarts attempts, one attempt with no carving at all is always made, i.e, setting carvingStarts = 0 will mean that just one attempt straight from the root with an SEB queue will be made. keep is the number of histogram pointers to try to store in hists. outOfClosest is the size of the subset of the maximum posterior points found from which to select the keep most spread-out points. This using this can prevent the starting points being so far apart that chains take too long to converge . stopOnMaxPosterior is an indicator for whether the search for maximum posterior points should continue until evaluatorSEB's maximum leaves is reached or terminate once it seems clear that a maximum has been found. If false, the search will continue until a evaluatorSEB's maximum leaves is reached. If true the search may continue for some relatively short number of states past a local maximum to ensure that it it appears to be a global maximum. postFileName is the filename to which to output the log from the carving queue. If this is the empty string ("") no log will be output. checkPostFileNameBase is the base for the filenames to which to output the log from the creation of each histogram found to be pointed to in hists carving queue. If this is the empty string ("") no log will be output. prec is the precision to use when outputting logs. seed is the seed to use for the carver-SEB RPQ process. Defaults to 1234. Postcondition: hists will contain pointers to the well-spread-out states found. It is not guaranteed that there will be keep of these, or indeed that there will be any.
static std::vector < AdaptiveHistogram * > &	findStartingPointsMaxLeafSpread (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, int carvingStarts, size_t keep, size_t outOfClosest, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version without minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPointsMaxLeafSpread (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, int carvingStarts, size_t keep, size_t outOfClosest, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version with minVol argument.
Find some over-dispersed starting points.
Fills hists with pointers to histograms created as keep well diversified points from the sequence of states created by the carving-seb RPQ that gives the overall maximum log-posterior point in carvingStarts+1 attempts at a combined carving-SEB rpq. Diversification is defined in terms of the number of leaves in the histograms. Note: The maximum leaves in the carving queue (specified using evaluatorCarving) and carvingStarts are regarded as initial values only: if no maximums are found using these values they may be adjusted within the method and the search proces repeated. Any pointers in hists at the end of the routine are pointers to objects in dynamic memory (ie, newed). These objects will need to be deleted at the end of the routine using them. The method identifies the the carving-seb RPQ that gives the overall maximum log-posterior point in carvingStarts+1 attempts at a combined carving-SEB rpq. It then identifies the maximum log posterior state in this sequence and selects keep well diversified states from a sub-sequence of states in the sequence that contains the maximum log-posterior state and starts at the first state that achieves of that maximum. is set within the method.
static std::vector < AdaptiveHistogram * > &	findStartingPointsOverdispersed (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, int carvingStarts, size_t keep, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version without minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPointsOverdispersed (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, int carvingStarts, size_t keep, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version with minVol argument.
static std::vector < AdaptiveHistogram * > &	findStartingPointsOverdispersed (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, int carvingStarts, size_t keep, double percentSpread, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Find some over-dispersed starting points.
static std::vector < AdaptiveHistogram * > &	findStartingPointsOverdispersed (const AdaptiveHistogram &adh, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, int carvingStarts, size_t keep, double percentSpread, bool stopOnMaxPosterior, const std::string &postFileName, const std::string &checkPostFileNameBase, int prec, unsigned long int seed=1234)
	Version with minVol argument.
Add a starting point to a container
of starting points. Adds one more pointer to hists, created using the carving and SEB queue parameters specified in evaluatorCarving and evaluatorSEB. Note: the pointer added to hists will be a pointer to an object in dynamic memory and will need to deleted at the end of the routine using it. Parameters: adhBase is the histogram to use to find the best staritiong points. Note that this is changed during the operation. hists is a container to which to add a pointer to the new start point created in this method. evaluatorCarving is the PrioritySplitQueueEvaluator to use to control the carving queue. It should specify the maximum number of leaves to which to attempt the carving queue. evaluatorSEB is the PrioritySplitQueueEvaluator to use to control the SEB queue. It should specify the maximum number of leaves to which to attempt the SEB queue. Note that if it also specifies a positive SEB-related stopping criteria, the maximum number of leaves specified may not be reached. logPrior the prior to uses to evaluate the log-posterior. minPoints the minimum number of points in a node to control which nodes are considered to be splittable. minVol the minimum volume that should be in any leaf node of the AdaptiveHistogram added to hists. checkPostFileNameBase is the base for the filename to which to output the log from the creation of the new histogram to be pointed to in hists carving queue. If this is the empty string ("") no log will be output. seed is the seed to use for the carver-SEB RPQ process. Defaults to 1234. Postcondition: hists will contain one more pointer, to a state created using evaluatorCarving and evaluatorSEB.
static std::vector < AdaptiveHistogram * > &	createStartingPoint (const AdaptiveHistogram &adhBase, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, const std::string &checkPostFileNameBase, unsigned long int seed=1234)
	Version without minVol argument.
static std::vector < AdaptiveHistogram * > &	createStartingPoint (const AdaptiveHistogram &adhBase, std::vector< AdaptiveHistogram * > &hists, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorSEB, LogMCMCPrior &logPrior, size_t minPoints, double minVol, const std::string &checkPostFileNameBase, unsigned long int seed=1234)
	Version with minVol argument.
Carve the given AdaptiveHistogram.
Parameters: adh is the histogram to carve. Note that this is changed during the operation. evaluatorCarving is the PrioritySplitQueueEvaluator to use to control the carving queue. It should specify the maximum number of leaves to which to attempt the carving queue. logPrior the prior to uses to evaluate the log-posterior. minPoints the minimum number of points in a node to control which nodes are considered to be splittable. minVol the minimum volume that should be in any leaf node of adh after the operation. postFileName is the filename to which to output the log from the carving queue. If this is the empty string ("") no log will be output. prec is the precision to use when outputting logs. seed is the seed to use for the carver-SEB RPQ process. Defaults to 1234. Postcondition: adh will be carved as specified by evaluatorCarving.
static AdaptiveHistogram &	carve (AdaptiveHistogram &adh, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, LogMCMCPrior &logPrior, size_t minPoints, const std::string &postFileName, int prec, unsigned long int seed=1234)
	Version without minVol argument.
static AdaptiveHistogram &	carve (AdaptiveHistogram &adh, AdaptiveHistogram::PrioritySplitQueueEvaluator evaluatorCarving, LogMCMCPrior &logPrior, size_t minPoints, double minVol, const std::string &postFileName, int prec, unsigned long int seed=1234)
	Version with minVol argument.

---

Detailed Description

A static class for doing carving-SEB RPQ routines.

Note:

Any pointers in hists at the end of the routines shown here are pointers to objects in dynamic memory (ie, newed). These objects will need to be deleted at the end of the routine using them.

Todo:

Would like to clean up this aspect of the design. If we used boost::shared_pointer a lot of horrible things like this could be dealt with, but it adds yet another library dependency to the whole thing.

---

Member Function Documentation

std::vector< AdaptiveHistogram * > & subpavings::CarverSEB::findStartingPointsOverdispersed	(	const AdaptiveHistogram &	adh,
		std::vector< AdaptiveHistogram * > &	hists,
		AdaptiveHistogram::PrioritySplitQueueEvaluator	evaluatorCarving,
		AdaptiveHistogram::PrioritySplitQueueEvaluator	evaluatorSEB,
		LogMCMCPrior &	logPrior,
		size_t	minPoints,
		int	carvingStarts,
		size_t	keep,
		double	percentSpread,
		bool	stopOnMaxPosterior,
		const std::string &	postFileName,
		const std::string &	checkPostFileNameBase,
		int	prec,
		unsigned long int	seed = 1234
	)		[static]

Find some over-dispersed starting points.

Fills hists with pointers to histograms created as keep well diversified points from the sequence of states created by the carving-seb RPQ that gives the overall maximum log-posterior point in carvingStarts+1 attempts at a combined carving-SEB rpq. Diversification is defined in terms of the number of leaves in the histograms.

Note:

The maximum leaves in the carving queue (specified using evaluatorCarving) and carvingStarts are regarded as initial values only: they may be adjusted within the method and the search proces repeated if no satisfactory maximums are found using the original values. Any such adjustment process must be finite, so that the method will eventually always either progress or fail with an exception (not continue indefinitely).

Any pointers in hists at the end of the routine are pointers to objects in dynamic memory (ie, newed). These objects will need to be deleted at the end of the routine using them.

Version without minVol argument.

  {
    
    double minVol = 0.0;
    return findStartingPointsOverdispersed(
              adh,
              hists,
              evaluatorCarving, 
              evaluatorSEB, 
              logPrior,
              minPoints,
              minVol,
              carvingStarts,
              keep,
              percentSpread,
              stopOnMaxPosterior, //always
              postFileName,
              checkPostFileNameBase,  
              prec,
              seed);
  }

---

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

• carver_seb.hpp
• carver_seb.cpp