VINCIA ROOT Interface

  1. Linking
  2. How to Create Runtime Displays
  3. Updating and Saving Displays (in realtime)
  4. Saving Histograms to .dat files
  5. Example Programs

The VINCIA package includes a few add-on tools that rely on ROOT. These can be used in any program, independently of VINCIA, though we note that they make use of the PYTHIA 8 settings database to store parameters. As such, PYTHIA 8 must be linked and initialised (though not necessarily used). In addition, the VINCIA ROOT libraries must be linked, and the VinciaRoot.h header included. The VINCIA Makefile includes a dedicated make target, make vinciaroot, which will compile just the VINCIAROOT libraries independently of the rest of VINCIA.

These tools are mainly intended as an aid to visualise event generation during running, by allowing the user to create runtime display(s) of ROOT histograms that can be updated in realtime during the event generation process. (Helpful, e.g., to quickly check whether the generated events look as expected.)

This should of course not be regarded as the only way to generate ROOT output from VINCIA. The user can still define his/her own histograms and ntuples as usual, and is encouraged to use the full arsenal of ROOT utilities in addition to the ones provided by VINCIA.

Note: for help on ROOT-specific issues, please consult the ROOT documentation and forums, not the VINCIA authors.

Note 2: feel free to use VINCIA's ROOT displays for your own publications, using the saveDisplay() method. We ask only that you respect the MCnet guidelines by including a reference to [GKS11] in which the VINCIA ROOT displays were first developed.

Linking

Linking to ROOT

Include the ROOT libraries and the ROOT include/ path when linking. For main programs ending with ...-root.cc (such as some of the example programs), the default Makefile shipping with VINCIA automatically looks for the ROOT libraries and include files in the location specified by the ROOTSYS environment variable. If linking still fails, try specifying the ROOTLIBDIR and ROOTINCDIR environment variables as well, to define the path to your ROOT libraries and include files, respectively. If this still fails, the Makefile has been written so that it should hopefully be easy for you to fix the problem yourself with a minimum of editing, see the Makefile's section on "Linking to ROOT".

When linking to VINCIA and PYTHIA 8, note also that it is important that your ROOT libraries were compiled with the same C++ compiler version as the PYTHIA 8 (and VINCIA) libraries were, see the section on Installation & Linking. Otherwise you may get errors related to inconsistent architectures.

We recommend including at least the following ROOT libraries: -lCore -lCint -lGpad -lGraf -lHist -lMathCore -lMatrix -lRIO -lThread, with a few alternatives also provided (but commented out by default) in the VINCIA Makefile.

Including the VinciaRoot.h header file and Namespace

To use the VINCIA ROOT utilities, simply add VinciaRoot.h to the list of header files included in your main program,

The default location of the VinciaRoot.h header file is VINCIA's vinciaroot/include/ subdirectory. This is automatically included in the VINCIA Makefile, when compiling programs ending in -root.cc. For standalone compilation, add this include path explicitly to your linking. Also add the libvinciaroot.a library (again handled automatically by the VINCIA Makefile). The other VINCIA libraries do not need to be linked; the VinciaRoot.h header only relies on itself, on the ROOT libraries, and on the auxiliary header files included in VinciaRoot.h.

The VINCIA ROOT classes and functions have all been defined to live inside the Vincia namespace, so to use them in your code they must either be prefaced by Vincia::, or you can include the Vincia namespace:

Dependencies

The interface relies on (and will automatically include) the following ROOT header files:

Since these declarations are contained in VinciaRoot.h (via VRsettings.h), you should not need to include them in your main program explicitly, but the linker will of course need to be told where to find them, i.e., a ROOT include path will need to be specified. See the section on interfacing to ROOT in VINCIA's default Makefile.

Example

How to Create Runtime ROOT Displays

For compactness, VINCIA's ROOT display tool is not intended to be a full-fledged graphics package, nor does it allow access to all the ROOT plotting functionality. A few methods are provided, however, to cover the most common tasks, such as normalizing to unity, setting logarithmic axes, adding legend labels, etc.

Note: if you need more advanced plotting options, remember that your histograms are ordinary ROOT ones and can therefore be saved to a standard ROOT file for later processing/plotting. Alternatively, you can save them to a plain ASCII file using VINCIA's saveHistogram() method.

