Welcome to YODA’s documentation!¶
This is the documentation for the Python interface to the YODA data analysis package. It’s rather barebones 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.read)
>>> 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
yodaconfig
yodadiff
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.84e01>
Extracting histogram statistical properties:
## Binned range extent: print h.xMin, h.xMax => 0.0 1.0 ## Sumofweights / integral for wholerange and binnedrange only: print h.sumW(), h.sumW(False) => 1000.0 485.0 ## Allrange and binnedrange wholehisto 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 aos = yoda.read("foo.yoda") print aos => {'/foo': <Histo1D '/foo' 20 bins, sumw=1e+03, xmean=4.84e01>} ## Reading to a list aos = yoda.read("foo.yoda", asdict=False) print aos => [<Histo1D '/foo' 20 bins, sumw=1e+03, xmean=4.84e01>] 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 => ...
Analysis object metadata:
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 hsum = reduce(operator.add, hs)
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:nmaxTODO: Extend to multidimensional 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


yoda.search.
match_aos
(aos, patts, unpatts=None, search=False)[source]¶ Filter a list of analysis objects to those which match given pathmatching 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 indevelopment tools for conveniently comparing and plotting YODA objects using matplotlib.
Plotting utilities, particularly for interaction with matplotlib and Rivet makeplots

yoda.plotting.
initmpl
(engine='MPL', font='TeX Gyre Pagella', fontsize=17, mfont=None, textfigs=True)¶ Oneliner matplotlib (mpl) setup.
By default mpl will be configured with its native MathText rendering backend, and a Palatinolike font for both text and math contexts, using ‘lowercase 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 ‘PGF’ will use the TeX PGF renderer: both these modes are much slower than MPL mode, but the latter only supports a limited set of LaTeX macros and does not render as nicely as the TeX backends.
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 lowercase/text/oldstyle numerals and use ‘uppercase’ numerals everywhere. These options do not currently apply to the MPL rendering engine.

yoda.plotting.
mk_figaxes_1d
(ratio=True, title=None, figsize=(8, 6))[source]¶ Make a standard main+ratio plot figure and subplot layout

yoda.plotting.
mplinit
(engine='MPL', font='TeX Gyre Pagella', fontsize=17, mfont=None, textfigs=True)[source]¶ Oneliner matplotlib (mpl) setup.
By default mpl will be configured with its native MathText rendering backend, and a Palatinolike font for both text and math contexts, using ‘lowercase 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 ‘PGF’ will use the TeX PGF renderer: both these modes are much slower than MPL mode, but the latter only supports a limited set of LaTeX macros and does not render as nicely as the TeX backends.
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 lowercase/text/oldstyle numerals and use ‘uppercase’ numerals everywhere. These options do not currently apply to the MPL rendering engine.

yoda.plotting.
nplot
(hs, outfiles=None, ratio=True, show=False, nproc=1, **plotkeys)[source]¶ Plot the given list of histogram(s), cf. many calls to plot().
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().
Outfiles must be an iterable corresponding to hs, and ratio may either be a bool or such an iterable.
The return value is a list of the return tuples from each call to plot(), of the same length as the hs arg.
MULTIPROCESSING – WARNING CURRENTLY BROKEN
The main point of this function, other than convenience, is that the Python multiprocessing module can be used to distribute the work on to multiple parallel processes.
The nproc argument should be the integer number of parallel processes on which to distribute the plotting. nproc = None (the default value) will use Ncpu1 or 1 process, whichever is larger. If nproc = 1, multiprocessing will not be used – this avoids overhead and eases debugging.

yoda.plotting.
plot
(hs, outfile=None, ratio=True, show=False, axmain=None, axratio=None, **plotkeys)[source]¶ Plot the given histograms on a single figure, returning (fig, (main_axis, ratio_axis)). Show to screen if the second arg is True, and saving to outfile if it is otherwise nonnull.

yoda.plotting.
plot_hist_1d
(hs, outfile=None, ratio=True, show=False, axmain=None, axratio=None, **plotkeys)¶ Plot the given histograms on a single figure, returning (fig, (main_axis, ratio_axis)). Show to screen if the second arg is True, and saving to outfile if it is otherwise nonnull.

yoda.plotting.
plot_hists_1d
(hs, outfile=None, ratio=True, show=False, axmain=None, axratio=None, **plotkeys)¶ Plot the given histograms on a single figure, returning (fig, (main_axis, ratio_axis)). Show to screen if the second arg is True, and saving to outfile if it is otherwise nonnull.

