# histc2

## PURPOSE

Multidimensional histogram count with weighted values.

## SYNOPSIS

function h = histc2( A, edges, wtMask )

## DESCRIPTION

``` Multidimensional histogram count with weighted values.

Creates a histogram h of the values in A [n x nd], with edges as
specified. If nd==1, that is when A is a vector, the resulting histogram
h is a vector of length nBins, where nBins=length(edges)-1. h(q) contains
the weighted count of values v in A such that edges(q) <= v < edges(q+1).
h(nBins) additionally contains the weighted count of values in A such
that v==edges(nBins+1) -- which is different then how histc treates the
boundary condition. Finally, h is normalized so that sum(h(:))==1.

It usually makes sense to specify edges explicitly, especially if
different histograms are going to be compared.  In general, edges must
have monotonically non-decreasing values.  Also, if the exact bounds are
unknown then it is convenient to set the first element in edges to -inf
and the last to inf.  If h = histc2( A, nBins, ...), edges are
automatically generated and have bins equally spaced between min(A) and
max(A). That is the edges vector is generated by:
edges = linspace( min(A)-eps, max(A)+eps, nBins+1 );

If nd>1, that is when A is a 2d matrix instead of a vector, the created
histogram is multi-dimensional with dimensions nBins^nd, where each bin
h(q1,...,qnd) contains the the weighted count of vectors v in A such that
edges{k}(qk) <= v(k) < edges{k}(qk+1), for k=1,...,nd.  Note that if nd>1
edges may be a cell vector where each element is a vector of edges or a
scalar nBins as before.

Each value in A may optionally have an associated weight given by wtMask,
which should have the same number of elements as A. If not specified, the

USAGE
h = histc2( A, edges, [wtMask] )

INPUTS
A           - [n x nd] 2D numeric array
edges       - quantization bounds, see above
wtMask      - [] length [n] vector of weights

OUTPUTS
h           - nd histogram [nBins^nd]

EXAMPLE - 1D histograms
A=filterGauss([1000 1000],[],[],0); A=A(:); n=length(A);
h1 = histc2( A, 25 );              figure(1); bar(h1);
h2 = histc2( A, 25, ones(n,1) );   figure(2); bar(h2);
h3 = histc2( A, 25, A );           figure(3); bar(h3);

EXAMPLE - 2D histograms
A=filterGauss([1000 1000],[],[],0); A=A(:); n=length(A);
h=histc2( [A A], 25 );    figure(1); im(h);  % decreasing along diag
h=histc2( [A A], 25, A ); figure(2); im(h);  % constant along diag