A histogram with fixed-width bins. More...

#include <Histogram.hh>

Public Types
enum	BinPlacement { left, center }

enum	Interpolator { flat, linear, spline }

Public Types inherited from utility::pointer::ReferenceCount
typedef platform::Size	Size

typedef platform::Size	size_type

Public Member Functions
std::string	to_string (Interpolator const &interpolator) const

	Histogram (utility::vector1< Y > const &densities, const X first_bin, const X step_size, const bool periodic=false, const BinPlacement bin_placement=left, const Interpolator interp=linear)
	Initialize a histogram with the given density distribution. More...

	Histogram (Histogram const &h)
	Copy Constructor. More...

	Histogram (std::istream &file)
	Generate Histogram from a file. More...

	~Histogram ()
	destructor More...

utility::vector1< Y >	densities () const
	The densities array. More...

utility::vector1< Y > &	densities ()

X	first_bin () const
	The x-value of the left corner of the first bin. More...

X &	first_bin ()

X	last_bin () const
	The x-value of the left corner of the last bin. More...

X	last_bin_right () const
	The x-value of the right corner of the last bin. More...

X	step_size () const
	Return the distance between two bins. More...

X &	step_size ()

bool	periodic () const
	Return whether this histogram is periodic. More...

bool &	periodic ()

BinPlacement	bin_placement () const
	The bin placement. More...

BinPlacement &	bin_placement ()

Interpolator	interpolator () const

Interpolator &	interpolator ()

X	minimum () const
	The smallest value for which we can interpolate. More...

X	maximum () const
	The largest value for which we can interpolate. More...

size_type	nbins () const
	The number of bins. More...

bool	interpolate (X const &x, Y &y) const
	Interpolates a density for a given x-value from the histogram. More...

bool	interpolate (X const &x, Y &y, Real &dy) const
	Interpolates a density for a given x-value from the histogram. More...

bool	derivative (X const &x, Y &dy) const
	The derivative of f(x), linearly interpolated. More...

bool	interpolate_spline (X const &x, Y &y, Real &dy) const

Public Member Functions inherited from utility::pointer::ReferenceCount
void	ctor ()

virtual	~ReferenceCount ()
	Destructor. More...

Size	ref_count () const
	Reference count. More...

Protected Member Functions
void	set_params (std::map< std::string, std::string > const &params)
	Set properties of this histogram from a map of strings. More...

platform::SSize	bin_number (X const &x, X &a) const
	get the number of the bin to the left of X. More...

bool	interpolate_flat (X const &x, Y &y) const
	Returns the density of the bin which x belongs to. More...

bool	interpolate_linear (X const &x, Y &y) const

bool	derivative_linear (X const &x, Y &y) const
	The derivative of f(x), linearly interpolated. More...

Protected Member Functions inherited from utility::pointer::ReferenceCount
	ReferenceCount ()
	Default constructor. More...

	ReferenceCount (ReferenceCount const &)
	Copy constructor. More...

ReferenceCount &	operator= (ReferenceCount const &)
	Copy assignment. More...

Static Protected Member Functions
static void	read_from_db (std::istream &db_file, utility::vector1< Y > &energies, std::map< std::string, std::string > &params)
	Read a score function from the minirosetta_database into an array. More...

Protected Attributes
utility::vector1< Y >	densities_

X	min_
	the x value of densities_[0]. Not actually the minimum for BinPlacement other than left. More...

X	step_

bool	periodic_

BinPlacement	bin_placement_

Interpolator	interpolator_

utility::pointer::owning_ptr < numeric::interpolation::spline::Interpolator >	spline_interpolator_

Detailed Description

template<typename, typename>
class numeric::interpolation::Histogram< typename, typename >

A histogram with fixed-width bins.

Histograms are commonly used to approximate arbitrary functions. At their most basic level they just map X values to f(X) for discrete, regularly spaced values of X. Usually you then interpolate between the stored Y values so that all values of X can be evaluated.