Create your own runtime ROOT displays using the following step-by-step procedure:

  1. Create an instance of the VinciaRoot object. Only one such instance should be constructed for each main program:
    • // Construct VinciaRoot object
    • VinciaRoot vroot;
    Note that this assumes you already included the relevant headers and namespace, see above.
  2. Optionally, you can set global properties that you wish to use for all displays already at this point, using the keyword "all" in any of the following methods:
    • // Set default display properties:
    • // Logarithmic Y axis
    • vroot.setLogY("all",true);
    • // Plots normalised to unity (including under/overflow)
    • vroot.setNormalize("all",true,1.0);
    • // Set default legend and MC names/versions
    • vroot.setLegend("all","Vincia");
    • vroot.setMCnames("all","Vincia 1.xxx + Pythia 8.xxx");
    • // Optionally set left/right white-on-black labels
    • vroot.setLeftLabel("all","ee");
    • vroot.setRightLabel("all","91.2 GeV");
    • // Optionally show a chi2(5%) value for each legend when comparing to data
    • vroot.setShowLegendChi2("all",true);
    • // Set ratio panes on/off (def: on)
    • vroot.setShowRatioPad("all",true);
    • // Optionally set range of ratio panes (def: 0.5 - 1.5)
    • vroot.setRatioRange("all",0.5,1.5);
    • // Optionally set size of MC stat error bars in units of sigma (def = 1.)
    • vroot.setSigmaMC("all",1.);
    • // Special flag to force MC to be rebinned like data (always true in ratio pane; this switch only affects main pane)
    • vroot.setRebinLikeData("all",true);
    • // Special flag to exclude zeroes when compute averages for rebinning
    • vroot.setZeroSkipping("all",true);
    Alternatively, you can leave the properties of any already created displays unchanged and change only the properties of any that are subsequently created by using the keyword "new" instead of "all" above. You can also change only the properties of a specific (named) display by using the name of that display. For example, if you have created a display named "Thrust" and you want to change the Y axis to a linear scale only for that display, use
    • // Set Linear Y axis for the "Thrust" display
    • vroot.setLogY("Thrust",false);
  3. Create an ordinary ROOT histogram, of the type TH1D (which is currently the only type supported by VinciaRoot), e.g.,
    • myTH1Dptr = new TH1D("Thrust","1-Thrust",100,0.,0.5);
    Optionally, you can set histogram properties by using the ordinary ROOT methods for TH1D, e.g.,
    • // Set histogram axis labels and plot range
    • myTH1Dptr->GetXaxis()->SetTitle("1-T");
    • myTH1Dptr->GetYaxis()->SetTitle("1/N dN/d(1-T)");
    • myTH1Dptr->SetMinimum(0.0005);
    • myTH1Dptr->SetMaximum(90.);

    Note that VINCIA does not read all the properties of the TH1D. The example above gives the most commonly used ones, with a few additional ones, such as custom axis labels, illustrated in the example main programs.

  4. Open a display for your histogram:
    • // Create a VinciaRoot display (name,hisPtr,x-pixels,y-pixels)
    • vroot.createDisplay("Thrust",myTH1Dptr,300,400);
    The first argument (here "Thrust") serves to identify this particular display in subsequent calls to VinciaRoot member functions (see subsequent steps). It is typecast as a string. The two last arguments give the size of the display in pixels. Any number of histograms and displays can be created by repeating steps 2-3. By default, additional displays cascade from the top left-hand corner of the screen. Optionally, if you wish a new display to appear somewhere else, two additional coordinate values can be given, specifying the desired offset (in pixels) from the top left-hand corner of your screen,
    • // Create a VinciaRoot display at specific coordinates (...,x-offset,y-offset)
    • vroot.createDisplay("Thrust",myTH1Dptr,300,400,100,20);
    It is also possible to open an empty display, in preparation for adding histograms to it later:
    • // Create an empty VinciaRoot display
    • vroot.createDisplay("Thrust",300,400);
  5. Optionally, additional histograms can be sent to the same display for (over)-plotting. If you just need to display a single histogram, skip to the next step, else read on. Add (further) histograms to an existing display by using the method:
    • // Add histogram to runtime display
    • vroot.addTH1DPtr("Thrust",myTH1Dptr);
    Currently, up to four different histograms can be added to the same display. Note that a ratio pane will automatically be added, showing the ratio of each subsequent histogram to the first one (or to data, if a file with data points is added, see below). In case you don't want to see the ratio pane, see the methods setShowRatio() and setRatioRange() below.
  6. Optionally, if you want to compare with experimental data, add a data file to the display by using the method:
    • //Add data file
    • vroot.setDataFile("Thrust","data/L3-91-Thrust-udsc.vec",10,30,40,51,52,61,62);
    The second argument specifies the file name of your data file. It is typecast as a string. It should be an ordinary ASCII file with values separated by tabs or spaces. The file may also contain text or other non-numerical lines (e.g., furnishing more details about the measurements, etc), but the lines containing the data entries must appear first in the file, as VINCIA will stop processing the file after it encounters the first non-numerical line. In the call to setDataFile(), the numerical values following the name of the data file specify the type and order of data columns in the file, column by column. The possible format specifiers are listed here:
    Left Bin Edge 10 xLeft 11 errX- 12 1-xRight 13 exp(xL) 14 10xL
    Bin Center 20 xCenter 21 xWeighted 22 1-xCenter 23 exp(x) 24 10x 25 ++iBin
    Right Bin Edge 30 xRight 31 errX+ 32 1-xLeft 33 exp(xR) 34 10xR
    Bin Content 40 y 43 y [logX] 45 k Factor 46 1/k Factor
    Stat Errors 50 errStat 51 errStat+ 52 errStat-
    Sys/Th Errors 1 (optional) 60 errSys 61 errSys+ 62 errSys-
    Sys/Th Errors 2 (optional) 70 2nd errSys 71 2nd errSys+ 72 2nd errSys-
    Total Errors (optional) 80 errTot 81 errTot+ 82 errTot-
    Merging Info (optional) 90 N 91 ... 92 ... 93 ... 94 ... 95 ...
    Generic Info (optional, read as strings, ignored by reader) 1 Experiment Name 2-9 Other string-type information
    Ignore column 0 Ignore
    This gives a large flexibility in the types of data files that can be used, without the user having to reorder content. E.g., the format given in the call to addDataFile() in the example above tells VinciaRoot that this particular data file should be interpreted as having the columns
    • xLeft xRight y errStat+ errStat- errSys+ errSys-
    By default, VINCIA then automatically adds a ratio pane below the main plot, showing Theory/Data in a +/- 50% window. Note that theory is automatically rebinned in the same way as data in the ratio plot, but to avoid rebinning artifacts it is still important to choose the binning of the theory to be at least as fine as that of the data. The ratio pane can be switched off using the method
    • vroot.setShowRatio(false);
    This change acts globally, on all displays. To switch off the ratio pane for a single display, use the display identifier as the first argument,
    • vroot.setShowRatio("Thrust",false);
    The range of the ratio plot can be changed from its default value, using the methods (globally or for a single display, respectively):
    • vroot.setRatioRange(double yMin, double yMax);
    • vroot.setRatioRange("Thrust",double yMin, double yMax);
    The name of the experiment and a reference for the analysis can also be read automatically from the data file, if it contains the following two lines
    • SRC = L3
    • REF = Phys.Rept. 399 (2004) 71
    I.e., the SRC keyword is used to give the name of the experiment (as it will appear in the plot legend) and the REF one to give the paper reference (as it will appear in the lower part of the plot, above the MC/version names).
  7. Optionally, to modify the properties of a single display without modifying the global ones set in step 1, you can use the same methods as in step 1 but inserting the display identifier as the first argument, e.g.,

    • vroot.setLogY("Thrust",true);
    • vroot.setLogX("Thrust",true);
    • vroot.setLegend("Thrust","Vincia",int align=0); // (-1:Left, 0:Auto, 1:Right)
    • vroot.setLegend("Thrust","Vincia",double xL, double xWid, double dY, double yTop);
    where the first variant of the setLegend() method uses an integer to specify the placement of the legend: -1 for left-hand placement, +1 for right-hand placement, and 0 for automatic left/right placement depending on where the data (or first MC) histogram is largest. The second variant of the setLegend() method instead uses absolute coordinates to specify the placement and size of the legend (only the first two arguments are mandatory).

    Note that some properties are so far only modifiable at the global level and cannot (yet) be changed for each individual display.

  8. Optionally, the colour palette for each graph on a plot can be set with
    • VinciaRoot::setColorScheme(string displayName, int iScheme, int iGraph=1);
    • VRdisplay::setColorScheme(int iScheme, int iGraph=1)
    So far, it is not possible to specify a complete user-defined palette (though this functionality could be added if needed). The predefined colour palettes available in VINCIAROOT were taken from the professional graphic-design literature and are constructed to produce appealing plots with maximum colour contrast under a variety of constraints. In particular, we use the colours from fig 11 in [Zeileis, Hornik and Murrell: "Escaping RGBland: Selecting Colours for Statistical Graphics." Comp. Stat. & Data Analysis 53, Issue 9 (2009) 3259-3270].
  9. Optionally, there is some (still very limited) functionality to add additional graphics content to a display. Currently, the only implemented functionality of this type is to add a line created with ROOT's TLine class. You create the line yourself and modify its properties to suit you, then send a pointer to it, to a named display (here called "Thrust") using:
    • TLine* myTLinePtr = new TLine(x1,y2,x2,y2);
    • vroot.addTLine("Thrust",myTLinePtr);
Using these steps, you should be able to open runtime displays, send ROOT histograms to them, and define associated data files. All that remains is to update them periodically during the run and/or save them to graphics and/or dat files.

Plotting Uncertainty Bands

Optionally, vectors of histograms can be used to represent uncertainty variations. This is especially convenient when using VINCIA's automatic uncertainty estimates, but can in principle also be used for making uncertainty estimates with other Monte Carlo generators. Instead of a single pointer to a TH1D, the display should then be initialised using an object of the type

The zero ("central") component of this vector will be displayed just as in the case of an ordinary TH1D*, including vertical lines showing the statistical MC uncertainty. However, if myTH1Dvec contains more than one element, VINCIA will also add a shaded box below the point, computed from a simple max and min operation on the uncertainty variations. Note that the size of the shaded box is obtained by summing the max and min variations in quadrature with the statistical MC uncertainty on the central point.

By default, VINCIA also adds a pane below the main plot showing the relative decomposition of the total variation into its components. A legend for this pane is given in the illustration here to the right, with names corresponding to VINCIA's automatic uncertainties and numbers indicating the vector index. As an aid to visualizing the many possible contributions, blue colours are used for even vector indices (generally corresponding to "High" variations in VINCIA) and red ones for odd indices (generally corresponding to "Low" variations in VINCIA), with the exception of index numbers 1, 8, and 9 which are drawn as black lines.

