Module reference¶
Universal HEP plot defines a universal interchange format of plots used in high-energy contexts.
- class uhepp.Graph(x_values, y_values, graphtype='points', label=None, **style)¶
Representation of arbitrary graph lines or points
The styles can be set or retrieved via properties. While setting an attribute, values are converted to the internal format, i.e. color names are converted to hex. If a style is not set, the corresponding attribute returns None.
The complete set of styles can be retrieved via the style attribute. Unset attributes do not appear in the dict.
- Possible styles are:
linewidth (float)
linestyle (– or - or -, or :)
color (matplotlib compliant)
makersize
marker
Any legal matplotlib color might be used to set color attributes, although the uhepp standard only allows hex string. Internally, all colors are converted to hex strings.
- property graphtype¶
Type of the graph
- to_data()¶
Return the graph object as python native dicts and lists
- property x_errors¶
Return a copy of the x errors
- property x_values¶
Return a copy of the x values
- property y_errors¶
Return a copy of the y errors
- property y_values¶
Return a copy of the y values
- class uhepp.HLine(pos, stretch=None, **style)¶
Horizontal line
- property pos_y¶
The position on the y-axis of the line
- to_data()¶
Return a uhepp compatible dict/list version
- class uhepp.Line(pos, stretch=None, **style)¶
Representation of vertical or horizontal lines
The styles can be set or retrieved via properties. While setting an attribute, values are converted to the internal format, i.e. color names are converted to hex. If a style is not set, the corresponding attribute returns None.
The complete set of styles can be retrieved via the style attribute. Unset attributes do not appear in the dict.
- Possible styles are:
linewidth (float)
linestyle (– or - or -, or :)
color (matplotlib compliant)
edgecolor (matplotlib compliant)
Any legal matplotlib color might be used to set color attributes, although the uhepp standard only allows hex string. Internally, all colors are converted to hex strings.
- class uhepp.PushReceipt(api_url, ui_url, uuid)¶
A PushReceipt stores the confirmation that a plot has been uploaded to a central server. The object also contains the human-readable web endpoint at the central server.
- class uhepp.RatioItem(numerator, denominator=None, bartype='step', error='stat', den_error=None, **style)¶
Representation of an item drawn in the ratio plot
The RatioItem object stores a list of yield names for the numerator and the denominator. The binned sum of all referenced yields is the content of the numerator and denominator of this stack item. Additionally, each stack item object stores style options used during plotting, a bar type defining the representation (step or points) and a method to computed the uncertainty, see Stack.
The styles can be set or retrieved via properties. While setting an attribute, values are converted to the internal format, i.e. color names are converted to hex. If a style is not set, the corresponding attribute returns None.
The complete set of styles can be retrieved via the style attribute. Unset attributes do not appear in the dict.
- Possible styles are:
linewidth (float)
linestyle (– or - or -, or :)
color (matplotlib compliant)
edgecolor (matplotlib compliant)
markersize
marker
Any legal matplotlib color might be used to set color attributes, although the uhepp standard only allows hex string. Internally, all colors are converted to hex strings.
- base()¶
See Yield.base()
- stat()¶
See Yield.stat()
- syst()¶
See Yield.syst()
- to_data()¶
Return a uhepp compliant version using dict and lists
- var_down()¶
See Yield.var_down()
- var_up()¶
See Yield.var_up()
- vary()¶
See Yield.vary()
- class uhepp.Stack(content, bartype='stepfilled', error='stat')¶
Representation of a collection of stacked items of the main plot
A stack defines a collection of
StackItem
s. In each bin, the bar heights of all stack items are added and drawn vertically on top of each other to form an overall bar. The items of the stack collection are refered to as content.A stack can be of different types: “step”, “stepfilled” or “points”. The type defines the plotting type. The default bar type is “stepfilled”.
The error property defnes how the total uncertainty band if the stack is computed. Possible values are: “no”, “stat”, “syst”, “env”, “stat+syst”, “stat+env”, “syst+env” or “stat+syst+env”. Depending on the value, the uncertainty includes the statistical uncertainties of the yield objects, the total systematic uncertinaties of the yield objects, the quadratic sum of all variations of the yield objects, or combinations thereof. Combinations of different uncertainties are added in quadrature. The default error computation method is “stat”.
Content, type and error are accessible via properties.
- base()¶
See Yield.base()
- property content¶
Return list of StackItems
- stat()¶
See Yield.stat()
- syst()¶
See Yield.syst()
- to_data()¶
Return a uhepp compatible dict/list version
- var_down()¶
See Yield.var_down()
- var_up()¶
See Yield.var_up()
- vary()¶
See Yield.vary()
- class uhepp.StackItem(yield_names, label, **style)¶
Representation of an item within a stack of the main plot
The StackItem object stores a list of names referring to yield objects. The binned sum of all referenced yields is the content of this stack item. Additionally, each stack object stores a label and style options used during plotting.
The styles can be set or retrieved via properties. While setting an attribute, values are converted to the interal format, i.e. color names are converted to hex. If a style is not set, the corresponding attribute returns None.
The complete set of styles can be retrieved via the style attribute. Unset attributes do not appear in the dict.
- Possible styles are:
linewidth (float)
linestyle (– or - or -, or :)
color (matplotlib compliant)
edgecolor (matplotlib compliant)
markersize
marker
Any legal matplotlib color might be used to set color attributes, althout the uhepp standard only allows hex string. Internally, all colors are converted to hex strings.
- to_data()¶
Return a uhepp compliant version using dict and lists
- exception uhepp.UHepParseError¶
Invalid input data
- class uhepp.UHepPlotModel¶
Empty base class
- class uhepp.UHeppHist(symbol, bin_edges, stacks=None, yields=None)¶
Uhepp Histogram class
The class represents a typical stacked, HEP histogram including the style information and the raw bin contents and its uncertainty. The actual objects is composed of Stacks, RatioItems, Lines and Yield objects.
- property atlas¶
True if the plot is ATLAS-branded
- clone()¶
Return a deep copy of the histogram.
- get_base(name)¶
Return the rebinned yields for name
- get_stat(name)¶
Return the rebinned stat uncert for name
- get_syst(name)¶
Return the rebinned syst uncert for name
- push(collection_id, api_url=None, api_key=None)¶
Upload the plot object to a central server
- render(filename=None)¶
Render the universal plot.
The methods return the axes objecft. If the optional argument filename is set, the plot is written to the file.
- show()¶
Render the plot and show it
- to_data()¶
Convert to uhepp compliant dicts and lists
- to_json(filename)¶
Convert the hist to a json-encoded file
- to_jsons()¶
Convert the hist to a json-encoded string
- to_yaml(filename)¶
Convert the hist to a yaml-encoded file
- to_yamls()¶
Convert the hist to a yaml-encoded string
- property version¶
The version of the uhepp specification
- class uhepp.VLine(pos, stretch=None, **style)¶
A vertical line
- property pos_x¶
The position on the x-axis of the line
- to_data()¶
Return a uhepp compatible dict/list version
- class uhepp.Yield(base, stat=None, syst=None, var_up=None, var_down=None)¶
Collection of yields and uncertainties of a single process
A yield object stores binned yields for a process including underflow and overflow bins. This means the number of bins is the number bin boundaries plus one: n - 1 + 1 (for underflow) + 1 (for overflow) = n + 1.
Additionally, the object stores the statistical uncertainty of each bin. The values stored as uncertainties correspond to the 1-sigma deviations form the central value. Optionally, the yield object can store a precomputed, overall systematic uncertainty for each bin. The central value is referred to as
base
.Besides the bin-by-bin statistical and systematic uncertainties, the yield object also provides a way to store binned systematic variations of the base histogram. Variations are identified by a string key. For each key, an up-variation and down-variation can be set as a replacement for the base values. Variations are stored as absolute yields and not as deviations from base. If a down-variation is not set, the up-variation is symmetrized such that the absolute differences to the base values are identical.
The option to store variations can be used during plotting. A total systematic uncertainty can be computed with the “env” option assuming that all variations are independent. Please note that in that case the computed uncertainties are not generally statistically independent between the bins. Alternatively, it is possible to use variations as histogram items in their own right, for example to compare the shape of a variation to nominal.
The class provides overload arithmetic operations. Yields objects can be multiplied and divided by integers and floats. Scaling a yield object will also scale the uncertainties and variations. Two yield objects can also be added, subtracted, multiplied and divided bin-wise. Statistical and systematic Uncertainties are propagated under the assumption that the two involved histograms are independent. If a variation is present in both yield objects, the varied arrays are added, subtracted, multiplied or divided. If a variation is absent in one of the yield objects, the base values are used as a fallback for the arithmetic operation.
Please note that the yields stored in a yield object are “number of events per bin”, not normalized to the bin width. Merging two adjacent bins yields a bin with the sum of the two yields. Normalizing the yield to the bin width, should happen during visualization.
The class is intended and well-suited for specific use-cases. The following is a list of limitations what this class cannot do:
A yield object does not store the bin boundaries. This means a standalone yield object, i.e. a yield object without binning information or a
UHeppHist
, does not make sense.When adding variations or using arithmetics, only the number of bins is checked not the actual binning. Mismatching bin edges lead to nonsensical results.
The class does not provide a way to construct the yield arrays. For example, use
numpy.histogram()
instead to convert an array of events to a histogram.The variations cannot store an uncertainty. This is assumed to be a secondary effect. If an uncertainty is required, assess whether taking the statistical uncertainty of the base yield instead is applicable.
The class does not store process names or style information. This is handled by a
UHeppHist
object.Asymmetric statistical and systematic uncertainties are not supported. The up- and down-variations, however, might be asymmetric.
Except for adding variations,
Yield
objects are considered to be immutable.
- add_var(var_name, var_up=None, var_down=None)¶
Add a new variation or set yield of an existing variation
If var_up (or var_down) is None, the var_up (or var_down) dict is left untouched. If a variation exists, it is overwritten.
- property base¶
List of base yields of the process including under- and overflow
- iter_vars()¶
Return an iterator for the tuples of (name, up, down)
- rebin(orig_edges, new_edges)¶
Return a rebinned version of the yield object
Merged bins are added for the base yield and variation yields. The statistical and systematic uncertainties of merged bins are added in quadrature. This is only correct, if the statistical and systematic uncertainty is not correlated between bins.
- property stat¶
Return the binned absolute, statistical uncertainty of the process
- sum()¶
Return the sum of all base bins
- property syst¶
Return the binned precomputed systematic uncertainty of the process
- to_data()¶
Return a uhepp compatible dict/list version
- total()¶
Return the total sum of yields of all bins for base and variations
- var_down(var_name)¶
Return the binned, down-varied yield for the given variation
If the variation is present in the down dict, return that variation. If the variation is only present in the up dict, compute and return the up variation as a symmetrized variation. If the variation is not present in neither dict, return base.
- property var_down_names¶
List of variation names present as down variation
- var_up(var_name)¶
Return the binned, up-varied yield for the given variation
If the variation is present in the up dict, return that variation. If the variation is only present in the down dict, compute and return the down variation as a symmetrized variation. If the variation is not present in neither dict, return base.
- property var_up_names¶
List of variation names present as up variation
- property variations¶
List of variation names present as up and/or down variation
- vary(**variations)¶
Returns the yield given a dict of variation pulls.
The keyword arguments must be of the form variation_name=pull_value. The pull_value defines the direction and amount of a variation. If pull_value is 1, the var_up yields are used, if pull_value is -1, the var_down yields are used, if the pull_value is 0 (default for not listed variations) the base yields are used.
For any other value, the method interpolates between the variations.
A variation passed to the method which is not found in var_down nor var_up is not an error. It will not effect the return value.
- uhepp.from_caf(sample_folder, path, cut_stage, variable, include_bins=False)¶
Create and return a Yield object from a histogram in CAF.
The base yield and statistical uncertainty are copied from the TH1F returned by the sample folder.
Under and overflow bins are considered.
If the include_overflow argument is True, the return value is a tuple of yield object and bin edges.
The from_th1() method does not provide a method to set the total systematic uncertainty or variations.
- uhepp.from_data(data)¶
Build and return a UHepPlot from uhepp compliant dicts and lists
- uhepp.from_json(filename)¶
Build and return a UHepPlot from a uhepp compliant json file
- uhepp.from_jsons(json_string)¶
Build and return a UHepPlot from a uhepp compliant json string
- uhepp.from_th1(base_th1, var_up=None, var_down=None, include_bins=False)¶
Create and return a Yield object from a ROOT TH1 object
The base yield and statistical uncertainty are copied from a TH1 object given as first object. Optionally, var_up and var_down dicts with variation name and TH1 mapping are used to extract he variation yield.
Under and overflow bins are considered.
If the include_overflow argument is True, the return value is a tuple of yield object and bin edges.
The from_th1() method does not provide a method to set the total systematic uncertainty.
- uhepp.from_yaml(filename)¶
Build and return a UHepPlot from a uhepp compliant yaml file
- uhepp.from_yamls(yaml_string)¶
Build and return a UHepPlot from a uhepp compliant yaml string
- uhepp.pull(uuid, api_url=None, api_key=None, full_link=None)¶
Retrieve a
UHepPlot
from a central server
- uhepp.pull_collection(collection_id, api_url=None, api_key=None)¶
Retrieve a collection of UHepPlot from a central server
- uhepp.to_python(data)¶
Convert the data to pure python list and numbers