Complex Plotting the Fun Way¶
The basic philosophy of rootplot (stolen from matplotlib) is to make easy things easy and hard things possible. In our case, this means taking away the tedious process of writing a custom macro every time you want to visualize your ROOT histograms. Wouldn’t it be easier if you could call a command that would do the tedious work for you and handle in a simple way all of the most common manipulations that physicists want to make?
Of course it would!
- rootplot is ...
- ...a way to rapidly visualize your data and try out different layouts
- You can make a webpage containing images of all your histograms by a quick call to rootplot histograms.root, area-normalize them by adding the -n option, and change the title with --title="My Fancy Title".
- ...the starting point for your perfect plot
- You can control most aspects of your plots directly from the command-line, but when you decide you need to add a fit to the data and overlay pictures of rainbows and unicorns, rootplot can output a python script or a ROOT .C macro to give you a jumpstart on your masterpiece.
- ...a tool that meets you where you are
- Although rootplot is a pure-python module, no familiarity with python or pyROOT is necessary. You can work completely from the command-line, utilize the python API, or export .C macros.
The application is also a great way to test out the formidable plotting capabilities of matplotlib. For that job, you’ll need mod:rootplot‘s more elegant twin, rootplotmpl, which shares the same interface, but produces output in matplotlib through use of the root2matplotlib library.
A full list of available options for ROOT output can be accessed by calling rootplot -h:
[?1034hUsage: rootplot [config.py] targets [options]
Targets may be either multiple root files to compare or a single root file
followed by multiple histograms or folders to compare. For example:
rootplot fileA.root fileB.root fileC.root
rootplot file.root dirA dirB dirC
rootplot file.root dirA/hist1 dirA/hist2
Full documentation is available at:
http://packages.python.org/rootplot/
Options:
--version show program's version number and exit
-h, --help show this help message and exit
Control the overall behavior of rootplot:
--config do nothing but write a template configuration file
called rootplot_config.py
--debug turn off error-catching to more easily identify errors
--path='.*' only process plot(s) matching this regular expression
--processors=4 the number of parallel plotting processes to create
Control the output format:
-e png, --ext=png choose an output extension
--merge sets --ext=pdf and creates a merged file containing
all plots
--noclean skips destroying the output directory before drawing
--output=plots name of output directory
--numbering print page numbers on images and prepend them to file
names; numbering will respect the order of objects in
the ROOT file
--size=700x500 set the canvas size to 'width x height' in pixels
Manipulate your histograms:
-n, --area-normalize
area-normalize the histograms
--scale=VAL normalize all histograms by VAL, or by individual
values if VAL is a comma-separated list
--normalize=NUM normalize to the NUMth target (starting with 1)
--norm-range=LOWxHIGH
only use the specified data range in determining the
normalization
--rebin=N group together bins in sets of N
--ratio=NUM divide histograms by the NUMth target (starting from
1)
--ratio-split=NUM same as --ratio, but split the figure in two,
displaying the normal figure on top and the ratio on
the bottom
--efficiency=NUM same as --ratio, but with errors computed by the
Wilson score interval
--efficiency-split=NUM
same as --ratio-split, but with errors computed by the
Wilson score interval
Fine-tune your style:
--draw='p H' argument to pass to ROOT's Draw command; try 'e' for
errorbars, or 'hist' to make sure no errorbars appear
--draw2D=box argument to pass to TH2::Draw (ignored if multiple
targets specified); set to "" to turn off 2D drawing
-f, --fill Histograms will have a color fill
--stack stack histograms
-m, --markers add markers to histograms
--xerr show width of bins
--data=NUM treat the NUMth target (starting from 1) specially,
drawing it as black datapoints; to achieve a classic
data vs. MC plot, try this along with --stack and
--fill
--xmax=XMAX set the maximum value of the x-axis
--xmin=XMIN set the minimum value of the x-axis
--ymax=YMAX set the maximum value of the y-axis
--ymin=YMIN set the minimum value of the y-axis
--zmax=ZMAX set the maximum value of the z-axis
--zmin=ZMIN set the minimum value of the z-axis
--legend-location='upper right'
Place legend in LOC, according to matplotlib location
codes; try 'lower left' or 'center'; to turn off, set
to 'None'
--legend-entries=''
A comma-separated string giving the labels to appear
in the legend
--title=TITLE replace the plot titles, or append to them by
preceeding with a '+'
--xlabel=XLABEL replace the x-axis labels, or append to them by
preceeding with a '+'
--ylabel=YLABEL replace the y-axis labels, or append to them by
preceeding with a '+'
--grid toggle the grid on or off for both axes
--gridx toggle the grid on or off for the x axis
--gridy toggle the grid on or off for the y axis
--logx force log scale for x axis
--logy force log scale for y axis
--overflow display overflow content in the highest bin
--underflow display underflow content in the lowest bin
And the list of options for output with matplotlib can be accessed by calling rootplotmpl -h:
[?1034hUsage: rootplotmpl [config.py] targets [options]
Targets may be either multiple root files to compare or a single root file
followed by multiple histograms or folders to compare. For example:
rootplotmpl fileA.root fileB.root fileC.root
rootplotmpl file.root dirA dirB dirC
rootplotmpl file.root dirA/hist1 dirA/hist2
Full documentation is available at:
http://packages.python.org/rootplot/
Options:
--version show program's version number and exit
-h, --help show this help message and exit
Control the overall behavior of rootplot:
--config do nothing but write a template configuration file
called rootplot_config.py
--debug turn off error-catching to more easily identify errors
--path='.*' only process plot(s) matching this regular expression
--processors=4 the number of parallel plotting processes to create
Control the output format:
-e png, --ext=png choose an output extension
--merge sets --ext=pdf and creates a merged file containing
all plots
--noclean skips destroying the output directory before drawing
--output=plots name of output directory
--numbering print page numbers on images and prepend them to file
names; numbering will respect the order of objects in
the ROOT file
--size=8.0x6.0 set the canvas size to 'width x height' in inches
--dpi=80 set the resolution of the output files
--transparent use a transparent background
Manipulate your histograms:
-n, --area-normalize
area-normalize the histograms
--scale=VAL normalize all histograms by VAL, or by individual
values if VAL is a comma-separated list
--normalize=NUM normalize to the NUMth target (starting with 1)
--norm-range=LOWxHIGH
only use the specified data range in determining the
normalization
--rebin=N group together bins in sets of N
--ratio=NUM divide histograms by the NUMth target (starting from
1)
--ratio-split=NUM same as --ratio, but split the figure in two,
displaying the normal figure on top and the ratio on
the bottom
--efficiency=NUM same as --ratio, but with errors computed by the
Wilson score interval
--efficiency-split=NUM
same as --ratio-split, but with errors computed by the
Wilson score interval
Fine-tune your style:
--draw2D=box command to use for plotting 2D hists; (ignored if
multiple targets specified) choose from 'contour',
'col', 'colz', and 'box'
--errorbar output a matplotlib errorbar graph
--barcluster output a clustered bar graph
--barh output a horizontal clustered bar graph
--bar output a bar graph with all histograms overlaid
--hist output a matplotlib hist graph (no fill)
--histfill output a matplotlib hist graph with solid fill
--stack stack histograms
-m, --markers add markers to histograms
--xerr show width of bins
--data=NUM treat the NUMth target (starting from 1) specially,
drawing it as black datapoints; to achieve a classic
data vs. MC plot, try this along with --stack
--xmax=XMAX set the maximum value of the x-axis
--xmin=XMIN set the minimum value of the x-axis
--ymax=YMAX set the maximum value of the y-axis
--ymin=YMIN set the minimum value of the y-axis
--zmax=ZMAX set the maximum value of the z-axis
--zmin=ZMIN set the minimum value of the z-axis
--legend-location='upper right'
Place legend in LOC, according to matplotlib location
codes; try 'lower left' or 'center'; to turn off, set
to 'None'
--legend-entries=''
A comma-separated string giving the labels to appear
in the legend
--legend-ncols=1 Number of columns to use in the legend
--title=TITLE replace the plot titles, or append to them by
preceeding with a '+'
--xlabel=XLABEL replace the x-axis labels, or append to them by
preceeding with a '+'
--ylabel=YLABEL replace the y-axis labels, or append to them by
preceeding with a '+'
--grid toggle the grid on or off for both axes
--gridx toggle the grid on or off for the x axis
--gridy toggle the grid on or off for the y axis
--cmap=CMAP matplotlib colormap to use for 2D plots
--barwidth=1.0 fraction of the bin width for bars to fill
--alpha=0.5 set the opacity of fills
--logx force log scale for x axis
--logy force log scale for y axis
--overflow display overflow content in the highest bin
--underflow display underflow content in the lowest bin
The Application Programming Interface¶
An API and a CLI for quickly building complex figures.
- rootplot.core.plot(*args, **kwargs)[source]¶
call signature:
plot(file1, file2, file3, ..., target, **kwargs):
build a ROOT canvas, pulling the target histogram from each of the files.
call signature:
plotmpl(file, target1, target2, target3, ..., **kwargs):
build a ROOT canvas, pulling all target histograms from file.
With either of these signatures, the plot style is specified through kwargs, which can accept any of the options available to rootplot at the command-line.
Returns the tuple (canvas, pads, stack, hists, plotpath).
- rootplot.core.plotmpl(*args, **kwargs)[source]¶
call signature:
plotmpl(file1, file2, file3, ..., target, **kwargs):
build a matplotlib figure, pulling the target histogram from each of the files.
call signature:
plotmpl(file, target1, target2, target3, ..., **kwargs):
build a matplotlib figure, pulling all target histograms from file.
With either of these signatures, the plot style is specified through kwargs, which can accept any of the options available to rootplotmpl at the command-line.
Returns the tuple (figure, axeses, stack, hists, plotpath).
- rootplot.core.rootplot(*args, **kwargs)[source]¶
call signature:
rootplot(file1, file2, file3, ..., **kwargs):
build ROOT canvases from corresponding histograms in each of the files.
call signature:
rootplot(file, folder1, folder2, folder3, ..., **kwargs):
build ROOT canvases from corresponding histograms in each of the folders in file.
call signature:
rootplot(file, target1, target2, target3, ..., **kwargs):
build a ROOT canvas from each of the targets in file.
With any of these call signatures, images are generated in an output directory along with a script with the necessary calls to plot() to reproduce each of the canvases. The plot style is specified through kwargs, which can accept any of the options available to rootplot at the command-line.
- rootplot.core.rootplotmpl(*args, **kwargs)[source]¶
call signature:
rootplotmpl(file1, file2, file3, ..., **kwargs):
build ROOT canvases from corresponding histograms in each of the files.
call signature:
rootplotmpl(file, folder1, folder2, folder3, ..., **kwargs):
build ROOT canvases from corresponding histograms in each of the folders in file.
call signature:
rootplotmpl(file, target1, target2, target3, ..., **kwargs):
build a ROOT canvas from each of the targets in file.
With any of these call signatures, images are generated in an output directory along with a script with the necessary calls to plotmpl() to reproduce each of the canvases. The plot style is specified through kwargs, which can accept any of the options available to rootplotmpl at the command-line.
Customization of rootplot¶
Most of the style options for your output can be specified in a rootlogon.C or matplotlibrc depending on which kind of output you’d like. Documentation on this kind of configuration can be found on the websites of ROOT and matplotlib respectively.
There are, however, several style options which are specific to rootplot. These include the line colors and markers used, as well as the dictionary used for text replacement with matplotlib. If you’d like to customize these for your own use, simply make a configuration file with a .py extension and add the file to your list of arguments to rootplot. You can get a nice default with all the configurable parameters by calling:
$ rootplot --config