yoda.plotting.
setup_mpl
(engine='MPL', font='TeX Gyre Pagella', fontsize=17, mfont=None, textfigs=True)¶ Oneliner matplotlib (mpl) setup.
By default mpl will be configured with its native MathText rendering backend, and a Palatinolike font for both text and math contexts, using ‘lowercase 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 ‘PGF’ will use the TeX PGF renderer: both these modes are much slower than MPL mode, but the latter only supports a limited set of LaTeX macros and does not render as nicely as the TeX backends.
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 lowercase/text/oldstyle numerals and use ‘uppercase’ 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, xextns, yextns)[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 semiautomatically 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.

yoda.core.
AO
¶ alias of
yoda.core.AnalysisObject

class
yoda.core.
AnalysisObject
¶ AnalysisObject is the base class of the main userfacing objects, such as the Histo, Profile and Scatter classes.

annotation
(self, k, default=None)¶ Get annotation k from this object (falling back to default if not set).
The annotation string will be automatically converted to Python native types as far as possible – more complex types are possible via the ast and yaml modules.

annotations
(self)¶ () > list[str] A list of all annotation/metadata keys.

annotationsDict
(self)¶ () > dict[str>str] A dict of all annotations/metadata entries.

clearAnnotations
(self)¶ Clear the annotations dictionary.

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, k)¶ Check if this object has annotation k.

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

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

rmAnnotation
(self, k)¶ Remove annotation k from this object.

setAnnotation
(self, k, v)¶ Set annotation k on this object.

setPath
(self, path)¶ Used for persistence and as a unique identifier. Must begin with a ‘/’ if not the empty string.

setTitle
(self, title)¶ Set the histogram title (optional)

title
(self)¶ Histogram title

type
(self)¶ String identifier for this type


class
yoda.core.
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
(self)¶ The sum of weightstimesx: sum(weights * x)

sumWX2
(self)¶ The sum of weightstimesxsquared: sum(weights * x * x)

xEdges
(self)¶ The lower and upper edges.

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
(self)¶ The upper bin edge.

xMean
(self)¶ The mean of the xvalues that have filled the bin.

xMid
(self)¶ The midpoint of the bin.

xMin
(self)¶ The lower bin edge.

xRMS
(self)¶ The rootmeansquare of the xvalues that have filled the bin.

xStdDev
(self)¶ The standard deviation of the xvalues that have filled the bin.

xStdErr
(self)¶ The standard error of the xvalues that have filled the bin.

xVariance
(self)¶ The variance of the xvalues that have filled the bin.

xWidth
(self)¶ The width of the bin.


class
yoda.core.
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
(self)¶ The sum of weightstimesx: sum(weights * x)

sumWX2
(self)¶ The sum of weightstimesxsquared: sum(weights * x * x)

xEdges
(self)¶ The lower and upper edges.

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
(self)¶ The upper bin edge.

xMean
(self)¶ The mean of the xvalues that have filled the bin.

xMid
(self)¶ The midpoint of the bin.

xMin
(self)¶ The lower bin edge.

xRMS
(self)¶ The rootmeansquare of the xvalues that have filled the bin.

xStdDev
(self)¶ The standard deviation of the xvalues that have filled the bin.

xStdErr
(self)¶ The standard error of the xvalues that have filled the bin.

xVariance
(self)¶ The variance of the xvalues that have filled the bin.

xWidth
(self)¶ The width of the bin.


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

adjacentTo
(self, Bin2D_Dbn2D other)¶

area
(self)¶ The area of this bin in the xy plane.

sumWX
(self)¶

sumWX2
(self)¶

sumWXY
(self)¶

sumWY
(self)¶

sumWY2
(self)¶

xEdges
(self)¶ The lower and upper x edges.

xFocus
(self)¶ Focus of the bin in x

xMax
(self)¶ High edge in x.

xMean
(self)¶

xMid
(self)¶ Geometric centre of the bin in x

xMin
(self)¶ Low edge in x.

xRMS
(self)¶

xStdDev
(self)¶

xStdErr
(self)¶

xVariance
(self)¶

xWidth
(self)¶ Width of the bin in x

xyEdges
(self)¶ The lower and upper x,y edge pairs.

xyFocus
(self)¶ The focus of the bin in the x and ydimensions

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

xyMean
(self)¶

xyMid
(self)¶ Geometric centre of the bin

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

xyRMS
(self)¶

xyStdDev
(self)¶

xyStdErr
(self)¶

xyVariance
(self)¶

xyWidths
(self)¶ The widths of this bin in the x and ydimensions.

yEdges
(self)¶ The lower and upper y edges.

yFocus
(self)¶ Focus of the bin in y

yMax
(self)¶ High edge in y.

yMean
(self)¶

yMid
(self)¶ Geometric centre of the bin in y

yMin
(self)¶ Low edge in y.

yRMS
(self)¶

yStdDev
(self)¶

yStdErr
(self)¶

yVariance
(self)¶

yWidth
(self)¶ Width of the bin in y


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

adjacentTo
(self, Bin2D_Dbn3D other)¶

area
(self)¶ The area of this bin in the xy plane.

sumWX
(self)¶

sumWX2
(self)¶

sumWXY
(self)¶

sumWY
(self)¶

sumWY2
(self)¶

xEdges
(self)¶ The lower and upper x edges.

xFocus
(self)¶ Focus of the bin in x

xMax
(self)¶ High edge in x.

xMean
(self)¶

xMid
(self)¶ Geometric centre of the bin in x

xMin
(self)¶ Low edge in x.

xRMS
(self)¶

xStdDev
(self)¶

xStdErr
(self)¶

xVariance
(self)¶

xWidth
(self)¶ Width of the bin in x

xyEdges
(self)¶ The lower and upper x,y edge pairs.

xyFocus
(self)¶ The focus of the bin in the x and ydimensions

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

