Histogram

class ctapipe.utils.Histogram(nbins, ranges, name='Histogram', axis_names=None)

Bases: object

An N-D histogram class with FITS image I/O.

The output FITS file will contain an ImageHDU datacube and associated WCS headers to describe the axes of the histogram. Thus, the output files should work correctly in any program capable of working with FITS datacubes (like SAOImage DS9).

Internally, it uses numpy.histogramdd to generate the histograms.

All axes are assumed to be linear, with equally spaced bins (otherwise they could not be stored in a FITS image HDU)

Attributes:

data: np.ndarray

the histogram counts.

nbins: array_like(int)

list of number of bins for each dimension

ranges: list(tuple)

list of (min,max) values for each dimension

name: str

name of histogram (will be used as FITS extension name when written to a file

axis_names: list(str)

name of each axis

Examples

>>> hist = Histogram(nbins=(10,10), ranges=[[-1,1], [-1,1]])
>>> data = np.random.normal(size=(100, 2)) # make 100 random 2D events
>>> hist.fill(data)

Get a point in the histogram (can also get multiple values at once by passing an array)

>>> val = hist.get_value([0.1,-0.5])
>>> vals = hist.get_value([[0.1,-0.5], [0.9,0.9]])

Get the full data array and do things with it:

>>> meanx = hist.data.mean(axis=0)

Write it to a FITS image file:

>>> hist.to_fits().writeto("output.fits")

Read it from FITS image file:

>>> hist2 = Histogram.from_fits("output.fits")

Attributes Summary

bin_lower_edges	lower edges of bins.
bins
hist	for backward compatibility.
ndims
outliers	returns the number of outlier points (the number of input datapoints - the sum of the histogram).
ranges

Methods Summary

bin_centers(index)	returns array of bin centers for the given index
draw_1d([dim])
draw_2d([dims])	draw the histogram using pcolormesh() (only works for 2D histograms currently)
fill(datapoints, **kwargs)	generate a histogram from data points.
from_fits(input_fits)	Construct a Histogram from a previously written FITS histogram file or HDU (see Histogram.to_fits())
get_value(coords[, outlier_value])	Returns the values of the histogram at the given world coordinate(s)
resample_inplace(nbins)	Change the shape of the histogram using an n-dimensional interpolation function (via ndimage.map_coordinates).
to_fits()	Convert the Histogram into an astropy.io.fits.ImageHDU, suitable for writing to a file.

Attributes Documentation

bin_lower_edges

lower edges of bins. The length of the array will be nbins+1, since the final edge of the last bin is included for ease of use in vector operations

bins

hist

for backward compatibility. Use Histogram.data for read/write access

ndims

outliers

returns the number of outlier points (the number of input datapoints - the sum of the histogram). This assumes the data of the histogram is unmodified (and represents “counts”).

ranges

Methods Documentation

bin_centers(index)

returns array of bin centers for the given index

draw_1d(dim=0, **kwargs)

draw_2d(dims=(0, 1), **kwargs)

draw the histogram using pcolormesh() (only works for 2D histograms currently)

Parameters:

dims: (int,int)

indices of which dimensions to draw

kwargs:

arguments to pass to matplotlib pcolormesh command

fill(datapoints, **kwargs)

generate a histogram from data points. Since the results of fill() are added to the current histogram, you can call fill() multiple times to fill a single Histogram.

Parameters:

datapoints: array_like

array of N-d points (see numpy.histogramdd documentation)

kwargs:

any extra options to pass to numpy.histogramdd when creating the histogram

classmethod from_fits(input_fits)

Construct a Histogram from a previously written FITS histogram file or HDU (see Histogram.to_fits())

Parameters:

input_fits: string or astropy.io.fits.ImageHDU

File or HDU to read into histogram (Should be a FITS HDU originally created by Histogram.to_fits(), may not work for general FITS images)

get_value(coords, outlier_value=None)

Returns the values of the histogram at the given world coordinate(s)

Parameters:

coords: array_like

array of M coordinates of dimension N (where the N is the histogram dimension)

outlier_value: float or None

value for outliers, if None, coordinates outside the edges of the histogram will be given the edge value

resample_inplace(nbins)

Change the shape of the histogram using an n-dimensional interpolation function (via ndimage.map_coordinates).

Parameters:

nbins: tuple of int

a tuple of the new number of bins to resample_inplace this histogram over (e.g. if the original histogram was (100,100), setting bins to (200,200) would provide double the resolution, with the interviening bins interpolated.

to_fits()

Convert the Histogram into an astropy.io.fits.ImageHDU, suitable for writing to a file.