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.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
yoda-config
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.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
    aos = yoda.read("foo.yoda")
    print aos
    => {'/foo': <Histo1D '/foo' 20 bins, sumw=1e+03, xmean=4.84e-01>}
    
    ## Reading to a list
    aos = yoda.read("foo.yoda", asdict=False)
    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
    => ...
    
  • 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: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.

Plotting utilities, particularly for interaction with matplotlib and Rivet make-plots

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

One-liner matplotlib (mpl) setup.

By default mpl will be configured with its native MathText 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 ‘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 lower-case/text/old-style numerals and use ‘upper-case’ 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.mk_lowcase_dict(d)[source]

Convert the keys of a str->obj dict to lower-case

yoda.plotting.mplinit(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 its native MathText 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 ‘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 lower-case/text/old-style numerals and use ‘upper-case’ 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 Ncpu-1 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 non-null.

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 non-null.

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 non-null.

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

One-liner matplotlib (mpl) setup.

By default mpl will be configured with its native MathText 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 ‘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 lower-case/text/old-style numerals and use ‘upper-case’ numerals everywhere. These options do not currently apply to the MPL rendering engine.

yoda.plotting.show()[source]

Convenience call to matplotlib.pyplot.show()

NOTE: done this way to avoid import of pyplot before mplinit() or mpl.use() has been (optionally) called.

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

yoda.core.AO

alias of yoda.core.AnalysisObject

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, 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 weights-times-x: sum(weights * x)

sumWX2(self)

The sum of weights-times-x-squared: 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 x-values that have filled the bin.

xMid(self)

The midpoint of the bin.

xMin(self)

The lower bin edge.

xRMS(self)

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

xStdDev(self)

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

xStdErr(self)

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

xVariance(self)

The variance of the x-values 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 weights-times-x: sum(weights * x)

sumWX2(self)

The sum of weights-times-x-squared: 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 x-values that have filled the bin.

xMid(self)

The midpoint of the bin.

xMin(self)

The lower bin edge.

xRMS(self)

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

xStdDev(self)

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

xStdErr(self)

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

xVariance(self)

The variance of the x-values 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 x-y 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 y-dimensions

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 y-dimensions.

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 x-y 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 y-dimensions

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 y-dimensions.

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 zero-dimensional ‘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, 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.
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 x-axis 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, 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.
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/d21-x01-y01”: 5, “/RAW/ATLAS_2017_I1514251/d33-x01-y01”: 16

}, “Scatter2D”: {

“/ATLAS_2017_I1514251/d09-x01-y01”: 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 x-axis 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 y-axis 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 z-axis 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, 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.
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 x-axis (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 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.

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, 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.

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

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 y-values that have filled the bin.

rms(self)

The RMS of the y-values that have filled the bin.

stdDev(self)

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

stdErr(self)

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

sumWY(self)

sum(weights * ys)

sumWY2(self)

sum(weights * ys * ys)

variance(self)

The variance of the y-values 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 3-6 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 YODA-format 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/pass-a-closure-from-cython-to-c 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, 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.

yoda.core.readAIDA(filename, asdict=True, patterns=None, unpatterns=None)

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.

yoda.core.readFLAT(filename, asdict=True, patterns=None, unpatterns=None)

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.

yoda.core.readYODA(file_or_filename, asdict=True, patterns=None, unpatterns=None)

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.

Indices and tables