Rosetta Utilities  2014.35
Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
numeric::interpolation::Histogram< typename, typename > Class Template Reference

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 ()
 
first_bin () const
 The x-value of the left corner of the first bin. More...
 
X & first_bin ()
 
last_bin () const
 The x-value of the left corner of the last bin. More...
 
last_bin_right () const
 The x-value of the right corner of the last bin. More...
 
step_size () const
 Return the distance between two bins. More...
 
X & step_size ()
 
bool periodic () const
 Return whether this histogram is periodic. More...
 
boolperiodic ()
 
BinPlacement bin_placement () const
 The bin placement. More...
 
BinPlacementbin_placement ()
 
Interpolator interpolator () const
 
Interpolatorinterpolator ()
 
minimum () const
 The smallest value for which we can interpolate. More...
 
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...
 
ReferenceCountoperator= (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_
 
min_
 the x value of densities_[0]. Not actually the minimum for BinPlacement other than left. More...
 
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:

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: numeric::Real, float, double
YThe 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
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 , 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
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< 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
template<typename , typename >
BinPlacement& numeric::interpolation::Histogram< typename, typename >::bin_placement ( )
inline
template<typename , typename >
utility::vector1<Y> numeric::interpolation::Histogram< typename, typename >::densities ( ) const
inline
template<typename , typename >
utility::vector1<Y>& numeric::interpolation::Histogram< typename, typename >::densities ( )
inline
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]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< 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
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::first_bin ( ) const
inline
template<typename , typename >
X& numeric::interpolation::Histogram< typename, typename >::first_bin ( )
inline
template<typename , typename >
bool numeric::interpolation::Histogram< typename, typename >::interpolate ( X const &  x,
Y &  y 
) const
inline
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]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< 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
template<typename , typename >
bool numeric::interpolation::Histogram< typename, typename >::interpolate_linear ( X const &  x,
Y &  y 
) const
inlineprotected
template<typename , typename >
bool numeric::interpolation::Histogram< typename, typename >::interpolate_spline ( X const &  x,
Y &  y,
Real dy 
) const
inline
template<typename , typename >
Interpolator numeric::interpolation::Histogram< typename, typename >::interpolator ( ) const
inline
template<typename , typename >
Interpolator& numeric::interpolation::Histogram< typename, typename >::interpolator ( )
inline
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::last_bin ( ) const
inline
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::last_bin_right ( ) const
inline
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::maximum ( ) const
inline
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::minimum ( ) const
inline
template<typename , typename >
size_type numeric::interpolation::Histogram< typename, typename >::nbins ( ) const
inline
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
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>

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

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
template<typename , typename >
std::string numeric::interpolation::Histogram< typename, typename >::to_string ( Interpolator const &  interpolator) const
inline

Member Data Documentation

template<typename , typename >
BinPlacement numeric::interpolation::Histogram< typename, typename >::bin_placement_
protected
template<typename , typename >
utility::vector1<Y> numeric::interpolation::Histogram< typename, typename >::densities_
protected
template<typename , typename >
Interpolator numeric::interpolation::Histogram< typename, typename >::interpolator_
protected
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::min_
protected
template<typename , typename >
bool numeric::interpolation::Histogram< typename, typename >::periodic_
protected
template<typename , typename >
utility::pointer::owning_ptr< numeric::interpolation::spline::Interpolator > numeric::interpolation::Histogram< typename, typename >::spline_interpolator_
protected
template<typename , typename >
X numeric::interpolation::Histogram< typename, typename >::step_
protected

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