xyMean
(self)¶

xyMid
(self)¶ Geometric centre of the bin

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

xyRMS
(self)¶

xyStdDev
(self)¶

xyStdErr
(self)¶

xyVariance
(self)¶

xyWidths
(self)¶ The widths of this bin in the x and ydimensions.

yEdges
(self)¶ The lower and upper y edges.

yFocus
(self)¶ Focus of the bin in y

yMax
(self)¶ High edge in y.

yMean
(self)¶

yMid
(self)¶ Geometric centre of the bin in y

yMin
(self)¶ Low edge in y.

yRMS
(self)¶

yStdDev
(self)¶

yStdErr
(self)¶

yVariance
(self)¶

yWidth
(self)¶ Width of the bin in y


class
yoda.core.
Counter
(path='', 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
(self)¶ () > float Binomial uncertainty on the sum of weights filled into this counter.

fill
(self, weight=1.0, fraction=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 > float Number of times this counter was filled.

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
(self)¶ () > float Sum of weights filled into this counter.

class
yoda.core.
Dbn0D
¶ A zerodimensional ‘counter’, used and exposed by Counter.

copy
(self)¶

effNumEntries
(self)¶ Effective number of entries (for weighted events)

errW
(self)¶ Error on sumW

fill
(self, weight=1.0, fraction=1.0)¶ (float weight=1.0) > None
Fills the distribution with the given weight at given x.

numEntries
(self)¶ The number of entries

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
(self)¶ sum(weights)

sumW2
(self)¶ sum(weights * weights)


class
yoda.core.
Dbn1D
¶ A 1D distribution ‘counter’, used and exposed by 1D histograms and their bins.

copy
(self)¶

effNumEntries
(self)¶ Effective number of entries (for weighted events)

errW
(self)¶ Error on sumW

fill
(self, x, weight=1.0, fraction=1.0)¶ (float x, float weight=1.0) > None
Fills the distribution with the given weight at given x.

numEntries
(self)¶ The number of entries

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.

scaleX
(self, x)¶ (float) > None
Scale the x dimension by the given factor.

sumW
(self)¶ sum(weights)

sumW2
(self)¶ sum(weights * weights)

sumWX
(self)¶ sum(weights * xs)

sumWX2
(self)¶ sum(weights * xs * xs)

xMean
(self)¶ Weighted mean of x

xRMS
(self)¶ Weighted root mean squared (RMS) of x

xStdDev
(self)¶ Weighted standard deviation of x

xStdErr
(self)¶ Weighted standard error on <x>

xVariance
(self)¶ Weighted variance of x


class
yoda.core.
Dbn2D
¶ A 2D distribution ‘counter’, used and exposed by 2D histograms and 1D profiles and their bins.
TODO: also provide normal scalar access to quantities like xRMS

copy
(self)¶

effNumEntries
(self)¶ Effective number of entries (for weighted events)

errW
(self)¶ Error on sumW

fill
(self, x, y, weight=1.0, fraction=1.0)¶ (x, y, weight=1.0) > None
Fills the distribution with the given weight at given (x, y).

mean
(self)¶ Weighted mean of x

numEntries
(self)¶ The number of entries

relErrW
(self)¶ Relative error on sumW

reset
(self)¶ () > None
Reset the distribution counters to the unfilled state.

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
(self)¶ Weighted standard deviation of x

stdErr
(self)¶ Weighted standard error on <x>

sumW
(self)¶ sum(weights)

sumW2
(self)¶ sum(weights * weights)

sumWX
(self)¶ sum(weights * xs)

sumWX2
(self)¶ sum(weights * xs * xs)

sumWXY
(self)¶ sum(weights xs * ys)

sumWY
(self)¶ sum(weights * ys)

sumWY2
(self)¶ sum(weights * ys * ys)

variance
(self)¶ Weighted variance of x


class
yoda.core.
Dbn3D
¶ A 3D distribution ‘counter’, used and exposed by 2D profiles and their bins.
TODO: also provide normal scalar access to quantities like xRMS

copy
(self)¶

effNumEntries
(self)¶ Effective number of entries (for weighted events)

errW
(self)¶ Error on sumW

fill
(self, x, y, z, weight=1.0, fraction=1.0)¶ (x, y, z, weight=1.0) > None
Fills the distribution with the given weight at given (x, y).

mean
(self)¶ Weighted mean of x

numEntries
(self)¶ The number of entries

relErrW
(self)¶ Relative error on sumW

reset
(self)¶ () > None
Reset the distribution counters to the unfilled state.

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
(self)¶ Weighted standard deviation of x

stdErr
(self)¶ Weighted standard error on <x>

sumW
(self)¶ sum(weights)

sumW2
(self)¶ sum(weights * weights)

sumWX
(self)¶ sum(weights * xs)

sumWX2
(self)¶ sum(weights * xs * xs)

sumWXY
(self)¶ sum(weights * xs * ys)

sumWXZ
(self)¶ sum(weights * xs * zs)

sumWY
(self)¶ sum(weights * ys)

sumWY2
(self)¶ sum(weights * ys * ys)

sumWYZ
(self)¶ sum(weights * ys * zs)

sumWZ
(self)¶ sum(weights * zs)

sumWZ2
(self)¶ sum(weights * zs * zs)

variance
(self)¶ Weighted variance of x


yoda.core.
H1D
¶ alias of
yoda.core.Histo1D

yoda.core.
H2D
¶ alias of
yoda.core.Histo2D

class
yoda.core.
Histo1D
(*args, **kwargs)¶ 1D histogram, with distinction between bin areas and heights.
Complete histogram binning is supported, including uniform/regular binning, variablewidth 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 inplace: the result is still a valid Histo1D. Binningcompatible 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.

addBin
(self, low, high)¶ (low, high) > None. Add a bin.

addBins
(self, edges_or_bins)¶ Add several bins.

areaErrs
(self)¶ All area errors of the histo.
TODO: asymm arg / areaErrsMinus/Plus?

areas
(self)¶ All areas of the histo.

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
(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, fraction=1.0)¶ (x,[w]) > None. Fill with given x value and optional weight.

fillBin
(self, size_t ix, weight=1.0, fraction=1.0)¶ (ix,[w]) > None. Fill bin ix and optional weight.

heightErrs
(self)¶ All height errors of the histo.
TODO: asymm arg / heightErrsMinus/Plus?

heights
(self)¶ All y heights of the histo.

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
(self)¶ () > int Number of bins (not including overflows).

numBinsX
(self)¶ () > int Number of xaxis bins (not including overflows).

numEntries
(self, includeoverflows=True)¶ ([bool]) > float Number of times this histogram was filled, optionally excluding the overflows.

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.

relErrs
(self)¶ All relative errors of the histo.
TODO: asymm arg / areaErrsMinus/Plus?

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.

sumWs
(self)¶ All sumW values of the histo.

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
(self)¶ None > Dbn1D The Dbn1D representing the total distribution.

underflow
(self)¶ None > Dbn1D The Dbn1D representing the underflow distribution.

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

xErrs
(self, foci=False)¶

xFoci
(self)¶ All x bin foci of the histo.

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

xMaxs
(self)¶ All x high edges of the histo.

xMean
(self, includeoverflows=True)¶ ([bool]) > float Mean x of the histogram, optionally excluding the overflows.

xMids
(self)¶ All x bin midpoints of the histo.

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

xMins
(self)¶ All x low edges 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.

xVals
(self, foci=False)¶

xVariance
(self, includeoverflows=True)¶ ([bool]) > float Variance in x of the histogram, optionally excluding the overflows.

yErrs
(self, area=False)¶

yMax
(self)¶ Highest y value.

yMaxs
(self, area=False)¶

yMin
(self)¶ Lowest x value.

yMins
(self, area=False)¶

yVals
(self, area=False)¶

class
yoda.core.
Histo2D
(*args, **kwargs)¶ 2D histogram.
Complete histogramming is supported, including uniform/regular binning, variablewidth 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 inplace: the result is still a valid Histo2D. Binningcompatible 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.

addBin
(self, xlow, xhigh, ylow, yhigh)¶ Add a bin.

addBins
(self, bins)¶ Add several bins.

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
(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, fraction=1.0)¶ (x,y,[w]) > None. Fill with given x,y values and optional weight.

fillBin
(self, size_t i, weight=1.0, fraction=1.0)¶ (i,[w]) > None. Fill bin i and optional weight.

heightErrs
(self, asymm=False, asgrid=False)¶ All height errors of the histo.
TODO: asymm arg / heightErrsMinus/Plus

heights
(self, asgrid=False)¶ All y heights of the histo.

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=1.0, bool includeoverflows=True)¶ (float, bool) > None. Normalize the histogram.

numBins
(self)¶ () > int Number of bins (not including overflows).

numBinsX
(self)¶ () > int Number of bins (edges) along the x axis.

numBinsY
(self)¶ () > int Number of bins (edges) along the y axis.

numEntries
(self, includeoverflows=True)¶ ([bool]) > float Number of times this histogram was filled, optionally excluding overflows.

relErrs
(self, asymm=False, asgrid=False)¶ All relative errors of the histo.
TODO: asymm arg / areaErrsMinus/Plus?

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.

sumWs
(self, asgrid=False)¶ All sumW values of the histo.

totalDbn
(self)¶ () > Dbn2D The Dbn2D representing the total distribution.

volumeErrs
(self, asymm=False, asgrid=False)¶ All volume errors of the histo.
TODO: asymm arg / areaErrsMinus/Plus?

volumes
(self, asgrid=False)¶ All volumes of the histo.

xEdges
(self)¶ Unique x edges of the histo.

xErrs
(self, foci=False, asgrid=False)¶ All x errors of the histo.

xFoci
(self, asgrid=False)¶ All x bin foci of the histo.

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

xMaxs
(self, unique=True, asgrid=False)¶ Unique/all x high edges of the histo.

xMean
(self, includeoverflows=True)¶ ([bool]) > float Mean x of the histogram, optionally excluding the overflows.

xMids
(self, unique=True, asgrid=False)¶ Unique/all x bin midpoints of the histo.

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

xMins
(self, unique=True, asgrid=False)¶ Unique/all x low edges 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.

xVals
(self, foci=False, asgrid=False)¶ All x values of the histo.

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.

yEdges
(self)¶ Unique y edges of the histo.

yErrs
(self, foci=False, asgrid=False)¶ All y errors of the histo.

yFoci
(self, asgrid=False)¶ All y bin foci of the histo.

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

yMaxs
(self, unique=True, asgrid=False)¶ Unique/all y high edges of the histo.

yMean
(self, includeoverflows=True)¶ ([bool]) > float Mean y of the histogram, optionally excluding the overflows.

yMids
(self, unique=True, asgrid=False)¶ Unique/all y bin midpoints of the histo.

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

yMins
(self, unique=True, asgrid=False)¶ Unique/all y low edges 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.

yVals
(self, foci=False, asgrid=False)¶ All y values of the histo.

yVariance
(self, includeoverflows=True)¶ ([bool]) > float Variance in y of the histogram, optionally excluding the overflows.

zErrs
(self, vol=False, asgrid=False)¶

zMax
(self, area=False)¶ Highest z value.

zMaxs
(self, area=False, asgrid=False)¶

zMin
(self, area=False)¶ Lowest z value.

zMins
(self, area=False, asgrid=False)¶

zVals
(self, vol=False, asgrid=False)¶

class
yoda.core.
HistoBin1D
(double a, double b)¶ 
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
(self)¶ Error computed using binomial statistics on squared sum of bin weights, i.e. s.areaErr = sqrt(s.sumW2)

height
(self)¶ b.height <==> b.area / b.width
The height of the bin is defined as the area divided by the width.

heightErr
(self)¶ Height error  scales the s.areaError by the reciprocal of the bin width.

relErr
(self)¶ Relative error  same for either area or height interpretations.


class
yoda.core.
HistoBin2D
(xlow, xhigh, ylow, yhigh)¶ 
height
(self)¶

heightErr
(self)¶

relErr
(self)¶

volume
(self)¶

volumeErr
(self)¶


class
yoda.core.
Index
¶ Index of a file.

toDict
(self)¶ Get dictionary containing index of the file.
 Returns:
 dict of str: dict of str: int : dictionary which holds
analysis object types (str) as keys and dictionaries as values which in turn hold paths (str) as keys and bin counts (int) as values.
 Example:
 {
 “Histo1D”: {
 “/RAW/ATLAS_2017_I1514251/d21x01y01”: 5, “/RAW/ATLAS_2017_I1514251/d33x01y01”: 16
}, “Scatter2D”: {
“/ATLAS_2017_I1514251/d09x01y01”: 3}
}


yoda.core.
P1D
¶ alias of
yoda.core.Profile1D

yoda.core.
P2D
¶ alias of
yoda.core.Profile2D

class
yoda.core.
Point
¶ A generic point with errors, used by the Scatter classes.

dim
(self)¶ None > int Space dimension of the point (should match containing Scatter)

errAvg
(self, i, source='')¶ int > float Average error on axis i. Optional string argument to specify which named uncertainty source from the breakdown to access. By default, the total uncertainty is accessed.

errMap
(self)¶ None > {string: [float,float]} error map of this point

errMinus
(self, i, source='')¶ int, string > float Minus error on axis i. Optional string argument to specify which named uncertainty source from the breakdown to change. By default, the total uncertainty is changed.

errPlus
(self, i, source='')¶ int, string > float Plus error on axis i. Optional string argument to specify which named uncertainty source from the breakdown to access. By default, the total uncertainty is accessed.

errs
(self, i, source='')¶ int, string > float Errors on axis i. Optional string argument allows to access a particular named uncertainty source from the breakdown

scale
(self, i, scale)¶ (int, float) > None Scale values on axis i

set
(self, i, val, *es, source='')¶  (int, float, float) > None
 (int, float, [float, float]) > None (int, float, float, float) > None (int, float, float, string) > None (int, float, [float, float],string) > None (int, float, float, float,string) > None
Set value and errors on axis i. Optional string argument to specify which named uncertainty source from the breakdown to change. By default, the total uncertainty is changed.

setErr
(self, i, e, source='')¶ (int, float, string) > None Set symmetric errors on axis i, with optional string argument to specify which named uncertainty source from the breakdown to change. By default, the total uncertainty is changed.

setErrMinus
(self, i, e, source='')¶ (int, float, string) > None Set minus error on axis i. Optional string argument to specify which named uncertainty source from the breakdown to change. By default, the total uncertainty is changed.

setErrPlus
(self, i, e, source='')¶ (int, float, string) > None Set plus error on axis i. Optional string argument to specify which named uncertainty source from the breakdown to change. By default, the total uncertainty is changed.

setErrs
(self, i, *es)¶  (int, float) > None
 (int, [float, float]) > None (int, float, float) > None (int, float, string) > None (int, [float, float], string) > None (int, float, float, string) > None
Set asymmetric errors on axis i. Optional string argument to specify which named uncertainty source from the breakdown to change. By default, the total uncertainty is changed.

setVal
(self, i, val)¶ (int, float) > None Value on axis i

val
(self, i)¶ int > float Value on axis i


class
yoda.core.
Point1D
(x=0, xerrs=0, source='')¶ 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.

setX
(self, x)¶ Set the x value

setXErrs
(self, *es)¶  (float,) > None
 ([float, float]) > None (float, float) > None (float, string) > None ([float, float], string) > None (float, float, string) > None
Set asymmetric errors on xaxis with an optional string argument to specify which named source of uncertainty in the error breakdown should be set. By default, if no source is provided, the total uncertainty is set.
TODO: simplify, this is too much for the Python wrapper

setYErrs
(self, val, source)¶

x
(self)¶ The x value

xErrAvg
(self)¶

xErrs
(self)¶ The x errors

xErrsFromSource
(self, source)¶ The y errors

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

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


class
yoda.core.
Point2D
(x=0, y=0, xerrs=0, yerrs=0, source='')¶ 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.

setX
(self, x)¶ Set the x value

setXErrs
(self, val)¶ Set the x errors

setY
(self, y)¶ Set the y value

setYErrs
(self, *es)¶  (float,) > None
 ([float, float]) > None (float, float) > None (float, string) > None ([float, float], string) > None (float, float, string) > None
Set asymmetric errors on yaxis with an optional string argument to specify which named source of uncertainty in the error breakdown should be set. By default, if no source is provided, the total uncertainty is set.
TODO: simplify, this is too much for the Python wrapper

x
(self)¶ The x value

xErrAvg
(self)¶

xErrs
(self)¶ The x errors

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

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

y
(self)¶ The y value

yErrAvg
(self)¶

yErrs
(self)¶ The (total) y errors

yErrsFromSource
(self, source)¶ The y errors from a particular named source of uncertainty in the breakdown

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

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


class
yoda.core.
Point3D
(x=0, y=0, z=0, xerrs=0, yerrs=0, zerrs=0, source='')¶ 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.

setX
(self, x)¶ Set the x value

setXErrs
(self, val)¶ Set the x errors

setY
(self, y)¶ Set the y value

setYErrs
(self, val)¶ Set the y errors

setZ
(self, z)¶ Set the z value

setZErrs
(self, *es)¶  (float,) > None
 ([float, float]) > None (float, float) > None (float, string) > None ([float, float], string) > None (float, float, string) > None
Set asymmetric errors on zaxis with an optional string argument to specify which named source of uncertainty in the error breakdown should be set. By default, if no source is provided, the total uncertainty is set.
TODO: simplify, this is too much for the Python wrapper

x
(self)¶ The x value

xErrAvg
(self)¶

xErrs
(self)¶ The x errors

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

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

y
(self)¶ The y value

yErrAvg
(self)¶

yErrs
(self)¶ The y errors

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

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

z
(self)¶ The z value

zErrAvg
(self)¶

zErrs
(self)¶ The z errors

zErrsFromSource
(self, source)¶ The z errors

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

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


class
yoda.core.
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, variablewidth 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 inplace: the result is still a valid Histo1D. Binningcompatible 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.

addBin
(self, low, high)¶ Add a bin.

addBins
(self, edges)¶ Add several bins.

bin
(self, i)¶ Get the i’th bin

binAt
(self, x)¶ Get the bin containing position x

binIndexAt
(self, x)¶ Get the bin index containing position x

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, fraction=1.0)¶ (x,y,[w]) > None. Fill with given x & y values and optional weight.

