Rosetta 3.3
Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes
numeric::interpolation::Histogram< X, Y > Class Template Reference

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

#include <Histogram.hh>

Inheritance diagram for numeric::interpolation::Histogram< X, Y >:
Inheritance graph
[legend]
Collaboration diagram for numeric::interpolation::Histogram< X, Y >:
Collaboration graph
[legend]

List of all members.

Public Types

enum  BinPlacement { left, center }
enum  Interpolator { flat, linear, spline }

Public Member Functions

 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.
 Histogram (Histogram const &h)
 Copy Constructor.
 Histogram (std::istream &file)
 Generate Histogram from a file.
 ~Histogram ()
 destructor
utility::vector1< Y > densities () const
 The densities array.
utility::vector1< Y > & densities ()
first_bin () const
 The x-value of the left corner of the first bin.
X & first_bin ()
last_bin () const
 The x-value of the left corner of the last bin.
last_bin_right () const
 The x-value of the right corner of the last bin.
step_size () const
 Return the distance between two bins.
X & step_size ()
bool periodic () const
 Return whether this histogram is periodic.
boolperiodic ()
BinPlacement bin_placement () const
 The bin placement.
BinPlacementbin_placement ()
Interpolator interpolator () const
Interpolatorinterpolator ()
minimum () const
 The smallest value for which we can interpolate.
maximum () const
 The largest value for which we can interpolate.
size_type nbins () const
 The number of bins.
bool interpolate (X const &x, Y &y) const
 Interpolates a density for a given x-value from the histogram.
bool interpolate (X const &x, Y &y, Real &dy) const
 Interpolates a density for a given x-value from the histogram.
bool derivative (X const &x, Y &dy) const
 The derivative of f(x), linearly interpolated.
bool interpolate_spline (X const &x, Y &y, Real &dy) const

Protected Member Functions

void set_params (std::map< std::string, std::string > const &params)
 Set properties of this histogram from a map of strings.
ssize_t bin_number (X const &x, X &a) const
 get the number of the bin to the left of X.
bool interpolate_flat (X const &x, Y &y) const
 Returns the density of the bin which x belongs to.
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.

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.

Protected Attributes

utility::vector1< Y > densities_
min_
 the x value of densities_[0]. Not actually the minimum for BinPlacement other than left.
step_
bool periodic_
BinPlacement bin_placement_
Interpolator interpolator_
utility::pointer::owning_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:

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

Template Parameters:
XThe range of the function. Should support the operations expected of real types. Examples: core::Real, float, double
YThe domain of the function. Should support the operations expected of real types.

Member Enumeration Documentation

template<typename X , typename Y >
enum numeric::interpolation::Histogram::BinPlacement
Enumerator:
left 
center 
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

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:
densitiesA vector giving the densities of each bin
first_binThe x-value of the first bin
step_sizeThe width of each bin
bin_placementIndicate what x-value the bins are mapped to: the left corner, the center of the bin, or the right corner
template<typename X , typename Y >
numeric::interpolation::Histogram< X, Y >::Histogram ( Histogram< X, Y > const &  h) [inline]

Copy Constructor.

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

template<typename X , typename Y >
numeric::interpolation::Histogram< X, Y >::~Histogram ( ) [inline]

destructor


Member Function Documentation

template<typename X , typename Y >
ssize_t numeric::interpolation::Histogram< X, Y >::bin_number ( X const &  x,
X &  a 
) const [inline, protected]

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 numeric::interpolation::periodic_range::full::bin(), numeric::interpolation::Histogram< X, Y >::first_bin(), numeric::modulo(), numeric::interpolation::Histogram< X, Y >::nbins(), numeric::interpolation::Histogram< X, Y >::step_, and ObjexxFCL::fmt::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().

template<typename X , typename Y >
BinPlacement numeric::interpolation::Histogram< X, Y >::bin_placement ( ) const [inline]
template<typename X , typename Y >
BinPlacement& numeric::interpolation::Histogram< X, Y >::bin_placement ( ) [inline]
template<typename X , typename Y >
utility::vector1<Y>& numeric::interpolation::Histogram< X, Y >::densities ( ) [inline]
template<typename X , typename Y >
utility::vector1<Y> numeric::interpolation::Histogram< X, Y >::densities ( ) const [inline]
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]xThe point on the independant axis for which to get the derivative
[out]dyAn approximation of df/dx, cast to a Y.

References numeric::interpolation::Histogram< X, Y >::derivative_linear(), 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, and utility_exit_with_message.

