PROFASI  Version 1.5
Public Member Functions | List of all members
prf_utils::His1D Class Reference

The default histogram utility in ProFASi is based on His1D. More...

#include <His1D.hh>

Inheritance diagram for prf_utils::His1D:
Inheritance graph
[legend]

Public Member Functions

 His1D ()
 Default constructor.
 
 His1D (int nbl)
 Create His1D with nbl blocks (create nbl histograms)
 
 His1D (double xmn, double xmx, int npnts, int numblocks=1)
 Construct with xmin, xmax, number of bins and number of blocks.
 
 His1D (double xmn, double xmx, double bnsz, int numblocks=1)
 Construct with xmin, xmax, bin size and number of blocks.
 
 His1D (const His1D &)
 Copy constructor (copies data, so do not initialize after this!)
 
His1Doperator= (const His1D &)
 Assignment operator (copies data, do not initialize after this!)
 
void Name (std::string nm)
 Give it a name.
 
void init ()
 Initializes using info about range etc.
 
void reset ()
 Reset all data (init calls this)
 
void NBlocks (int n)
 Make it a histogram of n blocks.
 
int NBlocks () const
 Return the number of blocks.
 
long n_entries (int i) const
 number of entries in block i
 
long n_entries_in_range (int i) const
 number of entries in block i in range
 
void Range (double x0, double x1)
 Set range.
 
void Nbins (int v)
 Set number of bins.
 
int Nbins () const
 Get number of bins.
 
void set_bin_size (double sz)
 Set bin size.
 
double Xmin () const
 Get xmin.
 
double Xmax () const
 Get xmax.
 
double Xbin () const
 Get bin size.
 
double xval (int i)
 x value for the middle of i'th bin
 
double yval (int iblk, int i)
 y value for the middle of i'th bin
 
int put (double x, int iblk=0)
 put value x into the iblk block
 
int nput (double howmanytimes, double x, int iblk)
 put n indentical values at once
 
double normalize ()
 normalize histogram so that each block sums to 1
 
double unnormalize ()
 unnormalize histogram so that each block sums to its occupancy
 
virtual void Export (const char *filename, int normmode=2, int datlayout=2)
 Export data in text format to a given file.
 
int Import (const char *filename)
 Import histogram data written in the format of Export function.
 
virtual His1Doperator+= (His1D &)
 Add information from another given histogram.
 

Detailed Description

This class can be used to construct histograms of one variable in ProFASi. In practice, the derived class AdaptiveHis, which can adjust its own range is used. But most of the functionality of the histograms is implemented in His1D, and is described here. Typical use:

  His1D his;
  his.Range(0,25);
  his.NBins(100);
  his.init();
  while (you are doing something useful) {
     do_some_great_calculations();
     x=a_very_important_number();
     his.put(x);
  }
  his.Export("his_avim.dat");

When you "put" lots of numbers into a His1D object as above, it measures how often the values you put were in different bins. The bins are calculated between the range you provide and the number of bins you set. Upon "Export()", you get a file with what the histogram has measured. Just how the measured histograms are reported in the output file varies, and needs a bit more explanation.

Normalization

A histogram may or may not be normalized. If it is not normalized, the y values for each x bin is simply the frequency of data points in the range (x-0.5*dx, x+0.5*dx). There is a function normalize() that can ask the histogram to normalize its data, so that the sum of the y values for all x bins is 1. The normalization can be undone with the unnormalize() function. But an explicit call to normalize() is normally not necessary. When the histogram is saved, the data written to the file is normalized, without changing the internal frequency counts. This way, a histogram can save normalized data at intermediate stages during a run, without messing up the frequencies. So, you don't normally need to call normalize().

Sometimes, the absolute observed frequencies rather than normalized data is of interest. So, it should be possible to save them. Therefore, the function "Export()" can be given a normalization mode parameter.

his.Export("his_avim.dat",0);

The raw frequencies are then saved with no normalization. Two additional modes of normalization are supported. Normalization mode 1 means that the sum of the values at all bins is 1. In normalization mode 2, sum of the values at each bin multiplied by the bin sizes is 1. In mode 1, two histograms of the same data, with different bin sizes, will superficially look different when plotted. The one with bigger bins will end up with larger amplitudes. In mode 2, the height of the histogram plots will be unchanged when bin size is changed.

Histogram data blocks

Another important aspect of His1D objects is that they are intrinsically indexed. Meaning, if you need 8 histograms for the same quantity corresponding to 8 values of some state designator, you only need one His1D. But you give it 8 blocks with the NBlocks(int) function. As an example, we take a parallel tempering run with 64 temperatures. Histograms of energy at every temperature is interesting. But then we end up with 64 histograms for total energy, and 64 again for every other quantity we wish to measure. In situations like this, you create a His1D object with many blocks, 64 in this case. Data for different blocks are written into the same output file, and of course, each block is separately normalized. In principle, this is just a way to combine related histograms into one file for the output, and one object for less cumbersome handling in the program.

Data layout in ProFASi histogram files

There are two supported layouts for the histogram data. One can choose the desired layout by passing an additional parameter to "Export()".

his.Export("his_avim.dat", 2,2);

The layout referred to as "profasi_his_v1" is the layout familiar to ProFASi users from older versions of the program. The data blocks are organized as:

  b0 x0 y00
  b0 x1 y01
  b0 x2 y02
  b0 x3 ...
  ...
  blank line
  b1 x0 y10
  b1 x1 y11
  etc.

In the above, b0, b1 etc were integer block identifiers. The different blocks could represent, for instance, different temperatures. Plotting this kind of a histogram file in GNUPLOT is easy:

gnuplot> p "myhis.dat" u 2:3 w l

This gives one line for each block. But this format is not very economic. The X values are repeated in every block. The numbers b0, b1 etc are written many times. The second supported format addresses these issues. The layout referred to as "profasi_his_v2" is like this:

  x0 y00 y10 y20 y30 ...
  x1 y01 y11 y21 y31 ...
  x2 y02 y12 y22 y31 ...
  etc.

The first column has the X values. The subsequent columns have the Y data for blocks 0, 1, 2 ... The block numbers are never written. The X values are written once. To plot it in GNUPLOT write:

gnuplot> p "myhis.dat" u 1:someblock w l

This will plot only one line at a time, depending on what block you choose.

If the histogram has only a single block, the block id is always 0 and is not written even in the layout profasi_his_v1. In this situation, the two layouts are equivalent. Histograms generated with ProFASi versions up to 1.2 were always in layout profasi_his_v1. In version 1.5, the default layout is changed to profasi_his_v2. The program his1dmerge (See Merging and converting ProFASi histograms with his1dmerge) can be used to change histogram data layout as well as normalization modes.

See Also
his1dmerge

Constructor & Destructor Documentation

His1D::His1D ( double  xmn,
double  xmx,
double  bnsz,
int  numblocks = 1 
)

The given range (xmn, xmx) is symmetrically extended to accommodate an integral number of bins of the requested size, if needed.

Member Function Documentation

void His1D::Export ( const char *  filename,
int  normmode = 2,
int  datlayout = 2 
)
virtual

Choose between different normalization modes and data layout options as described above.

Reimplemented in prf_utils::AdaptiveHis.

void His1D::set_bin_size ( double  sz)

Create bins of a given size. The existing histogram range is extended to accommmodate an integral number of bins.


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

PROFASI: Protein Folding and Aggregation Simulator, Version 1.5
© (2005-2016) Anders Irbäck and Sandipan Mohanty
Documentation generated on Mon Jul 18 2016 using Doxygen version 1.8.2