gwexpy.histogram.Histogram

class gwexpy.histogram.Histogram(values: Any, edges: Any, unit: Any = None, xunit: Any = None, cov: Any = None, sumw2: Any = None, underflow: Any = None, overflow: Any = None, underflow_sumw2: Any = None, overflow_sumw2: Any = None, name: str | None = None, channel: Any | None = None)[source]

Bases: PlotMixin, FittingMixin, HistogramRebinMixin, HistogramCoreMixin

A 1D Histogram representation with physical units and uncertainty.

Histogram stores a 1-dimensional distribution of values across a set of bin edges. It maintains physical consistency using astropy.units and provides robust uncertainty tracking via covariance matrices and sum-of-weights-squared.

Parameters:

  • values (array-like or ~astropy.units.Quantity) – The counts or integrated values in each bin.

  • edges (array-like or ~astropy.units.Quantity) – The bin boundaries (length n_bins + 1).

  • unit (str, ~astropy.units.Unit, optional) – Unit for values.

  • xunit (str, ~astropy.units.Unit, optional) – Unit for edges.

  • cov (array-like or ~astropy.units.Quantity, optional) – Covariance matrix for the bin values.

  • sumw2 (array-like or ~astropy.units.Quantity, optional) – Sum of squared weights per bin for statistical error tracking.

  • **kwargs – Additional attributes like name, channel, underflow, etc.

Notes

The uncertainty is tracked in two ways:

  1. sumw2: Statistical (uncorrelated) variance per bin.

  2. cov: Full covariance matrix. The diagonal of cov must stay consistent with sumw2.

Examples

>>> from gwexpy.histogram import Histogram
>>> h = Histogram([1, 2], [0, 1, 2])
>>> h
<Histogram (nbins=2, unit=)>
__init__(values: Any, edges: Any, unit: Any = None, xunit: Any = None, cov: Any = None, sumw2: Any = None, underflow: Any = None, overflow: Any = None, underflow_sumw2: Any = None, overflow_sumw2: Any = None, name: str | None = None, channel: Any | None = None)[source]

Initialize a histogram from values and bin edges.

Parameters:

  • values (array-like or Quantity) – Total events or integrated quantity in each bin (Length: n_bins).

  • edges (array-like or Quantity) – Bin boundaries (Length: n_bins + 1). Must be strictly monotonically increasing.

  • unit (str or astropy.units.Unit, optional) – Unit for values if it’s not a Quantity.

  • xunit (str or astropy.units.Unit, optional) – Unit for edges if it’s not a Quantity.

  • cov (array-like or Quantity, optional) – Covariance matrix (n_bins, n_bins) denoting uncertainties and correlations.

  • sumw2 (array-like or Quantity, optional) – Sum of squares of weights for each bin (n_bins) for uncorrelated errors.

  • underflow (float or Quantity, optional) – Total value below the first bin edge.

  • overflow (float or Quantity, optional) – Total value above the last bin edge.

  • underflow_sumw2 (float or Quantity, optional) – Sum of squared weights for the underflow region.

  • overflow_sumw2 (float or Quantity, optional) – Sum of squared weights for the overflow region.

  • name (str, optional) – Name of this histogram.

  • channel (any, optional) – Linked data channel.

Methods

__init__(values, edges[, unit, xunit, cov, ...])

Initialize a histogram from values and bin edges.

copy([deep])

Return a copy of the histogram.

crop([start, end])

Crop the histogram to a specific range [start, end].

fill(data[, weights])

Fill the histogram with new data points.

fit(model[, x_range, sigma, p0, limits, fixed])

Fit the data to a model using iminuit.

from_density(density, edges[, unit, xunit])

Create a Histogram from density values.

from_root(obj)

Create a Histogram from a ROOT TH1 object.

integral([start, end, xunit, return_error])

Integrate the histogram over the interval [start, end].

max()

Return the upper edge of the last bin with non-zero content.

mean()

Compute the weighted mean of the histogram.

median()

Compute the median of the histogram.

min()

Return the lower edge of the first bin with non-zero content.

plot(**kwargs)

Plot this object using gwexpy.plot.Plot.

quantile(q)

Compute the q-th quantile of the distribution.

read(source, *args, **kwargs)

Read data into a Histogram.

rebin(new_edges[, xunit])

Rebin the histogram into new bins using a fraction intersection matrix.

std([ddof])

Compute the weighted standard deviation of the histogram.

to_density([as_histogram])

Return the physical density (values / bin_widths).

to_th1d()

Convert this Histogram to a ROOT TH1D.

var([ddof])

Compute the weighted variance of the histogram.

write(target, *args, **kwargs)

Write Histogram to file.

Attributes

bin_centers

The center of each bin.

bin_widths

The width of each bin.

cov

Covariance matrix of the bins (n_bins, n_bins).

edges

n_bins + 1).

errors

1-sigma statistical errors (derived from cov or sumw2).

nbins

Number of bins.

overflow

The overflow value (sum of weights for data above the last edge).

overflow_sumw2

Sum of squares of weights for the overflow region.

sumw2

Sum of squares of weights for each bin (n_bins).

underflow

The underflow value (sum of weights for data below the first edge).

underflow_sumw2

Sum of squares of weights for the underflow region.

unit

The physical unit of the bin values.

value

Alias for values (bin total).

values

The total values in each bin (bin total).

xindex

The coordinates of the bins (centers).

xunit

The physical unit of the bin edges.
fill(data: Any, weights: Any = None) → Histogram[source]

Fill the histogram with new data points.

Calculates occurrence counts for the given data within current edges and increments existing values.

Parameters:

  • data (array-like or ~astropy.units.Quantity) – Data points to add.

  • weights (array-like or ~astropy.units.Quantity, optional) – Weights for each data point.

Returns:

A new Histogram object with updated values and uncertainties.

Return type:

Histogram

Notes

Updates both sumw2 and the diagonal of cov to maintain statistical consistency.

Examples

>>> h = Histogram([1, 2], [0, 1, 2])
>>> h = h.fill([0.5, 1.5, 1.5])
>>> h.values
<Quantity [2., 4.]>
classmethod read(source: Any, *args: Any, **kwargs: Any) → Histogram[source]

Read data into a Histogram.

classmethod from_root(obj: Any) → Histogram[source]

Create a Histogram from a ROOT TH1 object.

to_th1d() → Any[source]

Convert this Histogram to a ROOT TH1D.

write(target: Any, *args: Any, **kwargs: Any) → Any[source]

Write Histogram to file.