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

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

Bases: DictMapMixin, HistogramBaseDict[Histogram]

A dictionary of Histogram objects, indexed by label.

HistogramDict provides a convenient container for multiple histograms, allowing batch operations like fill, rebin, and statistical summaries.

Parameters:

  • *args – Passed to OrderedDict and update.

  • **kwargs – Passed to OrderedDict and update.

Notes

Key mapping methods:

fill(*args, **kwargs)

Fill each Histogram in the dict with new data.

rebin(*args, **kwargs)

Rebin each Histogram in the dict.

mean(*args, **kwargs)

Compute weighted mean of each Histogram.

std(*args, **kwargs)

Compute weighted standard deviation of each Histogram.

Examples

>>> from gwexpy.histogram import Histogram, HistogramDict
>>> h = Histogram([1, 2], [0, 1, 2])
>>> hd = HistogramDict()
>>> hd['H1'] = h
>>> hd
HistogramDict([('H1', <Histogram (nbins=2, unit=)>)])
EntryClass

alias of Histogram

rebin(*args, **kwargs)

Rebin each Histogram in the dict. Returns a HistogramDict.

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.

to_density(*args, **kwargs)

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

mean(*args, **kwargs)

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

var(*args, **kwargs)

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

std(*args, **kwargs)

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

median(*args, **kwargs)

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

quantile(*args, **kwargs)

Compute quantile 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.

max(*args, **kwargs)

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

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

Bases: ListMapMixin, HistogramBaseList[Histogram]

A list of Histogram objects.

HistogramList provides a container for an ordered sequence of histograms, supporting batch processing.

Parameters:

*items (Histogram or iterable of Histograms) – Initial items to populate the list.

Notes

Key mapping methods:

fill(*args, **kwargs)

Fill each Histogram in the list with new data.

rebin(*args, **kwargs)

Rebin each Histogram in the list.

mean(*args, **kwargs)

Compute weighted mean of each Histogram.

Examples

>>> from gwexpy.histogram import Histogram, HistogramList
>>> h = Histogram([1, 2], [0, 1, 2])
>>> hl = HistogramList([h])
>>> hl
[<Histogram (nbins=2, unit=)>]
EntryClass

alias of Histogram

rebin(*args, **kwargs)

Rebin each Histogram in the list. Returns a HistogramList.

fill(*args, **kwargs)

Fill each Histogram in the list with new data.

to_density(*args, **kwargs)

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

mean(*args, **kwargs)

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

var(*args, **kwargs)

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

std(*args, **kwargs)

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

median(*args, **kwargs)

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

quantile(*args, **kwargs)

Compute quantile 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.

max(*args, **kwargs)

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

クラス

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

A 1D Histogram representation with physical units and uncertainty.

HistogramDict(*args, **kwargs)

A dictionary of Histogram objects, indexed by label.

HistogramList(*items)

A list of Histogram objects.