TIMBER  beta
Tree Interface for Making Binned Events with RDataFrame
Functions
Plotting Tools (Plot.py)

Functions to easily plot histograms together in various configurations. More...

Functions

def CompareShapes (outfilename, year, prettyvarname, bkgs={}, signals={}, names={}, colors={}, scale=True, stackBkg=False, doSoverB=False, forceForward=False, forceBackward=False)
 Create a plot that compares the shapes of backgrounds versus signal. More...
 
def EasyPlots (name, histlist, bkglist=[], signals=[], colors=[], titles=[], logy=False, xtitle='', ytitle='', dataOff=False, datastyle='pe')
 Tool to produce plots quickly as .root, .pdf, .png, etc. More...
 
def MakeCumulative (hist, low, high, forward=True)
 Custom cumulative distribution function which has more predictable behavior than the TH1 version. More...
 
def MakePullPlot (data, bkg)
 Generates a pull plot defined as (data-bkg)/sigma where sigma is the error of data and bkg added in quadrature. More...
 
def MakeSoverB (stack_of_bkgs, signal, forceForward=False, forceBackward=False)
 Makes the SoverB distribution and returns it. More...
 
def MakeUpDown (hist)
 Creates up and down variations of a histogram based on its per-bin errors. More...
 

Detailed Description

Functions to easily plot histograms together in various configurations.

Function Documentation

◆ CompareShapes()

def TIMBER.Tools.Plot.CompareShapes (   outfilename,
  year,
  prettyvarname,
  bkgs = {},
  signals = {},
  names = {},
  colors = {},
  scale = True,
  stackBkg = False,
  doSoverB = False,
  forceForward = False,
  forceBackward = False 
)

Create a plot that compares the shapes of backgrounds versus signal.

If stackBkg, backgrounds will be stacked together and signals will be plot separately. Total background and signals are scaled to 1 if scale == True. Inputs organized as dicts so that keys can match across dicts (ex. bkgs and bkgNames). If doSoverB is True, add a sub pad with signal/sqrt(background) calculation.

Parameters
outfilename(string): Path where plot will be saved.
year(int): Year to determine luminosity value on plot. Options are 16, 17, 18, 1 (for full Run II), or 2 (for full Run II but represented as separate years, ie. 2016+2017+2018).
prettyvarname(string): What will be assigned to as the axis title.
bkgs({string:TH1}, optional): Dictionary of backgrounds to plot. Defaults to {}.
signals({string:TH1}, optional): Dictionary of signals to plot. Defaults to {}.
names({string:string}, optional): Formatted version of names for backgrounds and signals to appear in legend. Keys must match those in bkgs and signal. Defaults to {}.
colors({string:int}, optional): TColor code for backgrounds and signals to appear in plot. Keys must match those in bkgs and signal. Defaults to {}.
scale(bool, optional): If True, scales total background to unity and signals (separately) to unity. Defaults to True.
stackBkg(bool, optional): If True, backgrounds will be stacked and the total will be normalized to 1 (if scale==True). Defaults to False.
doSoverB(bool, optional): If True, add a sub pad with signal/sqrt(background) calculation. Defaults to False.
forceForward(bool, optional): If True, force define cumulative distribution from left to right. Defaults to False.
forceBackward(bool, optional): If True, force define cumulative distribution from right to left. Defaults to False.
Returns
None

◆ EasyPlots()

def TIMBER.Tools.Plot.EasyPlots (   name,
  histlist,
  bkglist = [],
  signals = [],
  colors = [],
  titles = [],
  logy = False,
  xtitle = '',
  ytitle = '',
  dataOff = False,
  datastyle = 'pe' 
)

Tool to produce plots quickly as .root, .pdf, .png, etc.

If providing TH2s, only plots the data (histlist) with no comparisons. If providing TH1s, plots together the data (histlist), total background (individual components as a stack), and signals with pulls in a lower pane. Providing multiple data histograms will plot the separate pads on a single canvas. Up to 6 pads are supported. See argument descriptions for plotting options.

histlist is just the generic list but if bkglist is specified (non-empty) then this function will stack the backgrounds and compare against histlist as if it is data. The important bit is that bkglist is a list of lists. The first index of bkglist corresponds to the index in histlist (the corresponding data). For example you could have: ```python histlist = [data1, data2] bkglist = [[bkg1_1,bkg2_1],[bkg1_2,bkg2_2]] ```