The y axis of the relative-uncertainty pane goes from -1 to 1. Above (below) zero, each variation greater than (smaller than) the central one is shown expressed as a fraction of the largest (smallest) variation. Thus, this pane illustrates, bin by bin, which source of uncertainty generates the largest contribution to the total. Due to unitarity, one generally sees a cross-over between reds and blues at the intersection between Sudakov- and hard-radiaton-dominated regions.

The pane showing the decomposition of the uncertainty into relative components can be switched off either locally, for a single display, or globally, using the method

Updating and Saving Displays

Updating Displays

Displays can be updated periodically during the event generation by adding a call to the bool VinciaRoot::update() method. For ordinary applications, just add a call to this method for every processed event (in which case VinciaROOT will count internally how many events have been processed so far) or it can be given an optional argument telling it how far we got, update(int iEvent). To save time, displays will not be refreshed at every call but instead with a frequency controlled by

mode  VinciaRoot:nUpdate   (default = 400; minimum = 1)
The return value of update() will be true if the displays were refreshed in this call, otherwise false.

If desired, the event number at which the displays will next be refreshed by update() can be retrieved with int VinciaRoot:nextUpdate().

Manually (forcing) an update

Note: for ordinary applications, the automated functionality described above should be sufficient. Forced updates are only intended to cover special cases where the user would want to override the automated functionality.

To force an update of a particular display during event generation, the updateDisplay(string displayName) method can be called, which, if not given an argument, updates all of the displays.

The ROOT example programs included with VINCIA give some further examples of updating, including adjusting the frequency of the updates as the run progresses.

Saving Displays to Graphics Files

Displays can be automatically saved to graphics files (see paragraph below for how to save histogram data files) as part of the call to update(). This is controlled by the parameter

flag  VinciaRoot:saveDisplays   (default = on)

Again, to save time, not every call to update() produces a new set of saved displays. The base interval between savings is controlled by the parameter

mode  VinciaRoot:nSave   (default = 2000; minimum = 1)
the displays (and/or histograms) will first be saved. Since the statistical accuracy scales with (the square root of) the number of processed events, linear intervals in nSave are only used at the beginning of a run. A transition is automatically made to the following form at the point when it produces a longer interval than the linear one:

nSave * pow(2,i/fSave) ,
with the parameter fSave controlling the frequency of saves in the asymptotic part.