template<typename X , typename Y >
bool numeric::interpolation::Histogram< X, Y >::derivative_linear ( X const &  x,
Y &  y 
) const [inline, protected]
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().

template<typename X , typename Y >
X& numeric::interpolation::Histogram< X, Y >::first_bin ( ) [inline]
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]xThe independant axis value to be interpolated
[out]yAn 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.

References numeric::interpolation::Histogram< X, Y >::flat, numeric::interpolation::Histogram< X, Y >::interpolate_flat(), numeric::interpolation::Histogram< X, Y >::interpolate_linear(), 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, and utility_exit_with_message.

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]xThe independant axis value to be interpolated
[out]yAn approximation of f(x), as specified by the Interpolator
[out]dyderivative 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< X, Y >::interpolate_spline(), numeric::interpolation::Histogram< X, Y >::interpolator_, numeric::interpolation::Histogram< X, Y >::spline, and utility_exit_with_message.

template<typename X , typename Y >
bool numeric::interpolation::Histogram< X, Y >::interpolate_flat ( X const &  x,
Y &  y 
) const [inline, protected]
template<typename X , typename Y >
bool numeric::interpolation::Histogram< X, Y >::interpolate_linear ( X const &  x,
Y &  y 
) const [inline, protected]
template<typename X , typename Y >
bool numeric::interpolation::Histogram< X, Y >::interpolate_spline ( X const &  x,
Y &  y,
Real dy 
) const [inline]
template<typename X , typename Y >
Interpolator& numeric::interpolation::Histogram< X, Y >::interpolator ( ) [inline]
template<typename X , typename Y >
Interpolator numeric::interpolation::Histogram< X, Y >::interpolator ( ) const [inline]
template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::last_bin ( ) const [inline]
template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::last_bin_right ( ) const [inline]
template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::maximum ( ) const [inline]
template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::minimum ( ) const [inline]
template<typename X , typename Y >
size_type numeric::interpolation::Histogram< X, Y >::nbins ( ) const [inline]
template<typename X , typename Y >
bool& numeric::interpolation::Histogram< X, Y >::periodic ( ) [inline]
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_.

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 
) [inline, static, protected]

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, ObjexxFCL::getline(), key, get_pdb::line, and value.

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

template<typename X , typename Y >
void numeric::interpolation::Histogram< X, Y >::set_params ( std::map< std::string, std::string > const &  params) [inline, protected]

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>

References numeric::interpolation::spline::SplineGenerator::add_known_value(), numeric::interpolation::Histogram< X, Y >::bin_placement_, numeric::interpolation::Histogram< X, Y >::center, utility::io::oc::cerr, numeric::interpolation::Histogram< X, Y >::densities_, numeric::eq_tol(), numeric::interpolation::Histogram< X, Y >::flat, gen, numeric::interpolation::spline::SplineGenerator::get_interpolator(), color_pdb::i, numeric::interpolation::Histogram< X, Y >::interpolator_, key, numeric::interpolation::Histogram< X, Y >::last_bin_right(), numeric::interpolation::Histogram< X, Y >::left, numeric::interpolation::Histogram< X, Y >::linear, numeric::max(), numeric::interpolation::Histogram< X, Y >::maximum(), numeric::min(), numeric::interpolation::Histogram< X, Y >::min_, numeric::interpolation::Histogram< X, Y >::minimum(), numeric::interpolation::Histogram< X, Y >::nbins(), numeric::interpolation::Histogram< X, Y >::periodic_, numeric::interpolation::Histogram< X, Y >::spline, numeric::interpolation::Histogram< X, Y >::spline_interpolator_, numeric::interpolation::Histogram< X, Y >::step_, utility_exit_with_message, and value.

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

template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::step_size ( ) const [inline]

Return the distance between two bins.

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

template<typename X , typename Y >
X& numeric::interpolation::Histogram< X, Y >::step_size ( ) [inline]

Member Data Documentation

template<typename X , typename Y >
BinPlacement numeric::interpolation::Histogram< X, Y >::bin_placement_ [protected]
template<typename X , typename Y >
utility::vector1<Y> numeric::interpolation::Histogram< X, Y >::densities_ [protected]
template<typename X , typename Y >
Interpolator numeric::interpolation::Histogram< X, Y >::interpolator_ [protected]
template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::min_ [protected]
template<typename X , typename Y >
bool numeric::interpolation::Histogram< X, Y >::periodic_ [protected]
template<typename X , typename Y >
X numeric::interpolation::Histogram< X, Y >::step_ [protected]

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines