YODA is hosted by Hepforge, IPPP Durham

# Welcome to YODA’s documentation!¶

This is the documentation for the Python interface to the YODA data analysis package. It’s rather bare-bones at the moment, and based largely on the docstrings embedded in the Python code. So the documentation you see here is the same as the documentation you can get by calling pydoc or by using the help() function in the Python interpreter, e.g.:

\$ python
>>> import yoda
>>> help(yoda.Histo1D)


As time goes by we’ll fill this documentation out with more examples etc. – at least that’s the plan. Feel free to hassle the authors at yoda@projects.hepforge.org if we don’t do it, or if you find things we can improve either in the documentation or the package itself.

# Scripts¶

TODO: the set of yoda* scripts needs to be documented here. For now, you can find out how to use them by calling e.g. yodafoo –help. Here is the current list of scripts that you can try:

aida2flat
aida2yoda
flat2yoda
yoda2aida
yoda2flat
yoda2root
yodacmp
yodacnv
yoda-config
yodahist
yodals
yodamerge
yodaplot
yodascale


# Code docs¶

## Basic usage¶

• Booking and filling a histogram called ‘/foo’ with 20 bins between 0 and 1:

import yoda, random
h = yoda.Histo1D(20, 0.0, 1.0, "/foo")
print h
=> <Histo1D '/foo' 20 bins, sumw=0, xmean=None>
for _ in range(1000):
h.fill(random.uniform(-0.5, 1.5))
print h
=> <Histo1D '/foo' 20 bins, sumw=1e+03, xmean=4.84e-01>

• Extracting histogram statistical properties:

## Binned range extent:
print h.xMin, h.xMax
=> 0.0 1.0

## Sum-of-weights / integral for whole-range and binned-range only:
print h.sumW(), h.sumW(False)
=> 1000.0 485.0

## All-range and binned-range whole-histo stats:
print h.xMean(), h.xStdDev(), h.xVariance()
=> 0.484427317353 0.581387076141 0.338010932304
print h.xMean(False), h.xStdDev(False), h.xVariance(False)
=> 0.513167582561 0.284805437402 0.0811141371739

• Extracting bin properties:

## Looping over bins:
for b in h.bins:
print b
=> <HistoBin1D x=[0, 0.05)>
=> <HistoBin1D x=[0.05, 0.1)>
=> <HistoBin1D x=[0.1, 0.15)>
=> ...

## Extract
for b in h.bins:
print b.xMin, b.xMid, b.xMax, b.xFocus, b.height, b.area, b.sumW2, b.xMean, b.xStdDev
=> 0.0 0.025 0.05 0.0277156583946 380.0 19.0 19.0 0.0277156583946 0.0156189244522
=> 0.05 0.075 0.1 0.077004858171 440.0 22.0 22.0 0.077004858171 0.0160044669375
=> 0.1 0.125 0.15 0.124272408837 640.0 32.0 32.0 0.124272408837 0.01703599909
=> ...

• Saving to file, and reading back:

## Saving
yoda.write(h, "foo.yoda") #< can pass any iterable of histos or other analysis objects

## Reading to a dict, indexed by histo paths
print aos
=> {'/foo': <Histo1D '/foo' 20 bins, sumw=1e+03, xmean=4.84e-01>}

print aos
=> [<Histo1D '/foo' 20 bins, sumw=1e+03, xmean=4.84e-01>]
print aos[0].path
=> /foo

• Converting to a Scatter, and looping over points:

s = h.mkScatter()  # <- you may also read scatters from file, e.g. reference data
print s
=> <Scatter2D '/foo' 20 points>

for p in s.points:
print p.x, p.y, p.xErrs, p.yErrAvg, p.errAvg(2)
=> 0.025 380.0 ErrorPair(minus=0.025, plus=0.025) 87.1779788708 87.1779788708
=> 0.075 440.0 ErrorPair(minus=0.02500000000000001, plus=0.024999999999999994) 93.8083151965 93.8083151965
=> ...


print s.annotations
=> ['Path', 'Title', 'Type']
s.setAnnotation("Foo", "My own private Patrick Swayze")
print s.annotations
=> ['Foo', 'Path', 'Title', 'Type']
print s.annotation("Foo")
=> 'My own private Patrick Swayze'


## Tips and tricks¶

• Filtering analysis objects by path:

aos = yoda.read("mydata.yoda")
hs = [h for h in aos.values() if "foo" in h.path]


or, if you have YODA version >= 1.3.2, you can do regex filtering inline during analysis object reading from file:

aos = yoda.read("mydata.yoda", ".*foo.*")

• Summing histograms:

import operator


## Bin/point path searching¶

The yoda.search subpackage provides tools for finding histogram bins and scatter points based on their parent objects’ paths, and on the bin/point index or the physical location of bin edges.

class yoda.search.PointMatcher(patt)[source]

System for selecting subsets of bins based on a search range syntax extended from Professor weight files: Path structure: /path/parts/to/histo[syst_variation]@xmin:xmax

or: /path/parts/to/histo[syst_variation]#nmin:nmax

TODO: Extend to multi-dimensional ranges i.e. @xmin:xmax,#nymin:nymax,...

match_pos(p)[source]

Decide if a given point p is in the match range.

p must be an object with attrs xmin, xmax, n

TODO: Use open ranges to include underflow and overflow

TODO: Allow negative indices in Python style, and use index=-1 to mean the N+1 index needed to include the last bin without picking up the overflow, too.

TODO: Extension to multiple dimensions

set_patt(patt)[source]

Find path and index/pos parts of patt and assign them to object attrs

yoda.search.match_aos(aos, patts, unpatts=None, search=False)[source]

Filter a list of analysis objects to those which match given path-matching patterns.

@a patts is a regex or iterable of regexes for positive matching, i.e. retention; @a unpatts is the equivalent for negative matching, i.e. rejection even if a patt matches.

@a search will use Python regex search mode rather than match mode, i.e. match if any part of the path fits the regex, rather than requiring a match from the start of the path.

## Histogram plotting¶

The yoda.plotting module provides in-development tools for conveniently comparing and plotting YODA objects using matplotlib.

yoda.plotting.mk_figaxes_1d(ratio=True, title=None, figsize=(8, 6))[source]

Make figure and subplot grid layout

yoda.plotting.mplot(hs, outfiles=None, plotkeys={}, ratio=None, nproc=None)[source]

Plot the given list of histogram(s) using the Python multiprocessing module to distribute the work on to multiple parallel processes. This is just syntactic sugar for something fairly easily done by the user.

hs must be an iterable, each entry of which will be the content of a single plot: the entries can either be single histograms or lists of histograms, i.e. either kind of valid first argument to plot().

The outfiles, plotkeys, and ratio arguments can either be iterables of valid corresponding plot() args, or single instances of such args to be applied to all the plots.

The nproc argument should be the integer number of parallel processes on which to distribute the plotting. nproc = None (the default value) will use Ncpu-1 or 1 process, whichever is larger. If nproc = 1, multiprocessing will not be used – this may ease debugging.

The return value is a list of the return tuples from each call to plot(), of the same length as the hs arg.

yoda.plotting.plot(hs, outfile=None, plotkeys={}, ratio=None)[source]

Plot the given histogram(s) on a single figure, maybe with a ratio plot, and return the 2-tuple of (fig, (main_axis,ratio_axis)). If an outfile is given, it will be saved to before returning the figure objects.

yoda.plotting.plot_hist_1d(h, outfile=None, plotkeys={})[source]

Plot the given histogram on a single figure without a ratio plot, returning the 2-tuple of (fig, main_axis).

yoda.plotting.plot_hists_1d(hs, outfile=None, ratio=None, plotkeys={})[source]

Plot the given histograms on a single figure, returning the 3-tuple of (fig, main_axis, ratio_axis), and saving to outfile if it is given.

yoda.plotting.setup_mpl(engine='MPL', font='TeX Gyre Pagella', fontsize=17, mfont=None, textfigs=True)[source]

One-liner matplotlib (mpl) setup.

By default mpl will be configured with the TeX PGF rendering backend, and a Palatino-like font for both text and math contexts, using ‘lower-case numerals’ if supported. Setting the engine to ‘TEX’ will use standard mpl rendering, with calls to LaTeX for axis labels and other text; setting it to ‘MPL’ will use the built-in mpl MathText renderer. MPL mode only supports a limited set of LaTeX macros and does not render as well as TeX, but it is faster and can be used to render to an interactive window.

The font and mfont optional arguments can be used to choose a different text font and math font respectively; if mfont is None, it defaults to the same as the text font. The textfigs boolean argument can be set false to disable the lower-case/text/old-style numerals and use ‘upper-case’ numerals everywhere. These options do not currently apply to the MPL rendering engine.

## Miscellaneous¶

Other functionality in the yoda package...

yoda.script_helpers.filter_aos(aos, match_re=None, unmatch_re=None)[source]

Remove unwanted analysis objects from a dict (modifies arg, also returned)

yoda.script_helpers.parse_x2y_args(args, xextn, yextn)[source]

Helper function for working out input and output filenames for YODA converter scripts, where the output name is generated by replacing the input file extension (xextn) with the output one (yextn), if there are exactly two arguments and the second arg is consistent with an output name. The x/yextn arguments should include the leading dot.

## Main YODA objects¶

The wrappers on the core C++ YODA data types and functions are all defined in the yoda.core module, which is generated semi-automatically by the Cython system. However, they are all available directly in the yoda namespace by virtue of a from yoda.core import * in the yoda package.

class yoda.core.AnalysisObject

AnalysisObject is the base class of the main user-facing objects, such as the Histo, Profile and Scatter classes.

annotation(self, string k, default=None)

Get annotation k from this object (falling back to default if not set).

annotations

AnalysisObject.annotations(self) () -> list[str]

A list of all annotation/metadata keys.
clearAnnotations(self)

Clear the annotations dictionary.

dim

AnalysisObject.dim(self) Fill dimension or plot dimension of this object, for fillables and scatters respectively

dump(self)

A human readable representation of this object.

hasAnnotation(self, string k)

Check if this object has annotation k.

name

AnalysisObject.name(self)

Return the histogram name, i.e. the last part of the path (which may be empty).

path

Used for persistence and as a unique identifier. Must begin with a ‘/’ if not the empty string.

rmAnnotation(self, string k)

Remove annotation k from this object.

setAnnotation(self, string k, v)

Set annotation k on this object.

title

type

AnalysisObject.type(self) String identifier for this type

class yoda.core.Bin1D_Dbn1D

Bin1D_Dbn1D(xlow, xhigh)

1D Bin based on an underlying Dbn1D.

ProfileBin1D(xlow, xhigh)

merge(self, Bin1D_Dbn1D other)

merge(other) -> Bin1D_Dbn1D. Merge this bin with another of the same type. Only directly adjacent bins, i.e. those sharing a common edge, can be merged.

sumWX

Bin1D_Dbn1D.sumWX(self)

The sum of weights-times-x: sum(weights * x)

sumWX2

Bin1D_Dbn1D.sumWX2(self)

The sum of weights-times-x-squared: sum(weights * x * x)

xEdges

Bin1D_Dbn1D.xEdges(self) The lower and upper edges.

xFocus

Bin1D_Dbn1D.xFocus(self)

The focus of the bin. If the bin has been filled, then this is the mean fill on this bin. If the bin has not been filled, then the focus is the midpoint of the bin.

xMax

Bin1D_Dbn1D.xMax(self) The upper bin edge.

xMean

Bin1D_Dbn1D.xMean(self) The mean of the x-values that have filled the bin.

xMid

Bin1D_Dbn1D.xMid(self) The midpoint of the bin.

xMin

Bin1D_Dbn1D.xMin(self) The lower bin edge.

xRMS

Bin1D_Dbn1D.xRMS(self)

The root-mean-square of the x-values that have filled the bin.

xStdDev

Bin1D_Dbn1D.xStdDev(self)

The standard deviation of the x-values that have filled the bin.

xStdErr

Bin1D_Dbn1D.xStdErr(self)

The standard error of the x-values that have filled the bin.

xVariance

Bin1D_Dbn1D.xVariance(self)

The variance of the x-values that have filled the bin.

xWidth

Bin1D_Dbn1D.xWidth(self) The width of the bin.

class yoda.core.Bin1D_Dbn2D

Bin1D_Dbn2D(xlow, xhigh)

1D Bin based on an underlying Dbn2D.

ProfileBin1D(xlow, xhigh)

merge(self, Bin1D_Dbn2D other)

merge(other) -> Bin1D_Dbn2D. Merge this bin with another of the same type. Only directly adjacent bins, i.e. those sharing a common edge, can be merged.

sumWX

Bin1D_Dbn2D.sumWX(self)

The sum of weights-times-x: sum(weights * x)

sumWX2

Bin1D_Dbn2D.sumWX2(self)

The sum of weights-times-x-squared: sum(weights * x * x)

xEdges

Bin1D_Dbn2D.xEdges(self) The lower and upper edges.

xFocus

Bin1D_Dbn2D.xFocus(self)

The focus of the bin. If the bin has been filled, then this is the mean fill on this bin. If the bin has not been filled, then the focus is the midpoint of the bin.

xMax

Bin1D_Dbn2D.xMax(self) The upper bin edge.

xMean

Bin1D_Dbn2D.xMean(self) The mean of the x-values that have filled the bin.

xMid

Bin1D_Dbn2D.xMid(self) The midpoint of the bin.

xMin

Bin1D_Dbn2D.xMin(self) The lower bin edge.

xRMS

Bin1D_Dbn2D.xRMS(self)

The root-mean-square of the x-values that have filled the bin.

xStdDev

Bin1D_Dbn2D.xStdDev(self)

The standard deviation of the x-values that have filled the bin.

xStdErr

Bin1D_Dbn2D.xStdErr(self)

The standard error of the x-values that have filled the bin.

xVariance

Bin1D_Dbn2D.xVariance(self)

The variance of the x-values that have filled the bin.

xWidth

Bin1D_Dbn2D.xWidth(self) The width of the bin.

class yoda.core.Bin2D_Dbn2D

Bin2D_Dbn2D(xlow, xhigh, ylow, yhigh) 2D Bin class templated on a Dbn2D

sumWX

Bin2D_Dbn2D.sumWX(self)

sumWX2

Bin2D_Dbn2D.sumWX2(self)

sumWXY

Bin2D_Dbn2D.sumWXY(self)

sumWY

Bin2D_Dbn2D.sumWY(self)

sumWY2

Bin2D_Dbn2D.sumWY2(self)

xEdges

Bin2D_Dbn2D.xEdges(self)

The lower and upper x edges.

xFocus

Bin2D_Dbn2D.xFocus(self) Focus of the bin in x

xMax

Bin2D_Dbn2D.xMax(self) High edge in x.

xMean

Bin2D_Dbn2D.xMean(self)

xMid

Bin2D_Dbn2D.xMid(self) Geometric centre of the bin in x

xMin

Bin2D_Dbn2D.xMin(self) Low edge in x.

xRMS

Bin2D_Dbn2D.xRMS(self)

xStdDev

Bin2D_Dbn2D.xStdDev(self)

xStdErr

Bin2D_Dbn2D.xStdErr(self)

xVariance

Bin2D_Dbn2D.xVariance(self)

xWidth

Bin2D_Dbn2D.xWidth(self) Width of the bin in x

xyEdges

Bin2D_Dbn2D.xyEdges(self)

The lower and upper x,y edge pairs.

xyFocus

Bin2D_Dbn2D.xyFocus(self) The focus of the bin in the x- and y-dimensions

xyMax

Bin2D_Dbn2D.xyMax(self) High edges in x,y.

xyMean

Bin2D_Dbn2D.xyMean(self)

xyMid

Bin2D_Dbn2D.xyMid(self) Geometric centre of the bin

xyMin

Bin2D_Dbn2D.xyMin(self) Low edges in x,y.

xyRMS

Bin2D_Dbn2D.xyRMS(self)

xyStdDev

Bin2D_Dbn2D.xyStdDev(self)

xyStdErr

Bin2D_Dbn2D.xyStdErr(self)

xyVariance

Bin2D_Dbn2D.xyVariance(self)

xyWidths

Bin2D_Dbn2D.xyWidths(self) The widths of this bin in the x- and y-dimensions.

yEdges

Bin2D_Dbn2D.yEdges(self)

The lower and upper y edges.

yFocus

Bin2D_Dbn2D.yFocus(self) Focus of the bin in y

yMax

Bin2D_Dbn2D.yMax(self) High edge in y.

yMean

Bin2D_Dbn2D.yMean(self)

yMid

Bin2D_Dbn2D.yMid(self) Geometric centre of the bin in y

yMin

Bin2D_Dbn2D.yMin(self) Low edge in y.

yRMS

Bin2D_Dbn2D.yRMS(self)

yStdDev

Bin2D_Dbn2D.yStdDev(self)

yStdErr

Bin2D_Dbn2D.yStdErr(self)

yVariance

Bin2D_Dbn2D.yVariance(self)

yWidth

Bin2D_Dbn2D.yWidth(self) Width of the bin in y

class yoda.core.Bin2D_Dbn3D

Bin2D_Dbn3D(xlow, xhigh, ylow, yhigh) 2D Bin class templated on a Dbn3D

sumWX

Bin2D_Dbn3D.sumWX(self)

sumWX2

Bin2D_Dbn3D.sumWX2(self)

sumWXY

Bin2D_Dbn3D.sumWXY(self)

sumWY

Bin2D_Dbn3D.sumWY(self)

sumWY2

Bin2D_Dbn3D.sumWY2(self)

xEdges

Bin2D_Dbn3D.xEdges(self)

The lower and upper x edges.

xFocus

Bin2D_Dbn3D.xFocus(self) Focus of the bin in x

xMax

Bin2D_Dbn3D.xMax(self) High edge in x.

xMean

Bin2D_Dbn3D.xMean(self)

xMid

Bin2D_Dbn3D.xMid(self) Geometric centre of the bin in x

xMin

Bin2D_Dbn3D.xMin(self) Low edge in x.

xRMS

Bin2D_Dbn3D.xRMS(self)

xStdDev

Bin2D_Dbn3D.xStdDev(self)

xStdErr

Bin2D_Dbn3D.xStdErr(self)

xVariance

Bin2D_Dbn3D.xVariance(self)

xWidth

Bin2D_Dbn3D.xWidth(self) Width of the bin in x

xyEdges

Bin2D_Dbn3D.xyEdges(self)

The lower and upper x,y edge pairs.

xyFocus

Bin2D_Dbn3D.xyFocus(self) The focus of the bin in the x- and y-dimensions

xyMax

Bin2D_Dbn3D.xyMax(self) High edges in x,y.

xyMean

Bin2D_Dbn3D.xyMean(self)

xyMid

Bin2D_Dbn3D.xyMid(self) Geometric centre of the bin

xyMin

Bin2D_Dbn3D.xyMin(self) Low edges in x,y.

xyRMS

Bin2D_Dbn3D.xyRMS(self)

xyStdDev

Bin2D_Dbn3D.xyStdDev(self)

xyStdErr

Bin2D_Dbn3D.xyStdErr(self)

xyVariance

Bin2D_Dbn3D.xyVariance(self)

xyWidths

Bin2D_Dbn3D.xyWidths(self) The widths of this bin in the x- and y-dimensions.

yEdges

Bin2D_Dbn3D.yEdges(self)

The lower and upper y edges.

yFocus

Bin2D_Dbn3D.yFocus(self) Focus of the bin in y

yMax

Bin2D_Dbn3D.yMax(self) High edge in y.

yMean

Bin2D_Dbn3D.yMean(self)

yMid

Bin2D_Dbn3D.yMid(self) Geometric centre of the bin in y

yMin

Bin2D_Dbn3D.yMin(self) Low edge in y.

yRMS

Bin2D_Dbn3D.yRMS(self)

yStdDev

Bin2D_Dbn3D.yStdDev(self)

yStdErr

Bin2D_Dbn3D.yStdErr(self)

yVariance

Bin2D_Dbn3D.yVariance(self)

yWidth

Bin2D_Dbn3D.yWidth(self) Width of the bin in y

class yoda.core.Counter

Counter(char *path=’‘, char *title=’‘)

Weight counter. Like a histogram without any axis (and hence only one bin).

Call fill() like with a histogram. Sums of weights can be returned, with val() and err() being shorthand for the sum of weights and its binomial error.

Counter(path=””, title=””).
Construct a counter with optional path and title but no bins.
clone(self)

None -> Couner. Clone this Counter.

divideBy(self, Counter other, efficiency=False)
effNumEntries(self)

None -> float Effective number of times this counter was filled, computed from weights.

err

Counter.err(self) () -> float

Binomial uncertainty on the sum of weights filled into this counter.
fill(self, weight=1.0)

([w]) -> None. Fill with given optional weight.

mkScatter(self)

None -> Scatter1D. Convert this Counter to a Scatter1D, with x representing the value and error.

numEntries(self)

None -> int Number of times this counter was filled.

relErr

Counter.relErr(self) () -> float

Relative binomial uncertainty on the sum of weights filled into this counter.
reset(self)

None -> None. Reset the counter.

scaleW(self, w)

(float) -> None. Rescale the weights in this counter by the factor w.

sumW(self)

() -> float Sum of weights filled into this counter.

sumW2(self)

() -> float Sum of weights filled into this counter.

val

Counter.val(self) () -> float

Sum of weights filled into this counter.
class yoda.core.Dbn0D

Dbn0D()

A zero-dimensional ‘counter’, used and exposed by Counter.

copy(self)
effNumEntries

Dbn0D.effNumEntries(self) Effective number of entries (for weighted events)

errW

Dbn0D.errW(self) Error on sumW

fill(self, weight=1.0)

(float weight=1.0) -> None

Fills the distribution with the given weight at given x.

numEntries

Dbn0D.numEntries(self) The number of entries

relErrW

Dbn0D.relErrW(self) Relative error on sumW

reset(self)

() -> None

Reset the distribution counters to the unfilled state.

scaleW(self, w)

(float) -> None

Scale the weights by the given factor.

sumW

Dbn0D.sumW(self) sum(weights)

sumW2

Dbn0D.sumW2(self) sum(weights * weights)

class yoda.core.Dbn1D

Dbn1D()

A 1D distribution ‘counter’, used and exposed by 1D histograms and their bins.

copy(self)
effNumEntries

Dbn1D.effNumEntries(self) Effective number of entries (for weighted events)

errW

Dbn1D.errW(self) Error on sumW

fill(self, x, weight=1.0)

(float x, float weight=1.0) -> None

Fills the distribution with the given weight at given x.

mean

Dbn1D.xMean(self) Weighted mean of x

numEntries

Dbn1D.numEntries(self) The number of entries

relErrW

Dbn1D.relErrW(self) Relative error on sumW

reset(self)

() -> None

Reset the distribution counters to the unfilled state.

rms

Dbn1D.xRMS(self) Weighted root mean squared (RMS) of x

scaleW(self, w)

(float) -> None

Scale the weights by the given factor.

scaleX(self, x)

(float) -> None

Scale the x dimension by the given factor.

stdDev

