API Documentation

plot_stack(; backgrounds, signals=[], data=[], options...)

Create HEP-style stacked plot with Data/MC ratio in the bottom panel.

Input arguments, backgrounds, signals, and data, are Arrays of FHist.jl's Hist1D.

See default_options for complete list of options.

Example usage:

plot_stack(
           backgrounds=[h1, h2, h3, h4, h5, h6],
           data=[data],
           signals=[signal], # TODO Not supported yet
           xaxistitle = "Δϕ<sub>jj</sub> [GeV]",
           outputname = "plot.pdf",
           backgroundlabels = ["tt̄", "Higgs", "Drell-Yan", "tt̄Z", "ZZ", "VBS WW"],
           signallabels = ["VVH"],
          )

default_options = Dict{Symbol, Any}

Default options of all the togglable options are documented here.

Output file name

:outputname => "plot.pdf", # or "plot.{pdf,png}" or "". TODO create output dir if not exist

Axes and labeling

:ratiotitle => "Data/MC"
:xaxistitle => "variable [unit]"
:yaxistitle => "Events"

:ratiotitlesize => 29

Axes scale and ranges

:yrange => []
:xrange => []
:ratiorange => [0, 2]
:yminclipnegative => true, # Clip minimum at 0
:ymaxscale => 1.8 # Multiplicative factor to ymax points across all histograms
:ylog => false

Legend labels

:backgroundlabels => []
:signallabels => []
:datalabels => ["Data"]

Histogram colors

:datacolors => ["black", "red", "blue", "orange", "green", "purple", "gray"]
:backgroundcolors => [4020, 4023, 4021, 4024, 2001, 6004, ... , (many more)]
:signalcolors => repeat([8001, 8002, 8003, 8004],10)
:stackedsignalopacity => 0.6 # Set the opacity of stacked signal fill

Color indexs are defined in https://github.com/sgnoohc/PlotlyJSWrapper.jl/blob/main/src/colors.jl.

LHC Experiment related labels

# Currently only "CMS" label implemented
:addcmsextralabel => true # To add extra label
:cmsextralabeltext => "Preliminary" # Label to be added next to "CMS"
:showbeaminfo => true # Show lumi and energy
:lumivalue => 137
:comenergy => 13

Extra labels settings

:totalsystlabel => ["+1σ", "-1σ"]

Extra operations

:dofit => false # Scales all background such that integral is same as `data[1]` histogram
:stacksignals => false # Stacks signals on top of total background
:showsignalsinratio => false # Show signals above unity line in ratio panel
:hideratio => false # Hide the ratio panel below
:poissonerror => false # Make the data error poisson
:showtotal => true # Show total background line
:showtotallegend => true # Show total background line legend item

# To provide a custom poisson error treatment lambda
# Must be of the form where a count `x` is provided and mapped to `[upper, lower]` error
# e.g.  x -> [sqrt(x+0.25)+0.5, sqrt(x+0.25)-0.5]
# default option is set to `nothing` and when not provided the above lambda will be used
:poissonerrorfunc => nothing

Significance (or other figure of merit) scans

# Define the "figure of merit"
# Following are available:
# ("soverb" | "soversqrtb" | "soversqrtsplusb" | "llsignif" | "custom")
:fom => "soversqrtb" # Default figure of merit is S/√B

# if :fom => "custom" then, a custom anonymous function (lambda) must be provided
# The lambda must be of x->something format where `x` is assumed to be a struct of the following
#   struct BinInfo
#       s::Float64   # signal yield
#       se::Float64  # signal yield error
#       b::Float64   # totalbkg yield
#       be::Float64  # totalbkg yield error
#       d::Float64   # data yield
#       de::Float64  # data yield error (i.e. sqrt(N))
#       ibin::Int64  # bin index
#   end
# Below is an example of how one might provide a custom function
# e.g. User wants a custom fom defining s/sqrt(s+b+berror^2+(0.15*b)^2) (to mimic 15% systematics)
#      then a following lambda must be provided:
#
#          :customfom => x -> x.s / sqrt(x.b + x.be^2 + (0.15*x.b)^2)
#
# N.B. only the first element of provided `data` histogram array can be used
#
# The default value of the option when not being used is set to
:customfom => nothing

# Three options: compute fom per bin or scan from left or right
:showfomperbin => false # Show figure of merit (fom) per bin
:showfomfromleft => false # Show fom cumulatively cut from left
:showfomfromright => false # Show fom cumulatively cut from right