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 unified 1D Histogram representation preserving astropy.units.

Unlike TimeSeries/FrequencySeries, Histogram is not an instance of ndarray, but instead a composite holding values, edges, cov, and sumw2 attributes. All properties expose proper astropy Quantities to maintain physical consistency.

Notes

Statistical Error Tracking (Double Management Rule): Histogram maintains two attributes for error tracking: 1. sumw2: The sum of squared weights per bin. This tracks the uncorrelated

statistical variance (e.g., from counting statistics).

  1. cov: The full covariance matrix. Its diagonal elements SHOULD include the statistical variance tracked by sumw2.

When filling the histogram, both are updated to ensure consistency.

__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]
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, ...])

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.

This method calculates the occurrence counts for the given data within the existing bin edges and adds them to the current values.

Statistical Error Tracking (Double Management Rule): It updates both sumw2 and the diagonal of cov if they are present. The diagonal of cov is updated with the new statistical variance derived from weights (or counts if weights are None).

Parameters:

  • data (array-like or Quantity) – Data points to be added to the histogram.

  • weights (array-like or Quantity, optional) – Weights for each data point. If a Quantity, it is converted to the histogram’s unit (self.unit).

Returns:

A new Histogram object with updated values and uncertainties.

Return type:

Histogram

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.