When creating a histogram the range and bin width must be given. Several parameters can also be specified to set how the interpolation will work. After that the function can be approximated for arbitrary X values by calling interpolate(). The important parameters describing how to interpolate are:

Periodicity:
- nonperiodic - Only X values within the range of the function are strictly legal. See interpolate(X,Y&) for the behavior when out of this range.
- periodic - All X values are taken modulus the length of the range of the function.
Bin Placement:
Since bins span a range of X, it is ambiguous exactly what X value the bin gives the value of. The choice for BinPlacement should depend on the source of the data for the histogram.
If bin[x] spans a range [x1,x2],
- left - bin[x] corresponds to f(x1). This is streightforward, but you tend to over-estimate f(x) for areas with positive slope and under-estimate for areas with negative slope due to the stair-step shape of the histogram
- center - bin[x] corresponds to f( (x1+x2)/2 )
- right - bin[x] corresponds to f(x2). Equivalent to left with bin[x+1]
Interpolator:
Specifies the algorithm used for interpolating between bins
- flat - No interpolation. Gives a discontinuous function, but faithful to the raw data.
- linear - Perform linear interpolation between the two adjacent bins.
Other (unimplemented) methods give functions which have continuous derivatives, etc.

Bins can be visualized as follows: w is the bin width; n is the number of bins; X_0 is the value of the first bin

left histograms go from [ X0 to (X0 + w*n) ) X = X0 + 0 w 2w ... (n-1)w n*w bin number | 1 | 2 | ... | n |
center histograms go from [ (X0 - w/2) to (X0 + (n-1)w/2)) ) X = X0 + -w/2 (1/2)w (3/2)w ... (n-3/2)w (n-1/2)w bin number | 1 | 2 | ... | n |
right histograms go from ( (X0 - w) to (X0 + (n-1)w) ] X = X0 + -w 0 w ... (n-2)w (n-1)w bin number | 1 | 2 | ... | n |

Template Parameters

X	The range of the function. Should support the operations expected of real types. Examples: numeric::Real, float, double
Y	The domain of the function. Should support the operations expected of real types.

Member Enumeration Documentation

template<typename , typename >

enum numeric::interpolation::Histogram::BinPlacement

Enumerator
left
center

template<typename , typename >

enum numeric::interpolation::Histogram::Interpolator

Todo:: It would be cool to implement the different ways of interpolating using subclasses of Histogram rather than this enum.

Enumerator
flat
linear
spline

Constructor & Destructor Documentation

template<typename , typename >

numeric::interpolation::Histogram< typename, typename >::Histogram	(	utility::vector1< Y > const &	densities,
		const X	first_bin,
		const X	step_size,
		const bool	periodic = `false`,
		const BinPlacement	bin_placement = `left`,
		const Interpolator	interp = `linear`
	)

inline

Initialize a histogram with the given density distribution.

Parameters

densities	A vector giving the densities of each bin
first_bin	The x-value of the first bin
step_size	The width of each bin
bin_placement	Indicate what x-value the bins are mapped to: the left corner, the center of the bin, or the right corner

template<typename , typename >

numeric::interpolation::Histogram< typename, typename >::Histogram ( Histogram< typename, typename > const & h )

inline

Copy Constructor.

template<typename , typename >

numeric::interpolation::Histogram< typename, typename >::Histogram ( std::istream & file )

inline

Generate Histogram from a file.

The parameters for the histogram (eg range, step size, etc) are read from any

Parameters

fields in the file header present, otherwise they are set to default values and can be changed after instantiation.

Note: See Histogram::read_from_db() for more information about the file format.

