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

#include <Histogram.hh>

Inheritance diagram for numeric::interpolation::Histogram< X, Y >:

Public Types
enum	BinPlacement { left , center }

enum	Interpolator { flat , linear , spline }

using	size_type = numeric::Size

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 () override=default
	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 ()

void	set_interpolator (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	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::VirtualBase
	VirtualBase ()=default
	Default constructor. More...

virtual	~VirtualBase ()=default
	The virtual destructor is one of the main reasons for the VirtualBase class. More...

	VirtualBase (VirtualBase const &)=default

	VirtualBase (VirtualBase &&)=default

VirtualBase &	operator= (VirtualBase const &)=default

VirtualBase &	operator= (VirtualBase &&)=default

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...

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::shared_ptr< numeric::interpolation::spline::Interpolator >	spline_interpolator_

Detailed Description

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

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 Typedef Documentation

◆ size_type

template<typename X , typename Y >

using numeric::interpolation::Histogram< X, Y >::size_type = numeric::Size

Member Enumeration Documentation

◆ BinPlacement

template<typename X , typename Y >

enum numeric::interpolation::Histogram::BinPlacement

Enumerator
left
center

◆ Interpolator

template<typename X , typename Y >

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

◆ Histogram() [1/3]

template<typename X , typename Y >

numeric::interpolation::Histogram< X, Y >::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

◆ Histogram() [2/3]

template<typename X , typename Y >

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

inline

Copy Constructor.

◆ Histogram() [3/3]

template<typename X , typename Y >

numeric::interpolation::Histogram< X, Y >::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< X, Y >::densities_, evaluate_beta_mutants::file, basic::options::OptionKeys::dna::specificity::params, numeric::interpolation::Histogram< X, Y >::read_from_db(), and numeric::interpolation::Histogram< X, Y >::set_params().

◆ ~Histogram()

template<typename X , typename Y >

numeric::interpolation::Histogram< X, Y >::~Histogram ( )

inlineoverridedefault

destructor

Member Function Documentation

◆ bin_number()

template<typename X , typename Y >

platform::SSize numeric::interpolation::Histogram< X, Y >::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]

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

Returns: The index of bin x_l

References a, create_a3b_hbs::bin, numeric::interpolation::Histogram< X, Y >::first_bin(), numeric::modulo(), numeric::interpolation::Histogram< X, Y >::nbins(), numeric::interpolation::Histogram< X, Y >::step_, and x.

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

◆ bin_placement() [1/2]

template<typename X , typename Y >

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

inline

References numeric::interpolation::Histogram< X, Y >::bin_placement_.

◆ bin_placement() [2/2]

template<typename X , typename Y >

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

inline

The bin placement.

References numeric::interpolation::Histogram< X, Y >::bin_placement_.

◆ densities() [1/2]

template<typename X , typename Y >

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

inline

References numeric::interpolation::Histogram< X, Y >::densities_.

◆ densities() [2/2]

template<typename X , typename Y >

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

inline

The densities array.

References numeric::interpolation::Histogram< X, Y >::densities_.

◆ derivative()

template<typename X , typename Y >

bool numeric::interpolation::Histogram< X, Y >::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 enumerate_junctions::default, numeric::interpolation::Histogram< X, Y >::derivative_linear(), 3d_histogram::dy, numeric::interpolation::Histogram< X, Y >::flat, numeric::interpolation::Histogram< X, Y >::interpolate_spline(), numeric::interpolation::Histogram< X, Y >::interpolator_, numeric::interpolation::Histogram< X, Y >::linear, numeric::interpolation::Histogram< X, Y >::spline, numeric::interpolation::Histogram< X, Y >::to_string(), utility_exit_with_message, x, and predPRE::y.

◆ derivative_linear()

template<typename X , typename Y >

bool numeric::interpolation::Histogram< X, Y >::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< X, Y >::derivative().

◆ first_bin() [1/2]

template<typename X , typename Y >

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

inline

References numeric::interpolation::Histogram< X, Y >::min_.

◆ first_bin() [2/2]

template<typename X , typename Y >

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

inline

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

References numeric::interpolation::Histogram< X, Y >::min_.

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

◆ interpolate() [1/2]

template<typename X , typename Y >

bool numeric::interpolation::Histogram< X, Y >::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.

◆ interpolate() [2/2]

template<typename X , typename Y >

bool numeric::interpolation::Histogram< X, Y >::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 enumerate_junctions::default, 3d_histogram::dy, numeric::interpolation::Histogram< X, Y >::interpolate_spline(), numeric::interpolation::Histogram< X, Y >::interpolator_, numeric::interpolation::Histogram< X, Y >::spline, numeric::interpolation::Histogram< X, Y >::to_string(), utility_exit_with_message, x, and predPRE::y.

◆ interpolate_flat()

template<typename X , typename Y >

bool numeric::interpolation::Histogram< X, Y >::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 compute_difference::alpha, create_a3b_hbs::bin, numeric::interpolation::Histogram< X, Y >::bin_number(), numeric::interpolation::Histogram< X, Y >::densities_, numeric::interpolation::Histogram< X, Y >::maximum(), numeric::interpolation::Histogram< X, Y >::minimum(), numeric::interpolation::Histogram< X, Y >::nbins(), numeric::interpolation::Histogram< X, Y >::periodic_, x, and predPRE::y.

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

◆ interpolate_linear()

template<typename X , typename Y >

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

inlineprotected

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

◆ interpolate_spline()

template<typename X , typename Y >

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

inline

References 3d_histogram::dy, numeric::interpolation::Histogram< X, Y >::spline_interpolator_, x, and predPRE::y.

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

◆ interpolator() [1/2]

template<typename X , typename Y >

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

inline

References numeric::interpolation::Histogram< X, Y >::interpolator_.

◆ interpolator() [2/2]

template<typename X , typename Y >

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

inline

References numeric::interpolation::Histogram< X, Y >::interpolator_.

Referenced by numeric::interpolation::Histogram< X, Y >::set_interpolator(), and numeric::interpolation::Histogram< X, Y >::to_string().

◆ last_bin()

template<typename X , typename Y >

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

inline

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

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

◆ last_bin_right()

template<typename X , typename Y >

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

inline

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

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

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

◆ maximum()

template<typename X , typename Y >

X numeric::interpolation::Histogram< X, Y >::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< X, Y >::derivative_linear(), numeric::interpolation::Histogram< X, Y >::interpolate_flat(), numeric::interpolation::Histogram< X, Y >::interpolate_linear(), numeric::interpolation::Histogram< X, Y >::set_interpolator(), and numeric::interpolation::Histogram< X, Y >::set_params().

◆ minimum()

template<typename X , typename Y >

X numeric::interpolation::Histogram< X, Y >::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< X, Y >::derivative_linear(), numeric::interpolation::Histogram< X, Y >::interpolate_flat(), numeric::interpolation::Histogram< X, Y >::interpolate_linear(), numeric::interpolation::Histogram< X, Y >::set_interpolator(), and numeric::interpolation::Histogram< X, Y >::set_params().

◆ nbins()

template<typename X , typename Y >

Size numeric::interpolation::Histogram< X, Y >::nbins ( ) const

inline

The number of bins.

References numeric::interpolation::Histogram< X, Y >::densities_.

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

◆ periodic() [1/2]

template<typename X , typename Y >

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

inline

References numeric::interpolation::Histogram< X, Y >::periodic_.

◆ periodic() [2/2]

template<typename X , typename Y >

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

inline

Return whether this histogram is periodic.

References numeric::interpolation::Histogram< X, Y >::periodic_.

◆ read_from_db()

template<typename X , typename Y >

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