parm  VinciaRoot:fSave   (default = 4; minimum = 0.5; maximum = 8)
E.g., a value fSave=1 would correspond to saving the displays each time the statistics have doubled, at which point statistical uncertainties will have been reduced by a factor sqrt(2)~1.4, while the default fSave=4 produces a save each time the statistical uncertainties are reduced by roughly 10% relative to the previous save.

When saveDisplays = on the produced file type(s) are controlled by the following flags:

flag  VinciaRoot:saveDisplays:pdf   (default = on)

flag  VinciaRoot:saveDisplays:png   (default = off)

flag  VinciaRoot:saveDisplays:gif   (default = off)

flag  VinciaRoot:saveDisplays:jpg   (default = off)

flag  VinciaRoot:saveDisplays:eps   (default = off)

flag  VinciaRoot:saveDisplays:ps   (default = off)

flag  VinciaRoot:saveDisplays:Portrait   (default = off)
Portrait mode

flag  VinciaRoot:saveDisplays:Landscape   (default = off)
Landscape mode

flag  VinciaRoot:saveDisplays:svg   (default = off)

flag  VinciaRoot:saveDisplays:xpm   (default = off)

flag  VinciaRoot:saveDisplays:xml   (default = off)

flag  VinciaRoot:saveDisplays:root   (default = off)

flag  VinciaRoot:saveDisplays:cxx   (default = off)

flag  VinciaRoot:saveDisplays:tex   (default = off)
mode.

By default, file names for the saved graphics files will be formed from the name of the saved display(s), followed by the appropriate graphics extension (so a display named "Thrust" will be saved to "Thrust.png"). User-specifiable prefixes and/or suffixes can also be provided (e.g., to distinguish plots made in different runs), via the following strings:

word  VinciaRoot:saveFilePrefix  

word  VinciaRoot:saveFileSuffix  

If desired, the event number at which the displays will next be saved by update() can be retrieved with int VinciaRoot:nextSave().

Manually (forcing) a save

Note: for ordinary applications, the automated functionality described above should be sufficient. Forced saves are only intended to cover special cases where the user would want to override the automated functionality.

To save a display during or after event generation, call the saveDisplay method,

where displayName specifies which display to save. The default name for the saved file is displayName.png. To give the file a more descriptive name, a second argument can optionally be given, which saves the display to a file named fileNameBase-displayName.png. To save the display in a different graphics format, a third argument can optionally be given, with the following values of fileType recognised by the program: eps, gif, jpg, pdf, png, ps. Note that ROOT is noot universally good at saving graphics in a visually pleasing way. Check your output files and experiment with different formats if results are not as desired. Finally, a fourth argument can be used to specify options to ROOT's save function, such as "Landscape".

Saving Histograms to .dat files

It is also possible to save your VinciaRoot histograms to simple ASCII data files, for later plotting with another program or for overplotting in a subsequent VINCIA run. This is controlled by the

flag  VinciaRoot:saveHistograms   (default = on)
Note: the intervals for when to save histogram data files are the same as those for saving graphics files, see above.

By default, the data format is that used by mcplots.cern.ch,

If you are running VINCIA with automated uncertainty bands, two additional columns will be added, representing the estimate of the theory uncertainty

The total uncertainty should be computed by adding the statistical and theory uncertainties. It is up to the user to decide whether to add them linearly or in quadrature.

Note: the theory uncertainties are computed from reweighted events, and hence have a slightly larger intrinsic statistical uncertainty than the central y values. This uncertainty is, however, still tightly correlated with the statistical uncertainty on the central result. For the time being, therefore, VINCIA does not output a separate statistical error on the theory uncertainties.

Note 2: in order to preserve total normalisations, VINCIA writes the underflow and overflow bins in the file as well, as the first and last line of the data points, respectively. They are assigned fictitious x values, displaced by one bin from the main bins, so they will not show up on plots restricted to the range of the original histogram. Feel free to edit the files to comment them out or remove them entirely, as suits your purpose, but be aware that by default, the first and last bins represent the under- and overflow bins and are assigned x values displaced from the main histogram range.

Example Programs

The following example programs are included with the VINCIA distribution and illustrate how to use the ROOT interface:

History

The snapshots below give a brief history of how the look of the VinciaRoot interface has evolved over time. Shown is the Thrust event-shape variable in e+e- collisions at 91.2 GeV.

Sep 2013
Vincia 1.101 + Pythia 8.180
May 2012
Vincia 1.028 + Pythia 8.162
Jul 2011
Vincia 1.026 + Pythia 8.150
Dec 2010
Vincia 1.023 + Pythia 8.140