Dbn1D.xStdDev(self) Weighted standard deviation of x

stdErr

Dbn1D.xStdErr(self) Weighted standard error on <x>

sumW

Dbn1D.sumW(self) sum(weights)

sumW2

Dbn1D.sumW2(self) sum(weights * weights)

sumWX

Dbn1D.sumWX(self) sum(weights * xs)

sumWX2

Dbn1D.sumWX2(self) sum(weights * xs * xs)

variance

Dbn1D.xVariance(self) Weighted variance of x

xMean

Dbn1D.xMean(self) Weighted mean of x

xRMS

Dbn1D.xRMS(self) Weighted root mean squared (RMS) of x

xStdDev

Dbn1D.xStdDev(self) Weighted standard deviation of x

xStdErr

Dbn1D.xStdErr(self) Weighted standard error on <x>

xVariance

Dbn1D.xVariance(self) Weighted variance of x

class yoda.core.Dbn2D

Dbn2D()

A 2D distribution ‘counter’, used and exposed by 2D histograms and 1D profiles and their bins.

copy(self)
effNumEntries

Dbn2D.effNumEntries(self) Effective number of entries (for weighted events)

errW

Dbn2D.errW(self) Error on sumW

fill(self, x, y, weight=1.0)

(x, y, weight=1.0) -> None

Fills the distribution with the given weight at given (x, y).

mean

Dbn2D.mean(self) Weighted mean of x

numEntries

Dbn2D.numEntries(self) The number of entries

relErrW

Dbn2D.relErrW(self) Relative error on sumW

reset(self)

() -> None

Reset the distribution counters to the unfilled state.

rms

Dbn2D.rms(self) Weighted root mean squared (RMS) of x

scaleW(self, w)

(float) -> None

Scale the weights by the given factor.

scaleX(self, x)

(float) -> None

Scale the x dimension by the given factor.

scaleXY(self, x, y)

(float, float) -> None

Scale the x and y dimensions by the given factors.

scaleY(self, y)

(float) -> None

Scale the y dimension by the given factor.

stdDev

Dbn2D.stdDev(self) Weighted standard deviation of x

stdErr

Dbn2D.stdErr(self) Weighted standard error on <x>

sumW

Dbn2D.sumW(self) sum(weights)

sumW2

Dbn2D.sumW2(self) sum(weights * weights)

sumWX

Dbn2D.sumWX(self) sum(weights * xs)

sumWX2

Dbn2D.sumWX2(self) sum(weights * xs * xs)

sumWXY

Dbn2D.sumWXY(self) sum(weights xs * ys)

sumWY

Dbn2D.sumWY(self) sum(weights * ys)

sumWY2

Dbn2D.sumWY2(self) sum(weights * ys * ys)

variance

Dbn2D.variance(self) Weighted variance of x

class yoda.core.Dbn3D

Dbn3D()

A 3D distribution ‘counter’, used and exposed by 2D profiles and their bins.

copy(self)
effNumEntries

Dbn3D.effNumEntries(self) Effective number of entries (for weighted events)

errW

Dbn3D.errW(self) Error on sumW

fill(self, x, y, z, weight=1.0)

(x, y, z, weight=1.0) -> None

Fills the distribution with the given weight at given (x, y).

mean

Dbn3D.mean(self) Weighted mean of x

numEntries

Dbn3D.numEntries(self) The number of entries

relErrW

Dbn3D.relErrW(self) Relative error on sumW

reset(self)

() -> None

Reset the distribution counters to the unfilled state.

rms

Dbn3D.rms(self) Weighted root mean squared (RMS) of x

scaleW(self, w)

(float) -> None

Scale the weights by the given factor.

scaleX(self, x)

(float) -> None

Scale the x dimension by the given factor.

scaleXYZ(self, x, y, z)

(float, float, float) -> None

Scale the x, y and z dimensions by the given factors.

scaleY(self, y)

(float) -> None

Scale the y dimension by the given factor.

scaleZ(self, z)

(float) -> None

Scale the z dimension by the given factor.

stdDev

Dbn3D.stdDev(self) Weighted standard deviation of x

stdErr

Dbn3D.stdErr(self) Weighted standard error on <x>

sumW

Dbn3D.sumW(self) sum(weights)

sumW2

Dbn3D.sumW2(self) sum(weights * weights)

sumWX

Dbn3D.sumWX(self) sum(weights * xs)

sumWX2

Dbn3D.sumWX2(self) sum(weights * xs * xs)

sumWXY

Dbn3D.sumWXY(self) sum(weights * xs * ys)

sumWXZ

Dbn3D.sumWXZ(self) sum(weights * xs * zs)

sumWY

Dbn3D.sumWY(self) sum(weights * ys)

sumWY2

Dbn3D.sumWY2(self) sum(weights * ys * ys)

sumWYZ

Dbn3D.sumWYZ(self) sum(weights * ys * zs)

sumWZ

Dbn3D.sumWZ(self) sum(weights * zs)

sumWZ2

Dbn3D.sumWZ2(self) sum(weights * zs * zs)

variance

Dbn3D.variance(self) Weighted variance of x

class yoda.core.Histo1D

Histo1D(*args, **kwargs)

1D histogram, with distinction between bin areas and heights.

Complete histogram binning is supported, including uniform/regular binning, variable-width binning, unbinned gaps in the covered range, and under/overflows. Rebinning by integer factors, or by explicit merging of contiguous bins is also supported.

Rescaling of weights and/or the x axis is permitted in-place: the result is still a valid Histo1D. Binning-compatible 1D histograms may be divided, resulting in a Scatter2D since further fills would not be meaningful.

Several sets of arguments are tried by the constructor in the following order.

Histo1D(path=””, title=””).
Construct a histogram with optional path and title but no bins.
Histo1D(nbins, low, high, path=””, title=””)
Construct a histogram with optional path and title, and nbins bins uniformly distributed between low and high.
Histo1D(B, path=””, title=””).
Construct a histogram with optional path and title, from an iterator of bins, B.

(low, high) -> None. Add a bin.

bin(self, i)

