15. Plotting

Introduction

The goal with MaCh3s plotting library is to be as flexible as possible and to abstract away all of the most annoying parts about plot making like reading in the data from fitter output files and keeping track of parameter names across different fitters, while allowing the user as much freedom as possible when it comes plot style and formatting.

The plotting Library consists primarily of 3 main manager classes:

• PlottingManager - This controls the high level stuff. It deals with application level options, command line options, and holds references to the other managers. This is the main class you should interact with on the user level.
• InputManager - This deals with the details of how input files (the outputs of the fitters) should be read and stored. This should be accessed via <Plotting Manager Instance>.input().
• StyleManager - This provides some helpful utilities for creating plots. This should be accessed via <Plotting Manager Instance>.style().

Config Files

In order to achieve a high level of flexibility, MaCh3s plotting library makes heavy use of config files so that the behavior of the code can be adapted easily to individual experiments without having to totally reinvent the wheel and rewrite large amounts of boilerplate code. In line with the rest of MaCh3, the plotting library uses YAML to specify its config files. Each of the manager classes above has a corresponding config file to control its functionality. The format of these config files are detailed below.

Plotting Config

This is the highest level config file and corresponds to the behavior of the Plotting Manager. It should be used to control high level variables like where to find other config files and various options for the plotting applications. This config acts as a sort of fixed reference point for the plotting library and so it's location is semi-hardcoded using the $MACH3 environment variable. In your experiment specific MaCh3 repository which is built against this MaCh3 core repository, you should define a plotting directory which contains the config file "PlottingConfig.yaml":

{MACH3}/plotting/PlottingConfig.yaml

You can find an example of such a config in this repository here

The most important options are the ones under ManagerOptions:

ManagerOptions:
    translationConfig: "" 
    styleConfig: ""

These tell the plotting manager where to find the other config files that are needed. translationConfig tells the manager where to find the translation config and styleConfig where to find the style config. These should be paths relative to the MACH3 environment variable e.g. if your MaCh3 directory contained your configs in a subdirectory called Cool-Configs then it would look something like:

${MaCh3}/..
${MaCh3}/Cool-Configs/Cool-Translation-Config.yaml
${MaCh3}/Cool-Configs/Cool-Style-Config.yaml
${MaCh3}/..

and your config options would look like:

ManagerOptions:
    translationConfig: "Cool-Configs/Cool-Translation-Config.yaml"
    styleConfig: "Cool-Configs/Cool-Style-Config.yaml"

If the options are left blank as they are above then when running the plotting code they will default to

translationConfig: "${MACH3}/plotting/universalTranslator.yaml"
styleConfig: "${MACH3}/plotting/StyleConfig.yaml"

Additionally, this config file contains options specific to each of the applications described below. They are described in more detail in that section but the general pattern they follow is

{ApplicationName}:
    {Option1}: <value>
    {Option2}: <value>
    ...

Translation Config

Fitter Specification

Parameter Specification

Sample Specification

Style Config

This config corresponds to the behavior of the Style Manager. Here you can specify options relating to the style of your plots.

Colour Palettes

You can specify colour palettes in the same style as root as follows:

ColorPallettes: # <- Tells yaml that the following are colour palettes

  RedWhiteBlue: # <- The name of this palette
  [
      ## blue to white to red gradient, usually used for cov matrices and sigma vatiations
      [255.0], ## Number of colours
      [ 0.00, 0.25, 0.50, 0.75, 1.00 ], ## stops
      [ 0.00, 0.25, 1.00, 1.00, 0.50 ], ## Reds
      [ 0.00, 0.25, 1.00, 0.25, 0.00 ], ## greens
      [ 0.50, 1.00, 1.00, 0.25, 0.00 ], ## blues
  ]

  AnotherPalette:
  ...

Which will give you a red-white-blue palette. The palettes you specify here can then be used in your plotting scripts by referencing the name set here using, for example, <plotting manager instance>.style()->SetPalette("RedWhiteBlue")

TH1 Styles

You can define styles that can be applied to TH1s as follows:

TH1Styles:
## define custom styles for TH1 type hists

  redHatchedError:     ## <- name of the style
    MarkerColor: 632   ## marker colour 
    MarkerStyle: 7     ## marker style
    FillColor: 632     ## fill colour
    FillStyle: 3003    ## fill style
    LineColor: 632     ## line Colour
    LineStyle: 1       ## line style

Which can then be applied to a TH1 using <Plotting Manager Instance>.style()->setTH1Style(/*TH1*/ <histogram>, /*std::string*/ <Style Name>) which will apply the style defined under <Style Name> to the TH1 .

Pretty Names

You can define fancy names to use in place of the parameter and sample tags defined in the translation config. You can even use latex here for added fanciness. This should look something like:

    ## first nice names for parameters
    parameters:

        XSEC_PAR_1: "{#phi}ancy xsec parameter: 1"
        XSEC_PAR_2: "{#phi}ancy xsec parameter: 2"
        XSEC_PAR_3: "{#phi}ancy xsec parameter: 3"

        DETSYST_PAR_1: "{#Delta}etector systematic 1"
        DETSYST_PAR_2: "{#Delta}etector systematic 2"
        
        FLUX_PAR_1: "{#Phi}_1"
        FLUX_PAR_2: "{#Phi}_2"
        
        OSC_PAR_1: "{#Delta}m^2_{23}"
        OSC_PAR_2: "{#delta}_{CP}"
        OSC_PAR_3: "{#theta}_{14}"

    ## now same for samples
    samples:
        
        SAMPLE_1: "sample 1"
        SAMPLE_2: "sample 2"
        SAMPLE_3: "sample 3"

Apps

PlotLLH

GetPostFitParamPlots