References numeric::interpolation::Histogram< typename, typename >::densities_, basic::options::OptionKeys::dna::specificity::params, numeric::interpolation::Histogram< typename, typename >::read_from_db(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

numeric::interpolation::Histogram< typename, typename >::~Histogram ( )

inline

destructor

Member Function Documentation

template<typename , typename >

platform::SSize numeric::interpolation::Histogram< typename, typename >::bin_number	(	X const &	x,
		X &	a
	)		const

inlineprotected

get the number of the bin to the left of X.

Takes periodicity and bin alignment into account. A periodic histogram will always return a number in [1,nbins] A nonperiodic histogram makes no guarentees that its return value will fall within the allowed bounds of 1 through nbins. You should do bounds checking elsewhere to assert that x is within the allowed range.

Parameters

x[in]	The independent axis value
a[out]	The alpha fraction: (x-x_l)/(x_u-x_l) for bin [x_l,x_u]

x is in the domain of the histogram. For nonperiodic histograms, this means minimum() <= x < maximum()

Returns: The index of bin x_l

References basic::options::OptionKeys::lh::fragpdb::bin, numeric::interpolation::Histogram< typename, typename >::first_bin(), numeric::modulo(), numeric::interpolation::Histogram< typename, typename >::nbins(), and numeric::interpolation::Histogram< typename, typename >::step_.

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate_flat(), and numeric::interpolation::Histogram< typename, typename >::interpolate_linear().

template<typename , typename >

BinPlacement numeric::interpolation::Histogram< typename, typename >::bin_placement ( ) const

inline

The bin placement.

References numeric::interpolation::Histogram< typename, typename >::bin_placement_.

template<typename , typename >

BinPlacement& numeric::interpolation::Histogram< typename, typename >::bin_placement ( )

inline

References numeric::interpolation::Histogram< typename, typename >::bin_placement_.

template<typename , typename >

utility::vector1<Y> numeric::interpolation::Histogram< typename, typename >::densities ( ) const

inline

The densities array.

References numeric::interpolation::Histogram< typename, typename >::densities_.

template<typename , typename >

utility::vector1<Y>& numeric::interpolation::Histogram< typename, typename >::densities ( )

inline

References numeric::interpolation::Histogram< typename, typename >::densities_.

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::derivative	(	X const &	x,
		Y &	dy
	)		const

inline

The derivative of f(x), linearly interpolated.

For x between bins, this is just the slope of the interpolation line. For x on a bin the slope of the line to the right is used.

Parameters

[in]	x	The point on the independant axis for which to get the derivative
[out]	dy	An approximation of df/dx, cast to a Y.

References numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::flat, numeric::interpolation::Histogram< typename, typename >::interpolate_spline(), numeric::interpolation::Histogram< typename, typename >::interpolator_, numeric::interpolation::Histogram< typename, typename >::linear, numeric::interpolation::Histogram< typename, typename >::spline, numeric::interpolation::Histogram< typename, typename >::to_string(), and utility_exit_with_message.

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::derivative_linear	(	X const &	x,
		Y &	y
	)		const

inlineprotected

The derivative of f(x), linearly interpolated.

For x between bins, this is just the slope of the interpolation line. For x on a bin the slope of the line to the right is used.

Note that the derivative will not be continuous when calculated in this way.

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative().

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::first_bin ( ) const

inline

The x-value of the left corner of the first bin.

References numeric::interpolation::Histogram< typename, typename >::min_.

Referenced by numeric::interpolation::Histogram< typename, typename >::bin_number().

template<typename , typename >

X& numeric::interpolation::Histogram< typename, typename >::first_bin ( )

inline

References numeric::interpolation::Histogram< typename, typename >::min_.

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::interpolate	(	X const &	x,
		Y &	y
	)		const

inline

Interpolates a density for a given x-value from the histogram.

Takes the periodicity and bin placement into account.

Parameters

[in]	x	The independant axis value to be interpolated
[out]	y	An approximation of f(x), as specified by the Interpolator

Returns: Whether the interpolated value was within the bounds or not. Periodic functions always return true.

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::interpolate	(	X const &	x,
		Y &	y,
		Real &	dy
	)		const

inline

Interpolates a density for a given x-value from the histogram.

Takes the periodicity and bin placement into account.

Parameters

[in]	x	The independant axis value to be interpolated
[out]	y	An approximation of f(x), as specified by the Interpolator
[out]	dy	derivative of f(x). Note: only with spline interpolator for now

Returns: Whether the interpolated value was within the bounds or not. Periodic functions always return true.

References numeric::interpolation::Histogram< typename, typename >::interpolate_spline(), numeric::interpolation::Histogram< typename, typename >::interpolator_, numeric::interpolation::Histogram< typename, typename >::spline, numeric::interpolation::Histogram< typename, typename >::to_string(), and utility_exit_with_message.

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::interpolate_flat	(	X const &	x,
		Y &	y
	)		const

inlineprotected

Returns the density of the bin which x belongs to.

If x is outside of the range of bins, returns zero.

References basic::options::OptionKeys::lh::fragpdb::bin, numeric::interpolation::Histogram< typename, typename >::bin_number(), numeric::interpolation::Histogram< typename, typename >::densities_, numeric::interpolation::Histogram< typename, typename >::maximum(), numeric::interpolation::Histogram< typename, typename >::minimum(), numeric::interpolation::Histogram< typename, typename >::nbins(), and numeric::interpolation::Histogram< typename, typename >::periodic_.

Referenced by numeric::interpolation::Histogram< typename, typename >::interpolate().

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::interpolate_linear	(	X const &	x,
		Y &	y
	)		const

inlineprotected

Referenced by numeric::interpolation::Histogram< typename, typename >::interpolate().

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::interpolate_spline	(	X const &	x,
		Y &	y,
		Real &	dy
	)		const

inline

References numeric::interpolation::spline::Interpolator::interpolate(), and numeric::interpolation::Histogram< typename, typename >::spline_interpolator_.

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative(), and numeric::interpolation::Histogram< typename, typename >::interpolate().

template<typename , typename >

Interpolator numeric::interpolation::Histogram< typename, typename >::interpolator ( ) const

inline

References numeric::interpolation::Histogram< typename, typename >::interpolator_.

template<typename , typename >

Interpolator& numeric::interpolation::Histogram< typename, typename >::interpolator ( )

inline

References numeric::interpolation::Histogram< typename, typename >::interpolator_.

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::last_bin ( ) const

inline

The x-value of the left corner of the last bin.

References numeric::interpolation::Histogram< typename, typename >::min_, numeric::interpolation::Histogram< typename, typename >::nbins(), and numeric::interpolation::Histogram< typename, typename >::step_.

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::last_bin_right ( ) const

inline

The x-value of the right corner of the last bin.

References numeric::interpolation::Histogram< typename, typename >::min_, numeric::interpolation::Histogram< typename, typename >::nbins(), and numeric::interpolation::Histogram< typename, typename >::step_.

Referenced by numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::maximum ( ) const

inline

The largest value for which we can interpolate.

All values of x where minimum()<=x<maximum() can be interpolated.

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate_flat(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::minimum ( ) const

inline

The smallest value for which we can interpolate.

All values of x where minimum()<=x<maximum() can be interpolated.

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate_flat(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

size_type numeric::interpolation::Histogram< typename, typename >::nbins ( ) const

inline

The number of bins.

References numeric::interpolation::Histogram< typename, typename >::densities_.

Referenced by numeric::interpolation::Histogram< typename, typename >::bin_number(), numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate_flat(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), numeric::interpolation::Histogram< typename, typename >::last_bin(), numeric::interpolation::Histogram< typename, typename >::last_bin_right(), numeric::interpolation::Histogram< typename, typename >::maximum(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::periodic ( ) const

inline

Return whether this histogram is periodic.

References numeric::interpolation::Histogram< typename, typename >::periodic_.

template<typename , typename >

bool& numeric::interpolation::Histogram< typename, typename >::periodic ( )

inline

References numeric::interpolation::Histogram< typename, typename >::periodic_.

template<typename , typename >

static void numeric::interpolation::Histogram< typename, typename >::read_from_db	(	std::istream &	db_file,
		utility::vector1< Y > &	energies,
		std::map< std::string, std::string > &	params
	)

inlinestaticprotected

Read a score function from the minirosetta_database into an array.

The scoring function should be represented as a list of Energies, one number per line. Lines begining with '#' are ignored as comments.

Files can contain parameter settings such as the range and step size. These are given by directives beginning with '@'.

Note: The database files should be ASCII. Unicode is not supported.

References utility::io::oc::cerr, utility::io::getline(), basic::options::OptionKeys::key, line, and value.

Referenced by numeric::interpolation::Histogram< typename, typename >::Histogram().

template<typename , typename >

void numeric::interpolation::Histogram< typename, typename >::set_params ( std::map< std::string, std::string > const & params )

inlineprotected

Set properties of this histogram from a map of strings.

Input is validated before being stored. Invalid input results in a printed warning and the previous (probably default) value being used instead.

Parameters currently recognised:

@minimum <X>
@maximum <X>
@step <X>
@periodic <bool>
@bins <BinPlacement>
@interpolator <Interpolator>

Referenced by numeric::interpolation::Histogram< typename, typename >::Histogram().

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::step_size ( ) const

inline

Return the distance between two bins.

References numeric::interpolation::Histogram< typename, typename >::step_.

template<typename , typename >

X& numeric::interpolation::Histogram< typename, typename >::step_size ( )

inline

References numeric::interpolation::Histogram< typename, typename >::step_.

template<typename , typename >

std::string numeric::interpolation::Histogram< typename, typename >::to_string ( Interpolator const & interpolator ) const

inline

References numeric::interpolation::Histogram< typename, typename >::flat, numeric::interpolation::Histogram< typename, typename >::linear, and numeric::interpolation::Histogram< typename, typename >::spline.

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative(), numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), numeric::interpolation::Histogram< typename, typename >::maximum(), and numeric::interpolation::Histogram< typename, typename >::minimum().

Member Data Documentation

template<typename , typename >

BinPlacement numeric::interpolation::Histogram< typename, typename >::bin_placement_

protected

Referenced by numeric::interpolation::Histogram< typename, typename >::bin_placement(), numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), numeric::interpolation::Histogram< typename, typename >::maximum(), numeric::interpolation::Histogram< typename, typename >::minimum(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

utility::vector1<Y> numeric::interpolation::Histogram< typename, typename >::densities_

protected

Referenced by numeric::interpolation::Histogram< typename, typename >::densities(), numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::Histogram(), numeric::interpolation::Histogram< typename, typename >::interpolate_flat(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), numeric::interpolation::Histogram< typename, typename >::nbins(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

Interpolator numeric::interpolation::Histogram< typename, typename >::interpolator_

protected

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::min_

protected

the x value of densities_[0]. Not actually the minimum for BinPlacement other than left.

Referenced by numeric::interpolation::Histogram< typename, typename >::first_bin(), numeric::interpolation::Histogram< typename, typename >::last_bin(), numeric::interpolation::Histogram< typename, typename >::last_bin_right(), numeric::interpolation::Histogram< typename, typename >::maximum(), numeric::interpolation::Histogram< typename, typename >::minimum(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

bool numeric::interpolation::Histogram< typename, typename >::periodic_

protected

Referenced by numeric::interpolation::Histogram< typename, typename >::derivative_linear(), numeric::interpolation::Histogram< typename, typename >::interpolate_flat(), numeric::interpolation::Histogram< typename, typename >::interpolate_linear(), numeric::interpolation::Histogram< typename, typename >::periodic(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

utility::pointer::owning_ptr< numeric::interpolation::spline::Interpolator > numeric::interpolation::Histogram< typename, typename >::spline_interpolator_

protected

Referenced by numeric::interpolation::Histogram< typename, typename >::interpolate_spline(), and numeric::interpolation::Histogram< typename, typename >::set_params().

template<typename , typename >

X numeric::interpolation::Histogram< typename, typename >::step_

protected

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

src/numeric/interpolation/Histogram.fwd.hh
src/numeric/interpolation/Histogram.hh

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

template<typename, typename> class numeric::interpolation::Histogram< typename, typename >

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename, typename>
class numeric::interpolation::Histogram< typename, typename >