histograms/@Hist (OctApps Reference Manual)

2.15 `histograms/@Hist`

Function File: hgrm = addDataToHist ( hgrm, data )

Adds the given input data to the histogram. If the histogram is too small, more bins are added.

Arguments

hgrm: histogram object
data: input histogram data

Examples

assert(histBins(addDataToHist(Hist(1, {"lin", "dbin", 1}), -2), 1, "finite", "bins")', -2:0)

assert(histBins(addDataToHist(Hist(1, {"lin", "dbin", 1}), -1), 1, "finite", "bins")', -1:0)

assert(histBins(addDataToHist(Hist(1, {"lin", "dbin", 1}),  0), 1, "finite", "bins")',  0:1)

assert(histBins(addDataToHist(Hist(1, {"lin", "dbin", 1}),  1), 1, "finite", "bins")',  0:2)

assert(histBins(addDataToHist(Hist(1, {"lin", "dbin", 1}),  2), 1, "finite", "bins")',  0:3)

assert(histProbs(addDataToHist(Hist(1, {"lin", "dbin", 1}), -2), "finite")', [1 0])

assert(histProbs(addDataToHist(Hist(1, {"lin", "dbin", 1}), -1), "finite")', [1])

assert(histProbs(addDataToHist(Hist(1, {"lin", "dbin", 1}),  0), "finite")', [1])

assert(histProbs(addDataToHist(Hist(1, {"lin", "dbin", 1}),  1), "finite")', [0 1])

assert(histProbs(addDataToHist(Hist(1, {"lin", "dbin", 1}),  2), "finite")', [0 0 1])

assert(histBins(addDataToHist(Hist(1, {"log", "binsper10", 1}), 0.9), 1, "finite", "bins")', -1:1, 1e-6)

assert(histBins(addDataToHist(Hist(1, {"log", "binsper10", 10}), 0.9), 1, "finite", "bins")', -1:0.1:1, 1e-6)

assert(histBins(addDataToHist(Hist(1, {"log", "minrange", 1, "binsper10", 10}), 0.9), 1, "finite", "bins")', -1:0.1:1, 1e-6)

assert(histBins(addDataToHist(Hist(1, {"log", "minrange", 1, "binsper10", 10}), 1.1), 1, "finite", "bins")', [-1:0.1:1, 2:10], 1e-6)

assert(histBins(addDataToHist(Hist(1, {"log", "minrange", 1, "binsper10", 10}), -10.1), 1, "finite", "bins")', [-100:10:-10, -9:-2, -1:0.1:1], 1e-6)

Function File: hgrmt = addHists ( addop, hgrms… )

Add multiple histograms together.

Arguments

addop

operation used to add histograms:

count: sum histogram counts
prob: sum histogram probabilities

hgrms

histograms to add; [] arguments are ignored

hgrmt

total histogram

Examples

hgrm1 = addDataToHist(Hist(1, 0:12), 0.5 + (0:11)');
hgrm2 = addDataToHist(Hist(1, 0:3:12), 0.5 + (0:11)');
hgrmt = addHists("count", hgrm1, hgrm2);
p = histProbs(hgrmt);
assert(length(p) == 14 && p(2:end-1) == 1/12);

hgrms = arrayfun(@(x) addDataToHist(Hist(1, 0:12), 0.5 + x), 0:11, "UniformOutput", false);
hgrmt = addHists("count", hgrms{:});
p = histProbs(hgrmt);
assert(length(p) == 14 && p(2:end-1) == 1/12);

Function File: hgrm = contractHist ( hgrm, newdims )

Contract a histogram by summing counts over dimensions.

Arguments

hgrm: histogram object
newdims: dimensions that will remain after contraction; counts in other dimensions will be summed.

Examples

hgrm = Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1});
hgrm = addDataToHist(hgrm, [octforge_normrnd(0, 1, 1e6, 1), rand(1e6, 1)]);
hgrm1 = contractHist(hgrm, 1);
hgrm2 = contractHist(hgrm, 2);

p2 = histProbs(hgrm2); c2 = histBinGrids(hgrm2, 1, "centre");
assert(mean(abs(p2(isfinite(c2)) - 1.0)) < 1e-2);

Function File: display ( hgrm )

Display a histogram object.

Arguments

hgrm: histogram object

Examples

display(Hist())
display(Hist(1, {"lin", "dbin", 0.1}))
display(Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}))
display(Hist(3, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}))
display(Hist(4, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}))
display(Hist(5, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}))

Function File: x = drawFromHist ( hgrm, N )

Generates random values drawn from the probability distribution given by the histogram.

Arguments

hgrm: histogram object
N: number of random values to generate
x: generated random values

Examples

hgrmA = Hist(1, {"lin", "dbin", 0.1});
hgrmB = Hist(1, {"log", "minrange", 0.1, "binsper10", 8});
hgrmC = Hist(2, {"lin", "dbin", 0.1}, {"log", "minrange", 1.0, "binsper10", 8});
N = 1e6;
do
  x = randn(N, 2);
  oldhgrmA = hgrmA;
  hgrmA = addDataToHist(hgrmA, x(:,1));
  hgrmB = addDataToHist(hgrmB, x(:,1));
  hgrmC = addDataToHist(hgrmC, x(:,1:2));
  histerr = histDistance(oldhgrmA, hgrmA);
until histerr < 1e-2

thgrmA = Hist(1, {"lin", "dbin", 0.1});
x = drawFromHist(hgrmA, N);
thgrmA = addDataToHist(thgrmA, x);
assert(histDistance(hgrmA, thgrmA) < 0.01);

thgrmC = Hist(2, {"lin", "dbin", 0.1}, {"log", "minrange", 1.0, "binsper10", 8});
x = drawFromHist(hgrmC, 20*N);
thgrmC = addDataToHist(thgrmC, x);
assert(histDistance(hgrmC, thgrmC) < 0.01);

Function File: hgrm = Hist ( dim, type… )

Create a new object representing a multi-dimensional histogram.

Arguments

hgrm

histogram object

dim

dimensionality of the histogram

type

bin types, one per dimension; possible types:

{lin, dbin, ‘bin width’, …, bin0, ‘starting bin (default 0)’}
{log, minrange, ‘starting minimal bin range (default: auto)’, …, binsper10, ‘number of bins to add per decade’}
[‘bin’, ‘bin’, …]
Fixed array of bins, cannot be extended

Examples

See the tutorial on Hist.

Function File: [ binq, … ] = histBinsGrids ( hgrm, k, type, … )

Return quantities relating to the histogram bin boundaries, in gridded arrays of the same size as the probability array.

Arguments

hgrm: histogram object
k: dimension along which to return bin quantities
type: see histBins()
binq: bin quantities

Examples

hgrm = restrictHist(addDataToHist(Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}), octforge_unifrnd(0, 1, 1e6, 2)));
sert(histBinGrids(hgrm, 1, "lower"), [-inf, 0:0.1:0.9, inf]' * ones(1, 12), 1e-3)
sert(histBinGrids(hgrm, 1, "centre"), [-inf, 0.05:0.1:0.95, inf]' * ones(1, 12), 1e-3)
sert(histBinGrids(hgrm, 1, "upper"), [-inf, 0.1:0.1:1.0, inf]' * ones(1, 12), 1e-3)

Function File: [ binq, … ] = histBins ( hgrm, k, type, … )

Function File: [ fbinq, … ] = histBins ( hgrm, k, finite, type, … )

Return quantities relating to the histogram bin boundaries.

Arguments

hgrm

histogram object

k

dimension along which to return bin quantities

type

one of:

bins: bin boundaries
lower: lower bin boundary
upper: upper bin boundary
centre: bin centre
width: bin width

binq

bin quantities

fbinq

finite bin quantities

Examples

hgrm = restrictHist(addDataToHist(Hist(1, {"lin", "dbin", 0.1}), octforge_unifrnd(0, 1, 1e6, 1)));
sert(histBins(hgrm, 1, "lower"),  [-inf, 0:0.1:0.9, inf]', 1e-3)
sert(histBins(hgrm, 1, "centre"), [-inf, 0.05:0.1:0.95, inf]', 1e-3)
sert(histBins(hgrm, 1, "upper"), [-inf, 0.1:0.1:1.0, inf]', 1e-3)
sert(histBins(hgrm, 1, "finite", "lower"),  [0:0.1:0.9]', 1e-3)
sert(histBins(hgrm, 1, "finite", "centre"), [0.05:0.1:0.95]', 1e-3)
sert(histBins(hgrm, 1, "finite", "upper"), [0.1:0.1:1.0]', 1e-3)

Function File: ubins = histBinUnions ( hgrms… )

Return the unions of bins of the given histograms in each dimension.

Arguments

ubins: cell array of union of bins in each dimension
hgrms: histograms

Examples

hgrm1 = restrictHist(addDataToHist(Hist(1, {"lin", "dbin", 0.1}), octforge_unifrnd(0, 1, 1e6, 1)));
hgrm2 = restrictHist(addDataToHist(Hist(1, {"lin", "dbin", 0.1}), octforge_unifrnd(1, 2, 1e6, 1)));
hgrm3 = restrictHist(addDataToHist(Hist(1, {"lin", "dbin", 0.1}), octforge_unifrnd(2, 3, 1e6, 1)));
sert(histBinUnions(hgrm1, hgrm2), {[0:0.1:2]}, 1e-3)
sert(histBinUnions(hgrm1, hgrm3), {[0:0.1:1, 2:0.1:3]}, 1e-3)
sert(histBinUnions(hgrm2, hgrm3), {[1:0.1:3]}, 1e-3)

Function File: dim = histDim ( hgrm )

Returns the dimensionality of a histogram object.

Arguments

hgrm: histogram object
dim: dimensionality of the histogram

Examples

assert(histDim(Hist(1, {"lin", "dbin", 0.1})), 1)

assert(histDim(Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1})), 2)

assert(histDim(Hist(3, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1})), 3)

assert(histDim(Hist(4, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1})), 4)

assert(histDim(Hist(5, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1})), 5)

Function File: [ d, KLD, JSD ] = histDistance ( hgrm1, hgrm2 )

Computes different distance measures between histograms

Arguments

hgrm1
hgrm2: histogram objects
d: defined to be the sum of the absolute difference in probability density in each bin (for a common bin set), multiplied by the bin area.
KLD: is the (non-symmetric) KullbackâLeibler divergence D_KL(hgrm1 || hgrm2) >= 0 https://en.wikipedia.org/wiki/Kullback-Leibler_divergence
JSD: is the (symmetric) JensenâShannon divergence 0 <= JDS <= 1 https://en.wikipedia.org/wiki/Jensen-Shannon_divergence

Examples

hgrm1 = createGaussianHist(1.2, 3.4, "binsize", 0.1);
hgrm2 = createGaussianHist(7.3, 3.4, "binsize", 0.1);
sert(histDistance(hgrm1, hgrm1), 0.00, 1e-3)
sert(histDistance(hgrm1, hgrm2), 1.26, 1e-3)

Function File: prob = histProbs ( hgrm )

Function File: fprob = histProbs ( hgrm, finite )

Return the probabily densities of each histogram bin

Arguments

hgrm: histogram object
prob: probability densities of all bins
fprob: probability densities of finite bins

Examples

hgrm1 = Hist(1, {"lin", "dbin", 0.01});
hgrm1 = addDataToHist(hgrm1, octforge_normrnd(0, 1, 1e6, 1));
hgrm2 = Hist(1, {"log", "minrange", 0.5, "binsper10", 50});
hgrm2 = addDataToHist(hgrm2, octforge_normrnd(0, 1, 1e6, 1));

p2 = histProbs(hgrm2); c2 = histBinGrids(hgrm2, 1, "centre");
assert(mean(abs(p2 - octforge_normpdf(c2, 0, 1))) < 0.005);

hgrm3 = Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1});
hgrm3 = addDataToHist(hgrm3, rand(1e6, 2));

Function File: [ rng, nbins ] = histRange ( hgrm, [ kk = 1:dim ] )

Function File: [ frng, fnbins ] = histRange ( hgrm, [ kk = 1:dim ] , finite )

Returns the ranges of a histogram object, which are finite if the histogram is non-empty and NaNs otherwise, and the number of bins in each range.

Arguments

hgrm: histogram object
kk: dimensions for which to return ranges; defaults to all
rng: ranges of the histogram
nbins: number of bins in each range
frng: finite ranges of the histogram
fnbins: number of finite bins in each range

Examples

hgrm0 = Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1});
rand("seed", 1);  # avoid random surprises exceeding tolerance
sert(histRange(addDataToHist(hgrm0, octforge_unifrnd(1.2, 9.7, 1000, 2))), [1.2, 9.7; 1.2, 9.7], 0.25)
sert(histRange(addDataToHist(hgrm0, [octforge_unifrnd(2.3, 11.3, 1000, 1), octforge_unifrnd(67.9, 103.5, 1000, 1)]), 1), [2.3, 11.3], 0.25)
sert(histRange(addDataToHist(hgrm0, [octforge_unifrnd(2.3, 11.3, 1000, 1), octforge_unifrnd(67.9, 103.5, 1000, 1)]), 2), [67.9, 103.5], 0.25)

Function File: total = histTotalCount ( hgrm )

Returns the total number of counts in a histogram object.

Arguments

hgrm: histogram object
total: total number of counts

Examples

hgrm = Hist(2, {"lin", "dbin", 0.01}, {"lin", "dbin", 0.1});
hgrm = addDataToHist(hgrm, [octforge_normrnd(1.7, 4.3, 13579, 1), rand(13579, 1)]);
assert(histTotalCount(hgrm), 13579);

Function File: hgrm = initHistFromFunc ( hgrm, F, [ xl_1, xh_1 ] , ..., [ xl_dim, xh_dim ] )

Initialise a histogram directly from a given function.

Arguments

hgrm: histogram object
F: function used to initialise histogram
xl_k
xh_k: range in dimension ’k’ to evaluate F over

Examples

hgrm = Hist(1, {"lin", "dbin", 0.1});
hgrm = initHistFromFunc(hgrm, @(x) octforge_normpdf(x, 1.3, 2.7), [-20, 20]);
assert(abs(meanOfHist(hgrm) - 1.3) < 1e-3);
assert(abs(stdvOfHist(hgrm) - 2.7) < 1e-3);

hgrm = Hist(2, {"lin", "dbin", 0.1}, {"lin", "dbin", 0.1});
hgrm = initHistFromFunc(hgrm, @(x, y) octforge_normpdf(x, y, 1.0), [-20, 20], [0, 10]);
assert(abs(meanOfHist(hgrm, 1) - linspace(0.05, 9.95, 100)) < 1e-4);

Function File: hgrm = resampleHist ( hgrm, k, newbins_k )

Function File: hgrm = resampleHist ( hgrm, newbins_1, …, newbins_dim )

Resamples a histogram to a new set of bins

Arguments

hgrm: histogram object
k: dimension along which to resample
newbins_k: new bins in dimension k (dim = number of dimensions)

Examples

hgrm = Hist(2, {"lin", "dbin", 0.01}, {"lin", "dbin", 0.1});
hgrm = addDataToHist(hgrm, [octforge_normrnd(1.7, 4.3, 1e6, 1), rand(1e6, 1)]);
assert(meanOfHist(hgrm, 1), meanOfHist(resampleHist(hgrm, 1, -30:0.2:30), 1), 1e-3);

Function File: hgrm = rescaleHistBins ( hgrm, s )

Rescale the bins of a histogram.

Arguments

hgrm: histogram object
s: strictly positive scale to apply to bin in each dimension

Examples

hgrm = createGaussianHist(1.2, 3.4, "binsize", 0.1);
sert(meanOfHist(rescaleHistBins(hgrm, 64.2)), 1.2 * 64.2, 1e-3)

Function File: rhgrm = restrictHist ( hgrm, k, [ xl_k, xh_k ] )

Function File: rhgrm = restrictHist ( hgrm, [ xl_1, xh_1 ] , …, [ xl_dim, xh_dim ] )

Function File: rhgrm = restrictHist ( hgrm )

Function File: rhgrm = restrictHist ( …, discard )

Extract histogram restricted to subrange of bins, as determined by the ranges [xl_k, xh_k]. Samples outside of these ranges are moved to the histogram boundary bins [-\inf,xl_k] and [xh_k,\inf], unless the string "discard" is given as the last argument. If no ranges are given, histRange() is used to find the minimum ranges.

Arguments

rhgrm: restricted histogram object
hgrm: original histogram object
k: dimension along which to restrict histogram range
xl_k
xh_k: range in dimension k to restrict range to

Examples

hgrm = Hist(2, {"lin", 0.01}, {"lin", 0.01});
hgrm = addDataToHist(hgrm, rand(50000,2));
hgrmx = restrictHist(hgrm, 1, [0, 0.5]);
hgrmy = restrictHist(hgrm, 2, [0, 0.3]);
assert(abs(meanOfHist(contractHist(hgrm, 1)) - 0.5) < 1e-2);
assert(abs(meanOfHist(contractHist(hgrm, 2)) - 0.5) < 1e-2);
assert(abs(meanOfHist(contractHist(hgrmx, 1)) - 0.25) < 1e-2);
assert(abs(meanOfHist(contractHist(hgrmx, 2)) - 0.5) < 1e-2);
assert(abs(meanOfHist(contractHist(hgrmy, 1)) - 0.5) < 1e-2);
assert(abs(meanOfHist(contractHist(hgrmy, 2)) - 0.15) < 1e-2);

hgrm = Hist(2, -1.0:0.1:2.0, -1.0:0.1:2.0);
hgrm = addDataToHist(hgrm, rand(50000,2));
count = histTotalCount(hgrm);
hgrmx = restrictHist(hgrm, 1, [0.0, 1.0]);
hgrmy = restrictHist(hgrm, 2, [-0.5, 1.5]);
hgrmxy = restrictHist(hgrm, [0, 0.5], [0, 0.5]);
assert(histTotalCount(hgrmx) == count);
assert(histTotalCount(hgrmy) == count);
assert(histTotalCount(hgrmxy) == count);

Function File: thgrm = thresholdHist ( hgrm, pth )

Set a threshold on the histogram probability of each bin; bins with probability below the threshold have their count set to zero.

Arguments

thgrm: thresholded histogram object
hgrm: original histogram object
pth: probability threshold

Examples

hgrm = createGaussianHist(1.2, 3.4, "binsize", 0.1);
assert(meanOfHist(thresholdHist(hgrm, 1e-10)), 1.2, 1e-3);
assert(meanOfHist(thresholdHist(hgrm, 0.1)), 1.2, 1e-3);

Function File: hgrm = transformHist ( hgrm, F, [ err ] )

Transform the contents of a histogram.

Arguments

hgrm

histogram object

F

function to apply to histogram samples:

should accept column vectors as inputs and return an array whose columns are vectorised outputs
number of input/output arguments must match histogram dimensionality

err

convergence requirement on histogram (default = 1e-2)

Examples

hgrmA = hgrmA1 = hgrmA2 = hgrmA3 = Hist(1, {"lin", "dbin", 0.1});
N = 1e6;
do
  x = randn(N, 1);
  oldhgrmA = hgrmA;
  hgrmA = addDataToHist(hgrmA, x);
  hgrmA1 = addDataToHist(hgrmA1, abs(x));
  hgrmA2 = addDataToHist(hgrmA2, x.^2 - 3);
  hgrmA3 = addDataToHist(hgrmA3, sin(x));
  histerr = histDistance(oldhgrmA, hgrmA);
until histerr < 1e-2

t_hgrmA = transformHist(hgrmA, @(x) x);
assert(histDistance(hgrmA, t_hgrmA) < 0.01);

t_hgrmA2 = transformHist(hgrmA, @(x) x.^2 - 3);
assert(histDistance(hgrmA2, t_hgrmA2) < 0.05);

hgrmB = hgrmB1 = hgrmB2 = hgrmB3 = Hist(2, {"lin", "dbin", 0.1}, {"log", "minrange", 1.0, "binsper10", 8});
N = 1e7;
do
  x = randn(N, 1);
  y = sign(x) .* 10.^(-1 + 3*rand(N, 1));
  oldhgrmB = hgrmB;
  hgrmB = addDataToHist(hgrmB, [x, y]);
  hgrmB1 = addDataToHist(hgrmB1, [abs(x), 10.*y]);
  hgrmB2 = addDataToHist(hgrmB2, [x.^2 - 3, y.^3]);
  hgrmB3 = addDataToHist(hgrmB3, [sin(x), cos(y)]);
  histerr = histDistance(oldhgrmB, hgrmB);
until histerr < 1e-2

t_hgrmB = transformHist(hgrmB, @(x,y) [x, y]);
assert(histDistance(hgrmB, t_hgrmB) < 0.05)

t_hgrmB2 = transformHist(hgrmB, @(x,y) [x.^2 - 3, y.^3]);
assert(histDistance(hgrmB2, t_hgrmB2) < 0.1);

2.15 histograms/@Hist

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

Arguments

Examples

2.15 `histograms/@Hist`