prf_utils::AdaptiveHis Class Reference
[Utilities]

A histogram that can adjust its own range according to the data. More...

#include <AdaptiveHis.hh>

Inheritance diagram for prf_utils::AdaptiveHis:


Public Member Functions
	AdaptiveHis ()
	Default constructor.
	AdaptiveHis (const AdaptiveHis &)
	Copy constructor.
AdaptiveHis &	operator= (const AdaptiveHis &)
	Assignment operator.
void	init ()
	Initializes using info about range etc.
void	reset ()
	Reset all data (init calls this).
int	adjust ()
	Adjust range to accommodate data, keeping bin size fixed.
int	put (double x, int i=0)
	Put a value into the histogram.
int	nput (int howmanytimes, double x, int iblk)
	put n indentical values at once
void	Export (const char *filename, int normmode=2)
	Save histogram and out of range points to files.

Detailed Description

This is a minor modification of the His1D class that frees the user from estimating a good range for a histogram before starting to fill it. When one starts a Monte Carlo run with a new protein, or in any other application where a histogram may be required, one has often no idea where the values of one measurement might lie. Before version 1.1 of PROFASI, one had to first make a trial run to get a good feeling for the true range of the data, and then start new production runs where the correct histogram ranges were specified. To a large extent, this will now be unnecessary.

This histogram follows the data, wherever it is. You just have to declare an AdaptiveHis, fill it with data, ask it to "adjust()" once in a while, and Export() it to a file. If you then plot the file, it will have a very reasonable range: not too many empty bins on left and right. Not too many missed data points.

This does not mean that one does not need to think about the size of the values put into the histograms at all. The adjust() function does not change the size of the bins used for the histogram. That's how it works! If there are many points outside the current range, the class remembers those missed points. When statistics is collected we pretend that there were an infinite number of bins of the size set at initialization. We only choose to do the book keeping on a finite range of those bins. If there are points outside our currently tracked bins, we can add a few bins to the left or right to accommodate them, without affecting the collected data at all. If we were to change the bin size during an adjustment, that would interfere with the data collected before adjust() was called.

So, an initial guess for the size of the data is useful. More precisely a good initial estimate of the size of the bins is useful. If the minimum or maximum ranges are wrong, this class will take care of it. If your data values range from 3000 to 10000 and you initialize your AdaptiveHis to a range 0 to 1 with 100 bins, The adjust function will result in a huge histogram. It will have a range 3000 to 10000, with 700000 bins. But if you initialize it to 2000 to 4000 with 50 bins, you will be fine. It will once again find the correct range, but will have less than 200 bins.

This class is newly introduced in version 1.1, and it is not yet clear whether it deserves to be a separate class than His1D. After a few months of use, the functionality might be absorbed in His1D.

Member Function Documentation

AdaptiveHis & prf_utils::AdaptiveHis::operator= ( const AdaptiveHis & )

It copies data, do not initialize after this!

void prf_utils::AdaptiveHis::disable_adjust ( ) [inline]

Disable/enable range tracking features. One can temporarily disable the "adaptive" qualities of the histogram. This is intended for use, if it is known that the incomming data for a certain stage of the program can contain non-sensical values which should have no bearing on the range. When "adjustability" is disabled, the histogram forgets new out of range values, until it is re-enabled.

int prf_utils::AdaptiveHis::adjust ( )

Appropriate range for the data is found by examining out of range points, and the occupancy of currently used bins. We add bins, only if we can fill them. The fundamental reason for the existance of any kind of histograms is that one does not wish to save each and every data point. "Similar" data points are groupped, or binned together. Now if there is one data point outside the current range, such that we would need add 100 bins to the right to reach that datapoint, the use of the histogram itself loses its meaning, if we do that. It is more economical to save that data point than to create 100 more bins and remember the frequency of each. Therefore, even after repeated calls to adjust, there might be one remaining out-of-range point that this class simply refuses to cover. When the histogram is saved, such points, if any, are saved in a separate file, and you can deal with them if you like.

Return value is non-zero if the range really changes.

int prf_utils::AdaptiveHis::put	(	double	x,
		int	i = `0`
	)

The value x is put into the histogram if it fits in the range. If not, it is stored in the out-of-range list. The adjust function deals with these out of range points and may put them into bins when the range is appropriately extended.

Reimplemented from prf_utils::His1D.

void prf_utils::AdaptiveHis::Export	(	const char *	filename,
		int	normmode = `2`
	)			`[virtual]`

The histogram data is saved in as (block_id_i, xi, yi) tripplets, as in class His1D. The same normalization conventions are also used. But this class also saves the out-of-range points not covered by the final range(those the function adjust() refuses to include), in a second file with the same name as the histogram file, but with an extension ".out_of_range" at the end.

Reimplemented from prf_utils::His1D.

void prf_utils::AdaptiveHis::disable_adjust ( ) [inline]

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

model/Aux/AdaptiveHis.hh
model/Aux/AdaptiveHis.cc

prf_utils::AdaptiveHis Class Reference [Utilities]

Public Member Functions

Detailed Description

Member Function Documentation

prf_utils::AdaptiveHis Class Reference
[Utilities]