name: Histogram

synopsis:

g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_stat.a

#include <Histogram.h>

~Histogram();
Histogram();
Histogram(const Histogram& copy_sym);

boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);
boolean setMode(BIN_MODE mode);
boolean setDim(long dim);
boolean setBins(const TVector& bins);
boolean setBins(long num_bins = DEF_NUM_BINS, TIntegral min = DEF_MIN, TIntegral max = DEF_MAX);
boolean setCounts(const TVector& counts);
boolean compute(const Vector<TVector>& values);
boolean pdf(VectorDouble& pdf) const;
boolean cdf(MatrixDouble& pdf);

quick start:

#include <Histogram.h>

// test a 2-D histogram with a specified number of bins in EDGES mode
//
MatrixDouble expected_cdf.assign(3, 3, L"0.4, 0.4, 0.4, 0.4, 0.8, 0.8, 0.4, 0.8, 1"), actual_cdf;
Vector test_data(2);
test_data(0).assign(L"1.1, 2.1, 3.1, 4.1, 5.1, 6.1, 4.1, 3.1, 2.1, 1.1");
test_data(1).assign(L"1.1, 2.1, 3.1, 4.1, 5.1, 7.1, 4.1, 3.1, 2.1, 1.1");

hist6.clear();
hist6.setScale(Histogram::LINEAR);
hist6.setMode(Histogram::EDGES);
hist6.setDim(2);
hist6.setBins(3, 1.0, 7.0);
hist6.compute(test_data);
hist6.cdf(actual_cdf);
if (!actual_cdf.almostEqual(expected_cdf)) {
  actual_cdf.debug(L"actual cdf");
  expected_cdf.debug(L"expected cdf");
  return Error::handle(name(), L"compute", Error::TEST, __FILE__,
    			 __LINE__);
}

description:

Histogram: a class for storing, computing, and updating multidimensional histograms of data. The Histogram class works under three binning scales

LINEAR: bins within each dimension are equal
LOG: bins within each dimension are logarithmically spaced
USER_DEFINED: bins within each dimension are defined by the user

In LINEAR and LOG scale binnings, the min, max values and the number of bins for each dimension can be specified.

The user can also specify how the bins are stored: using CENTERs or EDGES. This is more useful for the USER_DEFINED mode as the bins are manually set by the user only here:

CENTERS: bins are represented by their bin centers.
EDGES: bins are represented by their bin edges.

In both the modes, it is assumed that the centers or edges are in sorted order.

The base of the log in LOG scale binning is immaterial as all bases lead to same bins. If min and max are a and b, num bins is N, edge i in the log mode is given by:

c(i) = a * (b/a)^(i/N); which is independent of the base. Here log base-10 is chosen.

The dimension of the histogram is defined using setDim method.

There are several ways of setting up the bins by using the various setBins methods:

setBins(Vector& bins): In USER_DEFINED scale, specify bins for each dimension independently
setBins(TVector& bins): In USER_DEFINED scale, the same set of bins in each dimension
setBins(VectorLong& num_bins, TVector& min, TVector& max): In LINEAR and LOG scale, the bins are set using different bin parameters for each dimension
setBins(long num_bins, TIntegral min, TIntegral max): In LINEAR or LOG scale, the same kind of bins in all dimensions

The getCount, pdf and cdf methods return a single array the multidimensional index of which can be obtained using the method:

& bin_indices)

For computing one-dimensional histogram, use

For getting the pdf and cdf in two-dimensional histograms, use:

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"Histogram";

define i/o related constants:

static const String Histogram::DEF_PARAM = L"";

static const String Histogram::PARAM_SCALE = L"scale";

static const String Histogram::PARAM_MODE = L"mode";

static const String Histogram::PARAM_DIM = L"dim";

static const String Histogram::PARAM_MIN = L"min";

static const String Histogram::PARAM_MAX = L"max";

static const String Histogram::PARAM_NUM_BINS = L"num_bins";

static const String Histogram::PARAM_BINS = L"bins";

