Skip to content

Axes

Axis Specifications

Axes define the domains of variables. Every axis is of one of three types: continuous, binned or categorical. The type of an axis is determined structurally: an axis struct that contains the field categories is a categorical axis. Any other axis is a binned axis if it contains nbins or edges, and a continuous axis otherwise. Wherever axes appear in this standard, the permitted types of axes are stated there.

Continuous Axes

A continuous axis describes a real-valued variable. All continuous axes must include:

  • name: name of the axis; identifies the variable it describes
  • min: lower bound of the domain
  • max: upper bound of the domain

These fields define the domain over which PDFs are normalized. Where continuous axes are permitted, the binning fields (nbins, edges) must not be present.

Note on normalization: Any PDF depending on a continuous observable \(x\) must be normalized over the domain \([\text{min}, \text{max}]\) defined by that observable's axis, not over \((-\infty, \infty)\).

Binned Axes

A binned axis describes a real-valued variable whose domain is divided into a finite number of bins. The axis struct must contain name, the name of the axis identifying the variable it describes, alongside either the fields for regular binning or the fields for irregular binning, but not both.

Regular binning:

  • min: lower bound of the domain
  • max: upper bound of the domain
  • nbins: integer number of equal-width bins between min and max

Irregular binning:

  • edges: array of \(n+1\) bin boundaries in strictly ascending order, where \(n\) is the number of bins. The first and last entries are the lower and upper bounds of the domain.

Backward compatibility. Documents conforming to versions of this standard before 0.3 may contain min and max alongside edges; the first entry of edges must then be equal to min and the last entry equal to max. Documents conforming to version 0.3 or later must not contain min or max alongside edges.

Categorical Axes

A categorical axis describes a discrete-valued variable that takes one of a finite set of named states. A categorical axis must include:

  • name: name of the axis; identifies the variable it describes
  • categories: array of unique strings enumerating the allowed values. Categories are identified by their name; no meaning is assigned to their position in categories beyond the storage layout defined in Flattening of Binned Contents.

The categories array itself defines the domain of the axis; the fields min, max, nbins and edges must not be present.

Two documents that list the same categories in a different order describe the same model, provided that all arrays laid out along the axis (see Flattening of Binned Contents) are permuted accordingly.

Flattening of Binned Contents

For binned data with axes \(a_0, \ldots, a_{d-1}\), listed in this order in axes, where axis \(a_j\) has \(N_j\) bins (for a categorical axis, the number of entries in categories), contents must have length \(\prod_{j=0}^{d-1} N_j\). Bins along axis \(a_j\) are indexed by \(0 \le i_j < N_j\) in ascending order (for categorical axes, in the order given by categories); there are no underflow or overflow bins. The content of the bin with indices \((i_0, \ldots, i_{d-1})\) is stored at position

\[ k(i_0, \ldots, i_{d-1}) = \sum_{j=0}^{d-1} i_j \prod_{m=j+1}^{d-1} N_m , \]

i.e. the last axis listed in axes varies fastest (for \(j = d-1\) the product is empty and equals \(1\)). For example, for two axes with \(N_0 = 2\) and \(N_1 = 3\), contents lists the bins \((0,0), (0,1), (0,2), (1,0), (1,1), (1,2)\) in this order. The same order applies to any other array holding one value per bin.