ヒストグラム (gwexpy.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)

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).

2. 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.

fill(data: Any, weights: Any = None) → Histogram

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 from_root(obj: Any) → Histogram

Create a Histogram from a ROOT TH1 object.

classmethod read(source: Any, *args: Any, **kwargs: Any) → Histogram

Read data into a Histogram.

to_th1d() → Any

Convert this Histogram to a ROOT TH1D.

write(target: Any, *args: Any, **kwargs: Any) → Any

Write Histogram to file.

class gwexpy.histogram.HistogramDict(*args: Any, **kwargs: Any)

Bases: DictMapMixin, HistogramBaseDict[Histogram]

Ordered mapping of Histogram objects keyed by label.

EntryClass

alias of Histogram

fill(*args, **kwargs)

Fill each Histogram in the dict with new data.

integral(*args, **kwargs)

Compute integral of each Histogram in the dict. Returns a dict of Quantities.

max(*args, **kwargs)

Compute upper edge of last non-zero bin for each Histogram. Returns a dict of Quantities.

mean(*args, **kwargs)

Compute weighted mean of each Histogram. Returns a dict of Quantities.

median(*args, **kwargs)

Compute median of each Histogram. Returns a dict of Quantities.

min(*args, **kwargs)

Compute lower edge of first non-zero bin for each Histogram. Returns a dict of Quantities.

quantile(*args, **kwargs)

Compute quantile of each Histogram. Returns a dict of Quantities.

rebin(*args, **kwargs)

Rebin each Histogram in the dict. Returns a HistogramDict.

std(*args, **kwargs)

Compute weighted standard deviation of each Histogram. Returns a dict of Quantities.

to_density(*args, **kwargs)

Convert each Histogram to density representation. Returns a dict of Quantities.

var(*args, **kwargs)

Compute weighted variance of each Histogram. Returns a dict of Quantities.

class gwexpy.histogram.HistogramList(*items: _H | Iterable[_H])

Bases: ListMapMixin, HistogramBaseList[Histogram]

List of Histogram objects.

EntryClass

alias of Histogram

fill(*args, **kwargs)

Fill each Histogram in the list with new data.

max(*args, **kwargs)

Compute upper edge of last non-zero bin for each Histogram. Returns a list of Quantities.

mean(*args, **kwargs)

Compute weighted mean of each Histogram. Returns a list of Quantities.

median(*args, **kwargs)

Compute median of each Histogram. Returns a list of Quantities.

min(*args, **kwargs)

Compute lower edge of first non-zero bin for each Histogram. Returns a list of Quantities.

quantile(*args, **kwargs)

Compute quantile of each Histogram. Returns a list of Quantities.

rebin(*args, **kwargs)

Rebin each Histogram in the list. Returns a HistogramList.

std(*args, **kwargs)

Compute weighted standard deviation of each Histogram. Returns a list of Quantities.

to_density(*args, **kwargs)

Convert each Histogram to density representation. Returns a list of Quantities.

var(*args, **kwargs)

Compute weighted variance of each Histogram. Returns a list of Quantities.

クラス

Histogram	A unified 1D Histogram representation preserving astropy.units.
HistogramDict	Ordered mapping of Histogram objects keyed by label.
HistogramList	List of Histogram objects.