Parameters
name(str): Name of output file with extension (file type must be supported by TCanvas.Print()).
histlist([TH1 or TH2]): List of data histograms.
bkglist([[TH1]], optional): List of list of background histograms. Index of first list level matches against index of histlist. Internal list is the group of backgrounds that will be stacked together to create the total background estimate. For example you could have: histlist = [data1, data2] and bkglist = [[bkg1_1,bkg2_1],[bkg1_2,bkg2_2]]. Defaults to [].
signals([TH1], optional): List of signal histograms where index corresponds to the index of histlist. Defaults to [].
colors([int], optional): List of integers corresponding to TColor codes where the index corresponds to the index of histlist. Defaults to [].
titles([str], optional): List of titles for each histogram where the index corresponds to the index of histlist. Defaults to [] which means the input titles of histlist will be used.
logy(bool, optional): Option to plot log y-axis. Defaults to False.
xtitle(str, optional): X-axis title for all histograms on the canvas. Defaults to '' which means the input titles of histlist will be used.
ytitle(str, optional): Y-axis title for all histograms on the canvas. Defaults to '' which means the input titles of histlist will be used.
dataOff(bool, optional): If True, turns off data from being drawn in all pads. Defaults to False.
datastyle(str, optional): Style in which to draw data. Defaults to 'pe'.
Exceptions
ValueErrorIf number of requested pads is greater than 6.

◆ MakeCumulative()

def TIMBER.Tools.Plot.MakeCumulative (   hist,
  low,
  high,
  forward = True 
)

Custom cumulative distribution function which has more predictable behavior than the TH1 version.

Parameters
hist([type]): Input histogram.
low([type]): Lower bin number boundary, inclusive.
high([type]): Upper bin number boundary, exclusive.
forward(bool, optional): Integrates forward if True. Defaults to True.
Returns
TH1 Cumulative distribution of histogram with same axis as input histogram but with zero bins for those not included in [low,high) range.

◆ MakePullPlot()

def TIMBER.Tools.Plot.MakePullPlot (   data,
  bkg 
)

Generates a pull plot defined as (data-bkg)/sigma where sigma is the error of data and bkg added in quadrature.

Parameters
data(TH1): Histogram of data.
bkg(TH1): Histogram of total background.
Returns
TH1 Histogram of the pull.

◆ MakeSoverB()

def TIMBER.Tools.Plot.MakeSoverB (   stack_of_bkgs,
  signal,
  forceForward = False,
  forceBackward = False 
)

Makes the SoverB distribution and returns it.

Assumes that signal and stack_of_bkgs have same binning.

S/sqrt(B) is defined from the cumulative distribution of the histogram. In other words, S = total amount of signal kept by a cut and B = total amount of backgroud kept by a cut. So the cumulative distribution for each must be calculated and then the ratio of signal to square root of background is taken of those.

There is a question then of which direction to integrate for a distribution. For something like tau32, you want to integrate "forward" from 0 up since a signal-like tau32 cut is defined as keeping less than the cut value. For a machine learning algorithm score (like DeepCSV), one needs to integrate "backward" since the cut is defined as selecting signal-like events when keeping values greater than the cut.

The script will automatically find which of these to do and if the signal peak is not at edge of the space. If it is not at the edge, it will find the signal peak and build the cumulative distributions backwards to the left of the peak and forwards to the right of the peak.

Parameters
stack_of_bkgs(THStack): Stack of backgrounds, already normalized together, and as a sum normalized to 1.
signal(TH1): One histogram for signal. Can only calculate s/sqrt(b) one signal at a time.
forceForward(bool, optional): If True, force define cumulative distribution from left to right. Defaults to False.
forceBackward(bool, optional): If True, force define cumulative distribution from right to left. Defaults to False.
Returns
None

◆ MakeUpDown()

def TIMBER.Tools.Plot.MakeUpDown (   hist)

Creates up and down variations of a histogram based on its per-bin errors.

Parameters
hist(TH1): Histogram from which to create up/down distributions.
Returns
(TH1, TH1): Tuple of (up, down) histograms.