Get the i’th bin (equivalent to bins[i]

binAt(self, x)

Get the bin containing position x

binIndexAt(self, x)

Get the bin index containing position x

bins

Histo1D.bins(self) Access the ordered bins list.

clone(self)

None -> Histo1D. Clone this Histo1D.

divideBy(self, Histo1D h, efficiency=False)

Histo1D -> Scatter2D

Divide this histogram by h, returning a Scatter2D. The optional ‘efficiency’ argument, if set True, will use a binomial efficiency treatment of the errors.

effNumEntries(self, includeoverflows=True)

([bool]) -> float Effective number of times this histogram was filled, computed from weights, and optionally excluding the overflows.

fill(self, x, weight=1.0)

(x,[w]) -> None. Fill with given x value and optional weight.

fillBin(self, size_t ix, weight=1.0)

(ix,[w]) -> None. Fill bin ix and optional weight.

integral(self, includeoverflows=True)

([bool]) -> float Histogram integral, optionally excluding the overflows.

integralRange(self, int ia, int ib)

(int, int) -> float Integral between bins ia..ib inclusive

integralTo(self, int ia, includeunderflow=True)

(int, [bool]) -> float Integral up to bin ia inclusive, optionally excluding the underflow

mergeBins(self, ia, ib)

mergeBins(ia, ib) -> None. Merge bins from indices ia through ib.

mkScatter(self, usefocus=False)

None -> Scatter2D. Convert this Histo1D to a Scatter2D, with y representing bin heights (not sumW) and height errors.

normalize(self, normto=1.0, includeoverflows=True)

(float, bool) -> None. Normalize the histogram.

numBins

Histo1D.numBins(self) () -> int

Number of bins (not including overflows).
numEntries(self, includeoverflows=True)

([bool]) -> int Number of times this histogram was filled, optionally excluding the overflows.

overflow

Histo1D.overflow(self) None -> Dbn1D

The Dbn1D representing the overflow distribution.
rebin(self, arg, **kwargs)

(n) -> None or ([edges]) -> None Merge bins, like rebinBy if an int argument is given; like rebinTo if an iterable is given.

rebinBy(self, n, begin=0, end=None)

(n) -> None. Merge every group of n bins together (between begin and end, if specified).

rebinTo(self, edges)

([edges]) -> None. Merge bins to produce the given new edges... which must be a subset of the current ones.

reset(self)

None -> None. Reset the histogram but leave the bin structure.

scaleW(self, w)

(float) -> None. Rescale the weights in this histogram by the factor w.

sumW(self, includeoverflows=True)

([bool]) -> float Sum of weights filled into this histogram, optionally excluding the overflows.

sumW2(self, includeoverflows=True)

([bool]) -> float Sum of weights filled into this histogram, optionally excluding the overflows.

toIntegral(self, efficiency=False, includeunderflow=True, includeoverflow=True)

None -> Scatter2D.

Convert this Histo1D to a Scatter2D representing an integral (i.e. cumulative) histogram constructed from this differential one.

The efficiency argument is used to construct an ‘efficiency integral’ histogram and the includeXXXflow bools determine whether under and overflows are included in computing the (efficiency) integral.

totalDbn

Histo1D.totalDbn(self) None -> Dbn1D

The Dbn1D representing the total distribution.
underflow

Histo1D.underflow(self) None -> Dbn1D

The Dbn1D representing the underflow distribution.
xEdges

Histo1D.xEdges(self) All x edges of the histo.

xMax

Histo1D.xMax(self) High x edge of the histo.

xMean(self, includeoverflows=True)

([bool]) -> float Mean x of the histogram, optionally excluding the overflows.

xMin

Histo1D.xMin(self) Low x edge of the histo.

xRMS(self, includeoverflows=True)

([bool]) -> float RMS in x of the histogram, optionally excluding the overflows.

xStdDev(self, includeoverflows=True)

([bool]) -> float Standard deviation in x of the histogram, optionally excluding the overflows.

xStdErr(self, includeoverflows=True)

([bool]) -> float Standard error on the mean x of the histogram, optionally excluding the overflows.

xVariance(self, includeoverflows=True)

([bool]) -> float Variance in x of the histogram, optionally excluding the overflows.

class yoda.core.Histo2D

Histo2D(*args, **kwargs)

2D histogram.

Complete histogramming is supported, including uniform/regular binning, variable-width bininng, unbinned gaps in the covered range, and outflows (under/overflows around all edges and corners).

Rebinning by integer factors, or by explicit merging of contiguous bins is also supported, but in development.

Rescaling of weights and/or the x axis is permitted in-place: the result is still a valid Histo2D. Binning-compatible 2D histograms may be divided, resulting in a Scatter3D since further fills would not be meaningful.

Several sets of arguments are tried by the constructor in the following order.

Histo2D(path=””, title=””).
Construct a histogram with optional path and title but no bins.
Histo2D(nxbins, xlow, xhigh, nybins, ylow, yhigh, path=””, title=””).
Construct a histogram with nxbins on the x axis and nybins on the y axis, distributed linearly between the respective low–high limits.

bin(self, i)

Get the i’th bin

binAt(self, x, y)

Get the bin containing position (x,y)

binIndexAt(self, x, y)

Get the bin index pair containing position (x,y)

bins

Histo2D.bins(self) Access the ordered bins list.

clone(self)

None -> Histo2D. Clone this Profile2D.

divideBy(self, Histo2D h, efficiency=False)

Histo2D -> Scatter3D

Divide this histogram by Histo2D h, returning a Scatter3D. The optional ‘efficiency’ argument, if set True, will use a binomial efficiency treatment of the errors.

effNumEntries(self, includeoverflows=True)

([bool]) -> float Effective number of times this histogram was filled, computed from weights and optionally excluding overflows.

fill(self, double x, double y, weight=1.0)

(x,y,[w]) -> None. Fill with given x,y values and optional weight.

fillBin(self, size_t i, weight=1.0)

(i,[w]) -> None. Fill bin i and optional weight.

integral(self, includeoverflows=True)

([bool]) -> float Histogram integral, optionally excluding the overflows.

mkScatter(self, usefocus=False)

None -> Scatter3D. Convert this Histo2D to a Scatter3D, with y representing bin heights (not sumW) and height errors.

normalize(self, double normto, bool includeoverflows=True)

(float, bool) -> None. Normalize the histogram.

numBins

Histo2D.numBins(self) () -> int

Number of bins (not including overflows).
numBinsX

Histo2D.numBinsX(self) () -> int

Number of bins (edges) along the x axis.
numBinsY

Histo2D.numBinsY(self) () -> int

Number of bins (edges) along the y axis.
numEntries(self, includeoverflows=True)

([bool]) -> int Number of times this histogram was filled, optionally excluding overflows.

reset(self)

None -> None. Reset the histogram but leave the bin structure.

scaleW(self, w)

(float) -> None. Rescale the weights in this histogram by the factor w.

sumW(self, includeoverflows=True)

([bool]) -> float Sum of weights filled into this histogram.

sumW2(self, includeoverflows=True)

([bool]) -> float Sum of squared weights filled into this histogram.

totalDbn

Histo2D.totalDbn(self) () -> Dbn2D

The Dbn2D representing the total distribution.
xMax

Histo2D.xMax(self) High x edge of the histo.

xMean(self, includeoverflows=True)

([bool]) -> float Mean x of the histogram, optionally excluding the overflows.

xMin

Histo2D.xMin(self) Low x edge of the histo.

xRMS(self, includeoverflows=True)

([bool]) -> float RMS in x of the histogram, optionally excluding the overflows.

xStdDev(self, includeoverflows=True)

([bool]) -> float Standard deviation in x of the histogram, optionally excluding the overflows.

xStdErr(self, includeoverflows=True)

([bool]) -> float Standard error on the mean x of the histogram, optionally excluding the overflows.

xVariance(self, includeoverflows=True)

([bool]) -> float Variance in x of the histogram, optionally excluding the overflows.

xyMean(self, includeoverflows=True)

([bool]) -> (float,float) Mean (x,y) of the histogram, optionally excluding the overflows.

xyRMS(self, includeoverflows=True)

([bool]) -> (float,float) RMS in (x,y) of the histogram, optionally excluding the overflows.

xyStdDev(self, includeoverflows=True)

([bool]) -> (float,float) Standard deviations in (x,y) of the histogram, optionally excluding the overflows.

xyStdErr(self, includeoverflows=True)

([bool]) -> (float,float) Standard errors on the mean (x,y) of the histogram, optionally excluding the overflows.

xyVariance(self, includeoverflows=True)

([bool]) -> (float,float) Variances in (x,y) of the histogram, optionally excluding the overflows.

yMax

Histo2D.yMax(self) High y edge of the histo.

yMean(self, includeoverflows=True)

([bool]) -> float Mean y of the histogram, optionally excluding the overflows.

yMin

Histo2D.yMin(self) Low y edge of the histo.

yRMS(self, includeoverflows=True)

([bool]) -> float RMS in y of the histogram, optionally excluding the overflows.

yStdDev(self, includeoverflows=True)

([bool]) -> float Standard deviation in y of the histogram, optionally excluding the overflows.

yStdErr(self, includeoverflows=True)

([bool]) -> float Standard error on the mean y of the histogram, optionally excluding the overflows.

yVariance(self, includeoverflows=True)

([bool]) -> float Variance in y of the histogram, optionally excluding the overflows.

class yoda.core.HistoBin1D

HistoBin1D(double a, double b)

area

HistoBin1D.area(self)

b.area <==> b.sumW

The area of the bin is the sum of weights of the bin; it is independent of width.

areaErr

HistoBin1D.areaErr(self)

Error computed using binomial statistics on squared sum of bin weights, i.e. s.areaErr = sqrt(s.sumW2)

height

HistoBin1D.height(self)

b.height <==> b.area / b.width

The height of the bin is defined as the area divided by the width.

heightErr

HistoBin1D.heightErr(self)

Height error - scales the s.areaError by the reciprocal of the bin width.

relErr

HistoBin1D.relErr(self)

Relative error - same for either area or height interpretations.

class yoda.core.HistoBin2D

HistoBin2D(xlow, xhigh, ylow, yhigh)

height

HistoBin2D.height(self)

heightErr

HistoBin2D.heightErr(self)

relErr

HistoBin2D.relErr(self)

volume

HistoBin2D.volume(self)

volumeErr

HistoBin2D.volumeErr(self)

class yoda.core.Point

A generic point with errors, used by the Scatter classes.

dim

Point.dim(self) None -> int

Space dimension of the point (should match containing Scatter)
errAvg(self, i)

int -> float Average error on axis i

errMinus(self, i)

int -> float Minus error on axis i

errPlus(self, i)

int -> float Plus error on axis i

errs(self, i)

int -> float Errors on axis i

set(self, i, val, *es)
(int, float, float) -> None
(int, float, [float, float]) -> None (int, float, float, float) -> None

Set value and errors on axis i

setErr(self, i, e)

(int, float) -> None Set symmetric errors on axis i

setErrMinus(self, i, e)

(int, float) -> None Set minus error on axis i

setErrPlus(self, i, e)

(int, float) -> None Set plus error on axis i

setErrs(self, i, *es)
(int, float) -> None
(int, [float, float]) -> None (int, float, float) -> None

Set asymmetric errors on axis i

setVal(self, i, val)

(int, float) -> None Value on axis i

val(self, i)

int -> float Value on axis i

class yoda.core.Point1D

Point1D(x=0, xerrs=0)

A 1D point with errors, used by the Scatter1D class.

copy(self)
scaleX(self, a)

(float) -> None Scale the x values and errors by factor a.

x

x coordinate

xErrs

The x errors

xMax

Point1D.xMax(self) The maximum x position, i.e. highest error

xMin

Point1D.xMin(self) The minimum x position, i.e. lowest error

class yoda.core.Point2D

Point2D(x=0, y=0, xerrs=0, yerrs=0)

A 2D point with errors, used by the Scatter2D class.

copy(self)
scale(self, x=1.0, y=1.0)

(float=1, float=1) -> None DEPRECATED! Use scaleXY Scale the point coordinates by the given factors.

scaleX(self, a)

(float) -> None Scale the x values and errors by factor a.

scaleXY(self, x=1.0, y=1.0)

(float=1, float=1) -> None Scale the point coordinates by the given factors.

scaleY(self, a)

(float) -> None Scale the y values and errors by factor a.

x

x coordinate

xErrs

The x errors

xMax

Point2D.xMax(self) The maximum x position, i.e. highest error

xMin

Point2D.xMin(self) The minimum x position, i.e. lowest error

xy

x and y coordinates as a tuple

y

y coordinate

yErrs

The y errors

yMax

Point2D.yMax(self) The maximum y position, i.e. highest error

yMin

Point2D.yMin(self) The minimum y position, i.e. lowest error

class yoda.core.Point3D

Point3D(x=0, y=0, z=0, xerrs=0, yerrs=0, zerrs=0)

A 3D point with errors, used by the Scatter3D class.

copy(self)
scaleX(self, ax)

(float) -> None Scale the x point coordinates by the given factor.

scaleXYZ(self, ax=1.0, ay=1.0, az=1.0)

(float=1.0, float=1.0, float=1.0) -> None Scale the point coordinates by the given factors.

scaleY(self, ay)

(float) -> None Scale the y point coordinates by the given factor.

scaleZ(self, az)

(float) -> None Scale the z point coordinates by the given factor.

x

x coordinate

xMax

Point3D.xMax(self) The maximum x position, i.e. highest error

xMin

Point3D.xMin(self) The minimum x position, i.e. lowest error

y

y coordinate

yMax

Point3D.yMax(self) The maximum y position, i.e. highest error

yMin

Point3D.yMin(self) The minimum y position, i.e. lowest error

z

y coordinate

zMax

Point3D.zMax(self) The maximum z position, i.e. highest error

zMin

Point3D.zMin(self) The minimum z position, i.e. lowest error

class yoda.core.Profile1D

Profile1D(*args, **kwargs)

1D profile histogram, used to measure mean values of a y variable, binned in x.

Complete histogram binning is supported, including uniform/regular binning, variable-width binning, unbinned gaps in the covered range, and under/overflows. Rebinning by integer factors, or by explicit merging of contiguous bins is also supported.

Rescaling of weights and/or the x axis is permitted in-place: the result is still a valid Histo1D. Binning-compatible 1D histograms may be divided, resulting in a Scatter2D since further fills would not be meaningful.

Several sets of arguments are tried by the constructor in the following order.

Profile1D(path=””, title=””).
Construct a histogram with optional path and title but no bins.
Profile1D(nbins, low, high, path=””, title=””)
Construct a histogram with optional path and title, and nbins bins uniformly distributed between low and high.
Profile1D(B, path=””, title=””).
Construct a histogram with optional path and title, from an iterator of bins, B.

binAt(self, x)

Get the bin containing position x

binIndexAt(self, x)

Get the bin index containing position x

bins

Profile1D.bins(self) Access the ordered bins list.

clone(self)

None -> Profile1D. Clone this Profile1D.

divideBy(self, Profile1D h)
effNumEntries(self, includeoverflows=True)

([bool]) -> float Effective number of times this histogram was filled, computed from weights and optionally excluding the overflows.

fill(self, x, y, weight=1.0)

(x,y,[w]) -> None. Fill with given x & y values and optional weight.

fillBin(self, size_t ix, double y, weight=1.0)

(ix,y,[w]) -> None. Fill bin ix with y value and optional weight.

mergeBins(self, a, b)

mergeBins(ia, ib) -> None. Merge bins from indices ia through ib.

mkScatter(self, usefocus=False, usestddev=False)

None -> Scatter2D. Convert this Profile1D to a Scatter2D, with y representing mean bin y values and their standard errors.

numBins

Profile1D.numBins(self) () -> int

Number of bins (not including overflows).
numEntries(self, includeoverflows=True)

([bool]) -> int Number of times this histogram was filled, optionally excluding the overflows.

overflow

Profile1D.overflow(self) () -> Dbn2D

The Dbn2D representing the overflow distribution.
rebin(self, arg, **kwargs)

(n) -> None or ([edges]) -> None Merge bins, like rebinBy if an int argument is given; like rebinTo if an iterable is given.

rebinBy(self, n, begin=0, end=None)

(n) -> None. Merge every group of n bins together (between begin and end, if specified).

rebinTo(self, edges)

([edges]) -> None. Merge bins to produce the given new edges... which must be a subset of the current ones.

reset(self)

None -> None. Reset the histogram but leave the bin structure.

scaleW(self, double w)

(float) -> None. Rescale the weights in this histogram by the factor w.

scaleY(self, double f)

(float) -> None. Scale the y-direction (profiled value) in this histogram by the factor f.

sumW(self, includeoverflows=True)

([bool]) -> float Sum of weights filled into this histogram.

sumW2(self, includeoverflows=True)

([bool]) -> float Sum of weights filled into this histogram.

totalDbn

Profile1D.totalDbn(self) () -> Dbn2D

The Dbn2D representing the total distribution.
underflow

Profile1D.underflow(self) () -> Dbn2D

The Dbn2D representing the underflow distribution.
xEdges

Profile1D.xEdges(self) All x edges of the histo.

xMax

Profile1D.xMax(self) High x edge of the histo.

xMean(self, includeoverflows=True)

([bool]) -> float Mean x of the histogram, optionally excluding the overflows.

xMin

Profile1D.xMin(self) Low x edge of the histo.

xRMS(self, includeoverflows=True)

([bool]) -> float RMS in x of the histogram, optionally excluding the overflows.

xStdDev(self, includeoverflows=True)

([bool]) -> float Standard deviation in x of the histogram, optionally excluding the overflows.

xStdErr(self, includeoverflows=True)

([bool]) -> float Standard error on the mean x of the histogram, optionally excluding the overflows.

xVariance(self, includeoverflows=True)

([bool]) -> float Variance in x of the histogram, optionally excluding the overflows.

class yoda.core.Profile2D

Profile2D(*args, **kwargs)

2D profile histogram, used to measure mean values of a z variable, binned in x and y.

Complete histogramming is supported, including uniform/regular binning, variable-width bininng, unbinned gaps in the covered range, and outflows (under/overflows around all edges and corners).

Rebinning by integer factors, or by explicit merging of contiguous bins is also supported, but in development.

Rescaling of weights and/or the x axis is permitted in-place: the result is still a valid Histo2D. Binning-compatible 1D histograms may be divided, resulting in a Scatter3D since further fills would not be meaningful.

Several sets of arguments are tried by the constructor in the following order.

Histo2D(path=””, title=””).
Construct a histogram with optional path and title but no bins.
Histo2D(nxbins, xlow, xhigh, nybins, ylow, yhigh, path=””, title=””).
Construct a histogram with nxbins on the x axis and nybins on the y axis, distributed linearly between the respective low–high limits.

addBin(self, double xlow, double xhigh, double ylow, double yhigh)

bin(self, i)

Get the i’th bin

binAt(self, x, y)

Get the bin containing position (x,y)

binIndexAt(self, x, y)

Get the bin index pair containing position (x,y)

bins

Profile2D.bins(self) Access the ordered bins list.

clone(self)

None -> Profile2D. Clone this Profile2D.

divideBy(self, Profile2D h)
effNumEntries(self, includeoverflows=True)

([bool]) -> float Effective number of times this histogram was filled, computed from weights and optionally excluding the overflows.

fill(self, double x, double y, double z, double weight=1.0)

(x,y,z,[w]) -> None. Fill with given x,y & z values and optional weight.

fillBin(self, size_t i, double z, weight=1.0)

(i,z,[w]) -> None. Fill bin i with value z and optional weight.

mkScatter(self, usefocus=False, usestddev=False)

None -> Scatter3D. Convert this Profile2D to a Scatter3D, with z representing mean bin y values and their standard errors.

numBins

Profile2D.numBins(self) () -> int

Number of bins (not including overflows).
numBinsX

Profile2D.numBinsX(self) () -> int

Number of bins (edges) along the x axis.
numBinsY

Profile2D.numBinsY(self) () -> int

Number of bins (edges) along the y axis.
numEntries(self, includeoverflows=True)

([bool]) -> int Number of times this histogram was filled, optionally excluding the overflows.

reset(self)

None -> None. Reset the histogram but leave the bin structure.

scaleW(self, w)

(float) -> None. Rescale the weights in this histogram by the factor w.

scaleZ(self, double f)

(float) -> None. Scale the z-direction (profiled value) in this histogram by the factor f.

sumW(self, includeoverflows=True)

([bool]) -> float Sum of weights filled into this histogram.

sumW2(self, includeoverflows=True)

([bool]) -> float Sum of squared weights filled into this histogram.

totalDbn

Profile2D.totalDbn(self) () -> Dbn3D

The Dbn3D representing the total distribution.
xMax

Profile2D.xMax(self) High x edge of the histo.

xMean(self, includeoverflows=True)

([bool]) -> float Mean x of the histogram, optionally excluding the overflows.

xMin

Profile2D.xMin(self) Low x edge of the histo.

xRMS(self, includeoverflows=True)

([bool]) -> float RMS in x of the histogram, optionally excluding the overflows.

xStdDev(self, includeoverflows=True)

([bool]) -> float Standard deviation in x of the histogram, optionally excluding the overflows.

xStdErr(self, includeoverflows=True)

([bool]) -> float Standard error on the mean x of the histogram, optionally excluding the overflows.

xVariance(self, includeoverflows=True)

([bool]) -> float Variance in x of the histogram, optionally excluding the overflows.

xyMean(self, includeoverflows=True)

([bool]) -> (float,float) Mean (x,y) of the histogram, optionally excluding the overflows.

xyRMS(self, includeoverflows=True)

([bool]) -> (float,float) RMS in (x,y) of the histogram, optionally excluding the overflows.

xyStdDev(self, includeoverflows=True)

([bool]) -> (float,float) Standard deviations in (x,y) of the histogram, optionally excluding the overflows.

xyStdErr(self, includeoverflows=True)

([bool]) -> (float,float) Standard errors on the mean (x,y) of the histogram, optionally excluding the overflows.

xyVariance(self, includeoverflows=True)

([bool]) -> (float,float) Variances in (x,y) of the histogram, optionally excluding the overflows.

yMax

Profile2D.yMax(self) High y edge of the histo.

yMean(self, includeoverflows=True)

([bool]) -> float Mean y of the histogram, optionally excluding the overflows.

yMin

Profile2D.yMin(self) Low y edge of the histo.

yRMS(self, includeoverflows=True)

([bool]) -> float RMS in y of the histogram, optionally excluding the overflows.

yStdDev(self, includeoverflows=True)

([bool]) -> float Standard deviation in y of the histogram, optionally excluding the overflows.

yStdErr(self, includeoverflows=True)

([bool]) -> float Standard error on the mean y of the histogram, optionally excluding the overflows.

yVariance(self, includeoverflows=True)

([bool]) -> float Variance in y of the histogram, optionally excluding the overflows.

class yoda.core.ProfileBin1D

ProfileBin1D(double a, double b)

A 1D profile bin, as stored inside Profile1D.

Only one constructor:

• ProfileBin1D(xlow, xhigh)
mean

ProfileBin1D.mean(self) The mean of the y-values that have filled the bin.

rms

ProfileBin1D.rms(self) The RMS of the y-values that have filled the bin.

stdDev

ProfileBin1D.stdDev(self) The standard deviation of the y-values that have filled the bin.

stdErr

ProfileBin1D.stdErr(self) The standard error of the y-values that have filled the bin.

stddev

ProfileBin1D.stdDev(self) The standard deviation of the y-values that have filled the bin.

stderr

ProfileBin1D.stdErr(self) The standard error of the y-values that have filled the bin.

sumWY

ProfileBin1D.sumWY(self) sum(weights * ys)

sumWY2

ProfileBin1D.sumWY2(self) sum(weights * ys * ys)

variance

ProfileBin1D.variance(self) The variance of the y-values that have filled the bin.

class yoda.core.ProfileBin2D

ProfileBin2D(xlow, xhigh, ylow, yhigh)

mean

ProfileBin2D.mean(self)

rms

ProfileBin2D.rms(self)

stdDev

ProfileBin2D.stdDev(self)

stdErr

ProfileBin2D.stdErr(self)

stddev

ProfileBin2D.stdDev(self)

stderr

ProfileBin2D.stdErr(self)

sumWZ

ProfileBin2D.sumWZ(self)

sumWZ2

ProfileBin2D.sumWZ2(self)

variance

ProfileBin2D.variance(self)

class yoda.core.Scatter1D

Scatter1D(*args, **kwargs)

1D scatter plot, i.e. a collection of Point1D objects with positions and errors.

Constructor calling idioms:

Scatter1D(path=””, title=””)
Create a new empty scatter, with optional path and title.
Scatter1D(points, path=””, title=””):
Create a new empty scatter from an iterable of points, with optional path and title.

TODO: more documentation!

Provide either a single yoda.Point1D object, or the two args: x, xerrs=0.

clone(self)

() -> Scatter1D. Clone this Scatter1D.

mkScatter(self)

None -> Scatter1D. Make a new Scatter1D. Exists to allow mkScatter calls on any AnalysisObject, even if it already is a scatter.

numPoints

Scatter1D.numPoints(self) () -> int

Number of points in this scatter.
point(self, size_t i)

Access the i’th point.

points

Scatter1D.points(self) Access the ordered list of points.

scaleX(self, a)

(float) -> None Scale the x values and errors of the points in this scatter by factor a.

transformX(self, f)

(fn) -> None Transform the x values and errors of the points in this scatter by function f.

class yoda.core.Scatter2D

Scatter2D(*args, **kwargs)

2D scatter plot, i.e. a collection of Point2D objects with positions and errors.

Constructor calling idioms:

Scatter2D(path=””, title=””)
Create a new empty scatter, with optional path and title.
Scatter2D(points, path=””, title=””):
Create a new empty scatter from an iterable of points, with optional path and title.

TODO: more documentation!

Provide either a single yoda.Point2D object, or the four args: x, y, xerrs=0, yerrs=0.

clone(self)

() -> Scatter2D. Clone this Scatter2D.

combineWith(self, others)

Try to add points from other Scatter2Ds into this one.

mkScatter(self)

None -> Scatter2D. Make a new Scatter2D. Exists to allow mkScatter calls on any AnalysisObject, even if it already is a scatter.

numPoints

Scatter2D.numPoints(self) () -> int

Number of points in this scatter.
point(self, size_t i)

Access the i’th point.

points

Scatter2D.points(self) Access the ordered list of points.

scale(self, ax=1.0, ay=1.0)

(float=1, float=1) -> None DEPRECATED: USE scaleXY Scale the values and errors of the points in this scatter by factors ax, ay.

scaleX(self, a)

(float) -> None Scale the x values and errors of the points in this scatter by factor a.

scaleXY(self, ax=1.0, ay=1.0)

(float=1, float=1) -> None Scale the values and errors of the points in this scatter by factors ax, ay.

scaleY(self, a)

(float) -> None Scale the y values and errors of the points in this scatter by factor a.

transformX(self, f)

(fn) -> None Transform the x values and errors of the points in this scatter by function f.

transformY(self, f)

(fn) -> None Transform the y values and errors of the points in this scatter by function f.

class yoda.core.Scatter3D

Scatter3D(*args, **kwargs)

3D scatter plot, i.e. a collection of Point3D objects with positions and errors.

Constructor calling idioms:

Scatter3D(path=””, title=””)
Create a new empty scatter, with optional path and title.
Scatter3D(points, path=””, title=””):
Create a new empty scatter from an iterable of points, with optional path and title.

TODO: more documentation!

Provide either a single yoda.Point3D object, or the 3-6 args: x, y, z, xerrs=0, yerrs=0, zerrs=0.

clone(self)

() -> Scatter3D. Clone this Scatter3D.

combineWith(self, others)

Try to add points from other Scatter3Ds into this one.

mkScatter(self)

None -> Scatter3D. Make a new Scatter3D. Exists to allow mkScatter calls on any AnalysisObject, even if it already is a scatter.

numPoints

Scatter3D.numPoints(self) () -> int

Number of points in this scatter.
point(self, size_t i)

Access the i’th point.

points

Scatter3D.points(self) Access the ordered list of points.

scale(self, ax=1, ay=1, az=1)

(float=1, float=1, float=1) -> None DEPRECATED: USE scaleXYZ Scale the values and errors of the points in this scatter by factors ax, ay, az.

scaleX(self, a)

(float) -> None Scale the x values and errors of the points in this scatter by factor a.

scaleXYZ(self, ax=1, ay=1, az=1)

(float=1, float=1, float=1) -> None Scale the values and errors of the points in this scatter by factors ax, ay, az.

scaleY(self, a)

(float) -> None Scale the y values and errors of the points in this scatter by factor a.

scaleZ(self, a)

(float) -> None Scale the z values and errors of the points in this scatter by factor a.

transformX(self, f)

(fn) -> None Transform the x values and errors of the points in this scatter by function f.

transformY(self, f)

(fn) -> None Transform the y values and errors of the points in this scatter by function f.

transformZ(self, f)

(fn) -> None Transform the z values and errors of the points in this scatter by function f.

yoda.core.correlation(sample1, sample2)

(float, list[float]) -> int Return the unweighted correlation of the two provided sample lists.

yoda.core.covariance(sample1, sample2)

(list[float], list[float]) -> float Return the unweighted covariance of the two provided sample lists.

yoda.core.divide(ao1, ao2)

(AnalysisObject, AnalysisObject) -> Scatter{1,2,3}D Divide one AnalysisObject by another, producing a Scatter of appropriate dimension by using the logic of the bound divideBy methods.

yoda.core.index_between(x, binedges)

(float, list[float]) -> int Return the index of the bin which would contain x, or -1 if there is no enclosing bin in the given set of n+1 bin edges.

yoda.core.linspace(nbins, start, end)

(int, float, float) -> list[float] Make a list of n+1 bin edges linearly spaced between start and end, with the first and last edges on those boundaries.

yoda.core.logspace(nbins, start, end)

(int, float, float) -> list[float] Make a list of n+1 bin edges linearly spaced on the interval log(start..end), with the first and last edges on those boundaries.

yoda.core.mean(sample)

(list[float]) -> float Return the unweighted mean of the entries in the provided sample list.

yoda.core.mkScatter(ao, usefocus=False, usestddev=False)

AnalysisObject -> Scatter{1,2,3}D Convert an AnalysisObject to a Scatter, using the logic of the bound mkScatter methods.

@todo This falls back on use of optional args until we find one that works: is there a nicer way?

Read data objects from the provided filename, auto-determining the format from the file extension.

The loaded data objects can be filtered on their path strings, using the optional patterns and unpatterns arguments. These can be strings, compiled regex objects with a ‘match’ method, or any iterable of those types. If given, only analyses with paths which match at least one pattern, and do not match any unpatterns, will be returned.

Returns a dict or list of analysis objects depending on the asdict argument.

Read data objects from the provided AIDA-format file.

The loaded data objects can be filtered on their path strings, using the optional patterns and unpatterns arguments. These can be strings, compiled regex objects with a ‘match’ method, or any iterable of those types. If given, only analyses with paths which match at least one pattern, and do not match any unpatterns, will be returned.

Returns a dict or list of analysis objects depending on the asdict argument.

DEPRECATED: AIDA is a dead format. At some point we will stop supporting it.

Read data objects from the provided FLAT-format file.

The loaded data objects can be filtered on their path strings, using the optional patterns and unpatterns arguments. These can be strings, compiled regex objects with a ‘match’ method, or any iterable of those types. If given, only analyses with paths which match at least one pattern, and do not match any unpatterns, will be returned.

Returns a dict or list of analysis objects depending on the asdict argument.

Read data objects from the provided YODA-format file.

The loaded data objects can be filtered on their path strings, using the optional patterns and unpatterns arguments. These can be strings, compiled regex objects with a ‘match’ method, or any iterable of those types. If given, only analyses with paths which match at least one pattern, and do not match any unpatterns, will be returned.

Returns a dict or list of analysis objects depending on the asdict argument.

yoda.core.version()

Return YODA library version as a string

yoda.core.write(ana_objs, filename)

Write data objects to the provided filename, auto-determining the format from the file extension.

yoda.core.writeAIDA(ana_objs, file_or_filename)

Write data objects to the provided file in AIDA format.

yoda.core.writeFLAT(ana_objs, file_or_filename)

Write data objects to the provided file in FLAT format.

yoda.core.writeYODA(ana_objs, file_or_filename)

Write data objects to the provided file in YODA format.