fillBin
(self, size_t ix, double y, double weight=1.0, double fraction=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
(self)¶ () > int Number of bins (not including overflows).

numBinsX
(self)¶ () > int Number of bins on the xaxis (not including overflows).

numEntries
(self, includeoverflows=True)¶ ([bool]) > float Number of times this histogram was filled, optionally excluding the overflows.

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 ydirection (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.

sumWs
(self)¶ All sumW values of the histo.

totalDbn
(self)¶ () > Dbn2D The Dbn2D representing the total distribution.

underflow
(self)¶ () > Dbn2D The Dbn2D representing the underflow distribution.

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

xErrs
(self, foci=False)¶

xFoci
(self)¶ All x bin foci of the histo.

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

xMaxs
(self)¶ All x high edges of the histo.

xMean
(self, includeoverflows=True)¶ ([bool]) > float Mean x of the histogram, optionally excluding the overflows.

xMids
(self)¶ All x bin midpoints of the histo.

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

xMins
(self)¶ All x low edges 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.

xVals
(self, foci=False)¶

xVariance
(self, includeoverflows=True)¶ ([bool]) > float Variance in x of the histogram, optionally excluding the overflows.

yErrs
(self, sd=False)¶

yMax
(self, sd=False)¶ Highest y value.

yMaxs
(self, sd=False)¶

yMeans
(self)¶ All y heights y means.

yMin
(self, sd=False)¶ Lowest y value.

yMins
(self, sd=False)¶

yStdDevs
(self)¶ All standard deviations of the y distributions.

yStdErrs
(self)¶ All standard errors on the y means.

yVals
(self)¶

class
yoda.core.
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, variablewidth 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 inplace: the result is still a valid Histo2D. Binningcompatible 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.
NOT YET FINISHED: please contact the YODA authors if you require extra functionality.

addBin
(self, double xlow, double xhigh, double ylow, double yhigh)¶ Add a bin.

addBins
(self, xcuts, ycuts)¶ Add several bins.

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
(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, double fraction=1.0)¶ (x,y,z,[w]) > None. Fill with given x,y & z values and optional weight and fill fraction.

fillBin
(self, size_t i, double z, double weight=1.0, double fraction=1.0)¶ (i,z,[w]) > None. Fill bin i with value z and optional weight and fill fraction.

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
(self)¶ () > int Number of bins (not including overflows).

numBinsX
(self)¶ () > int Number of bins (edges) along the x axis.

numBinsY
(self)¶ () > int Number of bins (edges) along the y axis.

numEntries
(self, includeoverflows=True)¶ ([bool]) > float 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 zdirection (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.

sumWs
(self, asgrid=False)¶ All sumW values of the histo.

totalDbn
(self)¶ () > Dbn3D The Dbn3D representing the total distribution.

xEdges
(self)¶ Unique x edges of the histo.

xErrs
(self, foci=False, asgrid=False)¶ All x errors of the histo.

xFoci
(self, asgrid=False)¶ All x bin foci of the histo.

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

xMaxs
(self, unique=True, asgrid=False)¶ Unique/all x high edges of the histo.

xMean
(self, includeoverflows=True)¶ ([bool]) > float Mean x of the histogram, optionally excluding the overflows.

xMids
(self, unique=True, asgrid=False)¶ Unique/all x bin midpoints of the histo.

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

xMins
(self, unique=True, asgrid=False)¶ Unique/all x low edges 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.

xVals
(self, foci=False, asgrid=False)¶ All x values of the histo.

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.

yEdges
(self)¶ Unique y edges of the histo.

yErrs
(self, foci=False, asgrid=False)¶ All y errors of the histo.

yFoci
(self, asgrid=False)¶ All y bin foci of the histo.

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

yMaxs
(self, unique=True, asgrid=False)¶ Unique/all y high edges of the histo.

yMean
(self, includeoverflows=True)¶ ([bool]) > float Mean y of the histogram, optionally excluding the overflows.

yMids
(self, unique=True, asgrid=False)¶ Unique/all y bin midpoints of the histo.

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

yMins
(self, unique=True, asgrid=False)¶ Unique/all y low edges 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.

yVals
(self, foci=False, asgrid=False)¶ All y values of the histo.

yVariance
(self, includeoverflows=True)¶ ([bool]) > float Variance in y of the histogram, optionally excluding the overflows.

zErrs
(self, sd=False, asgrid=False)¶

zMax
(self, sd=False)¶ Highest z value.

zMaxs
(self, sd=False, asgrid=False)¶

zMeans
(self, asgrid=False)¶ All y heights of the histo.

zMin
(self, sd=False)¶ Lowest z value.

zMins
(self, sd=False, asgrid=False)¶

zStdDevs
(self, asgrid=False)¶ All standard deviations on the z means.

zStdErrs
(self, asgrid=False)¶ All standard errors on the z means.

zVals
(self, asgrid=False)¶

class
yoda.core.
ProfileBin1D
(double a, double b)¶ A 1D profile bin, as stored inside Profile1D.
Only one constructor:
 ProfileBin1D(xlow, xhigh)

mean
(self)¶ The mean of the yvalues that have filled the bin.

rms
(self)¶ The RMS of the yvalues that have filled the bin.

stdDev
(self)¶ The standard deviation of the yvalues that have filled the bin.

stdErr
(self)¶ The standard error of the yvalues that have filled the bin.

sumWY
(self)¶ sum(weights * ys)

sumWY2
(self)¶ sum(weights * ys * ys)

variance
(self)¶ The variance of the yvalues that have filled the bin.

class
yoda.core.
ProfileBin2D
(xlow, xhigh, ylow, yhigh)¶ 
mean
(self)¶

rms
(self)¶

stdDev
(self)¶

stdErr
(self)¶

sumWZ
(self)¶

sumWZ2
(self)¶

variance
(self)¶


yoda.core.
S1D
¶ alias of
yoda.core.Scatter1D

yoda.core.
S2D
¶ alias of
yoda.core.Scatter2D

yoda.core.
S3D
¶ alias of
yoda.core.Scatter3D

class
yoda.core.
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!

addPoint
(self, *args, **kwargs)¶ Add a new point.
Provide either a single yoda.Point1D object, or the two args: x, xerrs=0.

addPoints
(self, iterable)¶ Add several new points.

clone
(self)¶ () > Scatter1D. Clone this Scatter1D.

combineWith
(self, others)¶ Try to add points from other Scatter1Ds into this one.

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

numPoints
(self)¶ () > int Number of points in this scatter.

point
(self, size_t i)¶ Access the i’th point.

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

reset
(self)¶ Reset the scatter, removing all points

rmPoint
(self, idx)¶

rmPoints
(self, idxs)¶

scale
(self, i, scale)¶ (int, float) > None Scale values on axis i

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.

variations
(self)¶ None > vector[string] Get the list of variations stored in the poins of the Scatter

xMax
(self)¶ Highest x value.

xMaxs
(self)¶ All x high values.

xMin
(self)¶ Lowest x value.

xMins
(self)¶ All x low values.

xVals
(self)¶

class
yoda.core.
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!

addPoint
(self, *args, **kwargs)¶ Add a new point.
Provide either a single yoda.Point2D object, or the four args: x, y, xerrs=0, yerrs=0.

addPoints
(self, iterable)¶ Add several new points.

clone
(self)¶ () > Scatter2D. Clone this Scatter2D.

combineWith
(self, others)¶ Try to add points from other Scatter2Ds into this one.

correlationMatrix
(self)¶  covMatrix numpy matrix
 Convert a covariance matrix to a correlation matrix (ie normalise entry in i,j by uncertainty of bin i * uncertainty in bin j)

covarianceMatrix
(self, *ignoreOffDiagonalTerms)¶ bool > vector[vector[float]] Construct the covariance matrix

hasValidErrorBreakdown
(self)¶ Check if the AO’s error breakdown is not empty and has no bins withh 0 uncertainty

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

numPoints
(self)¶ () > int Number of points in this scatter.

parseVariations
(self)¶ None > None Parse the YAML which contains the variations stored in the points of the Scatter. Only needs to be done once!

point
(self, size_t i)¶ Access the i’th point.

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

reset
(self)¶ Reset the scatter, removing all points

rmPoint
(self, idx)¶

rmPoints
(self, idxs)¶

scale
(self, i, scale)¶ (int, float) > None Scale values on axis i

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.

variations
(self)¶ None > vector[string] Get the list of variations stored in the points of the Scatter

xErrAvgs
(self)¶ All x average errors

xErrs
(self)¶ All x error pairs

xMax
(self)¶ Highest x value.

xMaxs
(self)¶ All x high values.

xMin
(self)¶ Lowest x value.

xMins
(self)¶ All x low values.

xVals
(self)¶

yErrAvgs
(self)¶ All y average errors

yErrs
(self)¶ All y error pairs

yMax
(self)¶ Highest y value.

yMaxs
(self)¶ All y high values.

yMin
(self)¶ Lowest x value.

yMins
(self)¶ All y low values.

yVals
(self)¶

class
yoda.core.
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!

addPoint
(self, *args, **kwargs)¶ Add a new point.
Provide either a single yoda.Point3D object, or the 36 args: x, y, z, xerrs=0, yerrs=0, zerrs=0.

addPoints
(self, iterable)¶ Add several new points.

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
(self)¶ () > int Number of points in this scatter.

point
(self, size_t i)¶ Access the i’th point.

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

reset
(self)¶ Reset the scatter, removing all points

rmPoint
(self, idx)¶

rmPoints
(self, idxs)¶

scale
(self, i, scale)¶ (int, float) > None Scale values on axis i

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.

variations
(self)¶ None > vector[string] Get the list of variations stored in the points of the Scatter

xErrs
(self)¶ All x errors

xMax
(self)¶ Highest x value.

xMaxs
(self)¶ All x high values.

xMin
(self)¶ Lowest x value.

xMins
(self)¶ All x low values.

xVals
(self)¶

yErrs
(self)¶ All y errors

yMax
(self)¶ Highest y value.

yMaxs
(self)¶ All x high values.

yMin
(self)¶ Lowest x value.

yMins
(self)¶ All x low values.

yVals
(self)¶

zErrs
(self)¶ All z errors

zMax
(self)¶ Highest z value.

zMaxs
(self)¶ All z high values.

zMin
(self)¶ Lowest z value.

zMins
(self)¶ All z low values.

zVals
(self)¶

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, xmin, xmax)¶ (int, float, float) > list[float] Make a list of n+1 bin edges linearly spaced between xmin and xmax, with the first and last edges on those boundaries.

yoda.core.
logspace
(nbins, xmin, xmax)¶ (int, float, float) > list[float] Make a list of n+1 bin edges linearly spaced on the interval log(xmin..xmax), 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.
mkIndexYODA
(filename)¶ Generate Index object for the provided YODAformat file.

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?

yoda.core.
pdfspace
(nbins, xmin, xmax, fn, nsample=10000)¶ (int, float, float, [int]) > list[float] Make a list of n+1 bin edges spaced with density proportional to fn(x) between xmin and xmax, with the first and last edges on those boundaries.
The density is manually integrated by the Trapezium Rule, using nsample linspace points.
Note: manually implemented in Python here rather than mapping the C++ version, since that requires some awkward Cython shim work: https://stackoverflow.com/questions/39044063/passaclosurefromcythontoc https://github.com/cython/cython/tree/master/Demos/callback

yoda.core.
read
(filename, asdict=True, patterns=None, unpatterns=None)¶ Read data objects from the provided filename, autodetermining 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.

yoda.core.
readAIDA
(filename, asdict=True, patterns=None, unpatterns=None)¶ Read data objects from the provided AIDAformat 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.

yoda.core.
readFLAT
(filename, asdict=True, patterns=None, unpatterns=None)¶ Read data objects from the provided FLATformat 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.
readYODA
(file_or_filename, asdict=True, patterns=None, unpatterns=None)¶ Read data objects from the provided YODAformat 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, autodetermining 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.