Reference for histogram functions
bin_average
Synopsis
computes averages in histogram bins
Usage
Struct_Type bin_average(phi, rate, phi_lo[, phi_hi])
Qualifiers
- err: error on rate
- quantiles: array of quantiles to calculate for the distribution
- quartiles: calculate the .25, .5 and .75 quantiles
Description
The fields of the returned structure are:
-
bin_lo
andbin_hi
, defining the bins -
value
: the average -
err
: the standard error of the mean -
n
: the number of points in each bin
and, if the err
qualifier specifies an error array:
-
weighted_average
: an error-weighted average
histogram2d_min_max
Synopsis
computes a 2d histogram between minimum and maximum data values
Usage
h2 = histogram2d_min_max(Double_Type Y, X);
Qualifiers
- xmin [
=min(X)
]: first value ofXlo
-grid - xmax [
=max(X)
]: last value ofXhi
-grid - ymin [
=min(Y)
]: first value ofYlo
-grid - ymax [
=max(Y)
]: last value ofYhi
-grid - Nx [=50]: number of bins of (linear)
Xlo
-grid - Ny [=50]: number of bins of (linear)
Ylo
-grid - Xlo: reference to a variable to store the
Xlo
array - Ylo: reference to a variable to store the
Ylo
array
Description
For 2d arrays, the order of the indices matters.
Almost all ISIS and related functions use h2[iy, ix]
with the first index corresponding to y, and the second to x.
For this reason, histogram2d_min_max
-- just as
histogram2d
(though not explicitly documented) --
needs to get the array Y
of y-coordinates as first argument
and the array X
of x-coordinates only as second argument,
if the resulting 2d array h2
shall be used with functions
like plot_image
, png_write
, ds9_view
, etc..
The x-grid Xlo
starts at xmin
, but ends before xmax,
such that Xhi = make_hi_grid(Xlo)
would end at xmax
.
The same is true for the y-grid Ylo
with ymin
and ymax
.
Unlike histogram2d(Y, X, Ylo, Xlo)
, h2
will not contain
overflow bins in the last column and the last row, i.e.,
h2[iy,ix]
corresponds to the number of pairs (X
, Y
)
where Xlo[ix] <= X < Xhi[ix]
and Ylo[iy] <= Y < Xhi[iy]
.
Example
variable n=10000; x=2*grand(n), y=grand(n), Xlo, Ylo; variable h2 = histogram2d_min_max(y, x; Xlo=&Xlo, Ylo=&Ylo); plot_image(h2, 0, Xlo+(Xlo[1]-Xlo[0])/2., Ylo+(Ylo[1]-Ylo[0])/2.);
See also: histogram2d
histogram3d
Synopsis
bins scatter data into a 3d histogram
Usage
Integer_Type[,,] histogram3d(Double_Type x[], y[], z[], Xgrid[], Ygrid[], Zgrid[])
Description
histogram3d
computes the number N[i,j,k]
of points (x[m], y[m], z[m])
that fall into the 3d-cell with Xgrid[i] <= x < Xgrid[i+1]
,
Ygrid[j] <= y < Ygrid[j+1]
and Zgrid[k] <= z < Xgrid[k+1]
.
The last bin in each dimension is an overflow bin,
such that its upper limit is at infinity.
See also: histogram, histogram2d
histogram_gaussian_probability
Usage
Double_Type[] histogram_gaussian_probability(Double_Type[] x, sigma, lo[, hi])
Description
While histogram(x, lo[, hi])
increases the histogram bin j
where lo[j] <= x[i] < hi[j]
by one for every x[i]
,
histogram_gaussian_probability(x, lo[, hi])
adds the
the Gaussian proability of events with mean x[i]
and standard deviation sigma[i]
to all bins.
Note that this function acts like a convolution and therefore introduces an additional broadening.
Example
variable n=10000, x=grand(n), sigma=ones(n); variable lo=[-3:3:0.05], hi=make_hi_grid(lo); hplot(lo, hi, histogram(x, lo, hi)); ohplot(lo, hi, histogram_gaussian_probability(x, sigma, lo, hi)); % The first distribution follows N(0, 1), % but the second one follows N(0, sqrt(1^2 + sigma^2)) = N(0, sqrt(2)).
See also: histogram
histogram_min_max
Synopsis
computes a histogram between minimum and maximum value
Usage
Struct_Type h = histogram_min_max(Double_Type X[, Double_Type dx]);
Qualifiers
- log: use a logarithmic grid with the following number of bins:
- N [=100]: number of bins of logarithmic or linear grid
Description
The return value is a { bin_lo, bin_hi, value, err }
structure which
can directly be used with, e.g., hplot_with_err
, define_counts
, etc.
See also: histogram
log_grid
Synopsis
generate a logarithmic histogram grid
Usage
(bin_lo[], bin_hi[]) = log_grid(min, max, nbins);
Description
This function is an shorthand form of:
(log_bin_lo, log_bin_lo) = linear_grid( log(min), log(max), nbins );
bin_lo = exp( log_bin_lo );
bin_hi = exp( log_bin_hi );
See also: linear_grid
probmap
Synopsis
histogram-like function for 2d-data including uncertainties
Usage
Struct_Type probmap([Double_Type x0, x1, y0, y1]);
Qualifiers
xbins - number of bins in x-direction (preferred over 'bins') ybins - number of bins in y-direction (preferred over 'bins') bins - number of bins in both directions (default: 201)
Description
Using this object, a histogram of multiple xy-datasets including uncertainties for both, x- and y-direction, can be created. The uncertainties are handled as 2d- gaussians with sigma_x and sigma_y equal to the given errors.
Calling this function creates a structure with the following functions among other fields: add - adds xy-data to the map and returns the dataset number of the added data Usage: probmap.add(Double_Type[] x, y[, dy]); or probmap.add(Double_Type[] x, y[, dx, dy]); delete - deletes data identified by its dataset number Usage: probmap.delete(Integer_Type number); xrange - sets the x-range Usage: probmap.xrange(Double_Type xMin, xMax); yrange - sets the y-range Usage: probmap.yrange(Double_Type yMin, yMax); npoints - count the number of xy-data added in each point of the map. If set the density map is available at .data.npoints, and it is passed as qualifier 'npoints' to the norm_fun (see next qualifier). norm_fun - reference to a function used for normalization. The parameters are an array of all datasets, given as a structure (x,y,dx,dy), and the histogram map resulting by adding all data. The function has to return either a single normalization factor or a map of factors. Default factor: 1./max(histogram) getmap - calculates the histogram map from the added data and returns it as 2d-array Usage: probmap.getmap(); getpoint - returns the value of the histogram map at a specific point Usage: probmap.getpoint(x,y); calcpath - calculates the path with the highest averaged probability between to points using the A*-algorithm returning a structure with the best path (x,y)
Example
% creata a new map and set x- and y-range variable pm = probmap(0.1, 100, 0, 20); % add two xy-datasets including uncertainties pm.add(x1, y1, dx1, dy1); pm.add(x2, y2, dx2, dy2); % plot the resulting histogram plot_image(pm.getmap());
See also: histogram2d, histogram_gaussian_probability, aStar
rebin_mean
Synopsis
rebins units like intensity, where you expect the binning to take the mean of the value, properly
Usage
intens_new = rebin_mean(r_nlo,r_nhi,r_lo,r_hi,intens);