class histogrammar.primitives.stack.Stack(bins, quantity, value=<Count 0.0>, nanflow=<Count 0.0>)[source]

Bases: histogrammar.defs.Factory, histogrammar.defs.Container

Accumulates a suite of aggregators, each filtered with a tighter selection on the same quantity.

This is a generalization of Fraction, which fills two aggregators, one with a cut, the other without. Stack fills N + 1 aggregators with N successively tighter cut thresholds. The first is always filled (like the denominator of Fraction), the second is filled if the computed quantity exceeds its threshold, the next is filled if the computed quantity exceeds a higher threshold, and so on.

The thresholds are presented in increasing order and the computed value must be greater than or equal to a threshold to fill the corresponding bin, and therefore the number of entries in each filled bin is greatest in the first and least in the last.

Although this aggregation could be visualized as a stack of histograms, stacked histograms usually represent a different thing: data from different sources, rather than different cuts on the same source. For example, it is common to stack Monte Carlo samples from different backgrounds to show that they add up to the observed data. The Stack aggregator does not make plots of this type because aggregation trees in Histogrammar draw data from exactly one source.

To make plots from different sources in Histogrammar, one must perform separate aggregation runs. It may then be convenient to stack the results of those runs as though they were created with a Stack aggregation, so that plotting code can treat both cases uniformly. For this reason, Stack has an alternate constructor to build a Stack manually from distinct aggregators, even if those aggregators came from different aggregation runs.


Add two containers of the same type. The originals are unaffected.

__init__(bins, quantity, value=<Count 0.0>, nanflow=<Count 0.0>)

Create a Stack that is capable of being filled and added.

  • thresholds (list of floats) – specifies N cut thresholds, so the Stack will fill N + 1 aggregators, each overlapping the last.
  • quantity (function returning float) – computes the quantity of interest from the data.
  • value (Container) – generates sub-aggregators for each bin.
  • nanflow (Container) – a sub-aggregator to use for data whose quantity is NaN.
Other Parameters:
  • entries (float) – the number of entries, initially 0.0.
  • bins (list of float, Container pairs) – the N + 1 thresholds and sub-aggregators. (The first threshold is minus infinity; the rest are the ones specified by thresholds).
static build(*ys)

Create a Stack out of pre-existing containers, which might have been aggregated on different streams.

Parameters:aggregators (list of Container) – this function will attempt to add them, so they must also have the same binning/bounds/etc.

List of sub-aggregators, to make it possible to walk the tree.


Copy this container, making a clone with no reference to the original.

static ed(entries, bins, nanflow)

Create a Stack that is only capable of being added.

  • entries (float) – the number of entries.
  • bins (list of float, Container pairs) – the N + 1 thresholds and sub-aggregator pairs.
  • nanflow (Container) – the filled nanflow bin.

Reference to the container’s factory for runtime reflection.

fill(datum, weight=1.0)

Increment the aggregator by providing one datum to the fill rule with a given weight.

Usually all containers in a collection of histograms take the same input data by passing it recursively through the tree. Quantities to plot are specified by the individual container’s lambda functions.

The container is changed in-place.


User’s entry point for reconstructing a container from JSON text.

static fromJsonFragment(json, nameFromParent)

staticmethod(function) -> method

Convert a function to be a static method.

A static method does not receive an implicit first argument. To declare a static method, use this idiom:

class C: def f(arg1, arg2, ...): ... f = staticmethod(f)

It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class.

Static methods in Python are similar to those found in Java or C++. For a more advanced concept, see the classmethod builtin.

static ing(bins, quantity, value=<Count 0.0>, nanflow=<Count 0.0>)

Synonym for __init__.


Name of the concrete Factory as a string; used to label the container type in JSON.

plot(httpServer=None, **parameters)

Generate a VEGA visualization and serve it via HTTP.


Add a new Factory to the registry, introducing a new container type on the fly. General users usually wouldn’t do this, but they could. This method is used internally to define the standard container types.


Explicitly invoke histogrammar.specialized.addImplicitMethods on this object, usually right after construction (in each of the methods that construct: __init__, ed, ing, fromJsonFragment, etc).

Objects used as default parameter arguments are created too early for this to be possible, since they are created before the histogrammar.specialized module can be defined. These objects wouldn’t satisfy any of addImplicitMethod‘s checks anyway.


Cut thresholds (first items of bins).


Return a copy of this container as though it was created by the ed function or from JSON (the “immutable form” in languages that support it, not Python).


Convert this container to dicts and lists representing JSON (dropping its fill method).

Note that the dicts and lists can be turned into a string with json.dumps.


Used internally to convert the container to JSON without its "type" header.


Sub-aggregators (second items of bins).


Create an empty container with the same parameters as this one. The original is unaffected.