class histogrammar.primitives.collection.Branch(*values)[source]

Bases: histogrammar.defs.Factory, histogrammar.defs.Container, histogrammar.primitives.collection.Collection

Accumulate aggregators of different types, indexed by i0 through i9. Every sub-aggregator is filled with every input datum.

This primitive provides an anonymous collection of aggregators of different types, usually for gluing together various statistics. For instance, if the following associates a sum of weights to every bin in a histogram,

Bin.ing(100, 0, 1, lambda d: d.x,
  Sum.ing(lambda d: d.weight))

the following would associate the sum of weights and the sum of squared weights to every bin:

Bin.ing(100, 0, 1, lambda d: d.x,
  Branch.ing(Sum.ing(lambda d: d.weight),
             Sum.ing(lambda d: d.weight**2)))

Branch is a basic building block for complex aggregators. The limitation to ten branches, indexed from i0 to i9, is a concession to type inference in statically typed languages. It is not a fundamental limit, but the type-metaprogramming becomes increasingly complex as branches are added. Error messages may be convoluted as the compiler presents internals of the type-metaprogramming in response to a user’s simple mistake.

Therefore, individual implementations may allow more than ten branches, but the Histogrammar standard only requires ten.

To collect an unlimited number of aggregators of the same type without naming them, use Index. To collect aggregators of the same type with string-based labels, use Label. To collect aggregators of different types with string-based labels, use UntypedLabel.


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


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

Parameters:values (list of Container) – the collection of aggregators to fill.
Other Parameters:
 entries (float) – the number of entries, initially 0.0.

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, *values)

Create a Branch that is only capable of being added.

  • entries (float) – the number of entries.
  • values (list of Container) – the collection of filled aggregators.

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.


Attempt to get index i, returning None if it does not exist.

getOrElse(x, default)

Attempt to get index i, returning an alternative if it does not exist.

static ing(*values)

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.


Return the number of containers.


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.


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.


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