static const String Histogram::PARAM_COUNTS = L"counts";

define the static NameMap objects:

static const NameMap MODE_MAP(L"LINEAR, LOG, USER_DEFINED");

static const NameMap MODE_MAP(L"CENTERS, EDGES");

define the default value(s) of the class data:

static const long DEF_DIM = 1;

static const long DEF_MIN = 0;

static const long DEF_MAX = 1;

static const long DEF_NUM_BINS = 10;

define the mode choices:

enum BIN_MODE { EDGES = 0, CENTERS, DEF_MODE = EDGES};

define the scale choices:

enum SCALE { LINEAR = 0, LOG, USER_DEFINED, DEF_MODE = LINEAR};

error codes:

error code indicating a general error:

static const long ERR = 60500;

static const long ERR_BINS = 60501;

protected data:

define a bin mode flag:

SCALE scale_d;

define a bin mode flag:

BIN_MODE mode_d;

define dimension:

Long dim_d;

define variables of bins and counts

Vector<VectorDouble> bins_d;

VectorLong counts_d;

define max, min and num of bins

VectorDouble min_d, max_d;

VectorLong num_bins_d;

define boundary for blocks, to be used for indexing

VectorLong block_boundary_index_d;

VectorDouble delta_d;

debug level:
```
static Integral::DEBUG debug_level_d;
```
memory manager:
```
static MemoryManager mgr_d;
```

required public methods:

static methods:

static const String& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods:

static boolean setDebug(Integral::DEBUG debug_level);

boolean debug(const unichar* message) const;

destructor/constructor(s):

~Histogram();

Histogram(SCALE scale = DEF_SCALE, BIN_MODE mode = DEF_MODE, long dim = DEF_DIM);

Histogram(const Histogram& arg);

assign methods:
```
boolean assign(const Histogram& arg);
```

operator= methods:

Histogram& operator= (const Histogram& arg);

i/o methods:

long sofSize() const;

boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

equality methods:

boolean eq(const Histogram& compare_hist) const;

memory management methods:

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

Histogram set/get methods:

boolean setScale(SCALE scale);

boolean setMode(BIN_MODE mode);

boolean setDim(long dim);

template<class TVector> boolean setBins(const Vector<TVector>& bins);

template<class TVector> boolean setBins(const TVector& bins);

template<class TIntegral> boolean setBins(long num_bins = DEF_NUM_BINS, TIntegral min = DEF_MIN, TIntegral max = DEF_MAX);

template<class TVector> boolean setBins(const VectorLong& num_bins, const TVector& min, const TVector& max);

boolean setCounts(const VectorLong& counts);

SCALE getScale();

BIN_MODE getMode();

long getDim();

boolean getBins(Vector<VectorDouble>& bins);

boolean getBins(VectorLong& num_bins, VectorDouble& min, VectorDouble& max);

boolean getCounts(VectorLong& counts);

boolean getBinIndexCoordinates(Vector<VectorLong>& multidim_bin_index);

boolean getBlockBoundaryIndex(VectorLong& block_boundary_index);

compute and update methods:

template<class TVector> boolean compute(const Vector<TVector>& values);

template<class TVector> boolean compute(const TVector& values);

template<class TVector> boolean update(const Vector<TVector>& values);

template<class TVector> boolean update(const TVector& values);

probability distribution methods:

boolean pdf(VectorDouble& pdf) const;

boolean pdf(MatrixDouble& pdf);

boolean cdf(VectorDouble& cdf);

boolean cdf(MatrixDouble& cdf);

private methods:

method used to set block boundaries for indexing
```
boolean computeBlockBoundaryIndex();
```

method to search the index for a scalar value in 1-D
```
long findBinIndex(double value, long dim_num);
```

methods to convert between local indices and global index of a bin

boolean convertGlobalToLocalIndex(VectorLong& loc_ind, long glob_ind);

long convertLocalToGlobalIndex(VectorLong& loc_ind);

examples:

none

notes:

none