M3::Plotting::PlottingManager Class Reference

The main class to be used in plotting scripts. More...

#include <Utils/Plotting/PlottingManager.h>

Collaboration diagram for M3::Plotting::PlottingManager:

Public Member Functions
	PlottingManager ()
	Construct a new PlottingManager using default plottingConfig config. More...
	PlottingManager (const std::string &PlottingConfigName)
	Construct a new PlottingManager using specified plottingConfig config. More...
void	initialise ()
	initalise this PlottingManager. More...
	~PlottingManager ()
void	parseInputs (int argc, char *const *argv)
	Parse command line arguments. More...
void	parseInputsVec (const std::vector< std::string > &argv)
	Parse vector of command line arguments. More...
void	addUserOption ()
	Describe an option you want to add to the PlottingManager which can be read in from the command line and retrieved later with getOption(). This should be done before calling parseInputs(). More...
std::string	getUserOption (const std::string &option)
	Retrieve a command line option you specified using addOption. More...
void	usage () const
	Print a usage message for the current executable. More...
void	parseFileLabels (std::string labelString, std::vector< std::string > &labelVec)
	Parse string of labels into a vector of strings. More...
void	setOutFileName (const std::string &fileName)
	Parse and set the output file name, if extension specified, check its one root supports, if not, default to pdf. More...
void	setExec (const std::string &execName)
	Internally set the name of the executable that manager is being used in. More...
template<typename T >
T	getOption (const std::string &option)
	Get a specific option from the config for this executable. More...
YAML::Node	getOption (const std::string &option) const
const StyleManager &	style () const
	Get the StyleManager contained within this PlottingManager, for doing style related things. More...
const InputManager &	input () const
	Get the InputManager contained within this PlottingManager, for doing input related things. More...
General getters
const std::string	getFileName (int i) const
const std::string	getFileLabel (int i) const
const std::string	getDrawOptions () const
const std::string	getOutputName ()
	Get the straight up output file name with no bells or whistles, just the file extension. More...
const std::string	getOutputName (const std::string &suffix)
	Get the output name but can specify a suffix to add to the name, before the file extension. More...
const std::vector< std::string >	getFileNames () const
const std::vector< std::string >	getFileLabels () const
size_t	getNFiles () const
bool	getSplitBySample () const
bool	getPlotRatios () const
bool	getDrawGrid () const

Public Attributes
const std::string	DEFAULT_TRANSLATION_CONFIG
const std::string	DEFAULT_STYLE_CONFIG
const std::string	DEFAULT_PLOTTING_CONFIG

Private Attributes
std::string	_configFileName = std::string(std::getenv("MACH3")) + "/plotting/PlottingConfig.yaml"
YAML::Node	_plottingConfig
YAML::Node	_execOptions
std::vector< std::string >	_fileNames
std::vector< std::string >	_fileLabels
std::vector< std::string >	_defaultFileLabels
std::string	_outputName = "Plot.pdf"
std::string	_extraDrawOptions = ""
bool	_splitBySample = false
bool	_plotRatios = false
bool	_drawGrid = false
std::unique_ptr< StyleManager >	_styleMan
std::unique_ptr< InputManager >	_inputMan

Detailed Description

The main class to be used in plotting scripts.

When it comes to plotting, this guys in charge, the main man, the head honcho, the big cheese. If it's a plot you need, this is the guy you call. You just call him in your scripts and let him and his goons StyleManager, and InputManager worry about the details, no questions asked. This class handles all the command line inputs and manages the other managers. Intention with this class is that you should be able to create one from your custom plotting script, then from that, be able to get all manner of inputs from the InputManager contained within, and set any style options you like from the StyleManager. Also a hopefully not too distant dream is to wrap this up in python so it is usable in .py scripts to take advantage of nice existing plotting libraries for e.g. MCMC plotting.

Author

Ewan Miller

Definition at line 36 of file PlottingManager.h.

Constructor & Destructor Documentation

PlottingManager() [1/2]

M3::Plotting::PlottingManager::PlottingManager

(

)

Construct a new PlottingManager using default plottingConfig config.

Returns

Constructed PlottingManager instance.

Definition at line 7 of file PlottingManager.cpp.

                                 {
  // set config file name
  _configFileName = DEFAULT_PLOTTING_CONFIG;
}

PlottingManager() [2/2]

M3::Plotting::PlottingManager::PlottingManager

(

const std::string &

PlottingConfigName

)

Construct a new PlottingManager using specified plottingConfig config.

Parameters

PlottingConfigName

The config file file defining executables specific options, and other minor manager related options.

Returns

Constructed PlottingManager instance.

Definition at line 13 of file PlottingManager.cpp.

                                                                    {
  // parse the config file
  _configFileName = PlottingConfigName;
}

~PlottingManager()

M3::Plotting::PlottingManager::~PlottingManager ( )

inline

Definition at line 67 of file PlottingManager.h.

                     {
    MACH3LOG_DEBUG("##### Deleting PlottingManager Instance #####");
  }

Member Function Documentation

addUserOption()

void M3::Plotting::PlottingManager::addUserOption

(

)

Describe an option you want to add to the PlottingManager which can be read in from the command line and retrieved later with getOption(). This should be done before calling parseInputs().

Todo:

Would be good to add functionality to this to allow user to add their own options.

The way I can think to do this would be have fn addUserOption() to set the options, defining the cmd line option (e.g. -x), the name of the option, and maybe some description of the option to be used in the help message

can then store these options in some map or something to be retrieved later by getUserOption()

Todo:

Implement this.

Definition at line 188 of file PlottingManager.cpp.

                                    {
}

getDrawGrid()

bool M3::Plotting::PlottingManager::getDrawGrid ( ) const

inline

Definition at line 154 of file PlottingManager.h.

{ return _drawGrid; }

getDrawOptions()

const std::string M3::Plotting::PlottingManager::getDrawOptions ( ) const

inline

Definition at line 131 of file PlottingManager.h.

{ return _extraDrawOptions; }

getFileLabel()

const std::string M3::Plotting::PlottingManager::getFileLabel ( int  i ) const

inline

Definition at line 129 of file PlottingManager.h.

{ return _fileLabels[i]; }

getFileLabels()

const std::vector<std::string> M3::Plotting::PlottingManager::getFileLabels ( ) const

inline

Definition at line 146 of file PlottingManager.h.

{ return _fileLabels; }

getFileName()

const std::string M3::Plotting::PlottingManager::getFileName ( int  i ) const

inline

Definition at line 127 of file PlottingManager.h.

{ return _fileNames[i]; }

getFileNames()

const std::vector<std::string> M3::Plotting::PlottingManager::getFileNames ( ) const

inline

Definition at line 144 of file PlottingManager.h.

{ return _fileNames; }

getNFiles()

size_t M3::Plotting::PlottingManager::getNFiles ( ) const

inline

Definition at line 148 of file PlottingManager.h.

{ return _fileNames.size(); }

getOption() [1/2]

template<typename T >

T M3::Plotting::PlottingManager::getOption ( const std::string &  option )

inline

Get a specific option from the config for this executable.

Template Parameters

T	the type of parameter expected for this option, e.g. std::string.

Parameters

option

The option that you want from the config.

Returns

The specified value for the option.

Definition at line 121 of file PlottingManager.h.

{ return _execOptions[option].as<T>(); }

getOption() [2/2]

YAML::Node M3::Plotting::PlottingManager::getOption ( const std::string &  option ) const

inline

Definition at line 122 of file PlottingManager.h.

{ return _execOptions[option]; }

getOutputName() [1/2]

const std::string M3::Plotting::PlottingManager::getOutputName ( )

inline

Get the straight up output file name with no bells or whistles, just the file extension.

Returns

The straight up output file name.

Definition at line 136 of file PlottingManager.h.

{ return _outputName; }

getOutputName() [2/2]

const std::string M3::Plotting::PlottingManager::getOutputName

(

const std::string &

suffix

)

Get the output name but can specify a suffix to add to the name, before the file extension.

Parameters

suffix

The suffix to add to the file name.

Returns

Output file name with suffix added before the extension.

Output file name, including the file extension will be returned, but with specified suffix after the name but before the extension. This is useful for e.g. saving multiple LLH scan types to separate files: can specify suffix "_PriotLLH" will return OutputName_PriorLLH.ext

Definition at line 252 of file PlottingManager.cpp.

                                                                      {
  std::filesystem::path path(_outputName);
  // ".root", ".pdf", etc.
  std::string ext = path.extension().string();
  // filename without extension
  std::string stem = path.stem().string();
 
  return stem + suffix + ext;
}

getPlotRatios()

bool M3::Plotting::PlottingManager::getPlotRatios ( ) const

inline

Definition at line 152 of file PlottingManager.h.

{ return _plotRatios; }

getSplitBySample()

bool M3::Plotting::PlottingManager::getSplitBySample ( ) const

inline

Definition at line 150 of file PlottingManager.h.

{ return _splitBySample; }

getUserOption()

std::string M3::Plotting::PlottingManager::getUserOption

(

const std::string &

option

)

Retrieve a command line option you specified using addOption.

Todo:

Implement this.

Definition at line 192 of file PlottingManager.cpp.

                                                                {
  (void) option;
  return "";
}

initialise()

void M3::Plotting::PlottingManager::initialise

(

)

initalise this PlottingManager.

• Read the plotting config file
• Instantiate a StyleManager using the style config file specified in the plotting config file, or if none was provided, using DEFAULT_STYLE_CONFIG.
• Instantiate an InputManager using the translation config file specified in the plotting config file, or if none was provided, using DEFAULT_TRANSLATION_CONFIG.
• Add all files specified in this PlottingManagers _fileNames vector to the new InputManager that was just created

  Warning

  This should always be called After parseInputs() unless you are manually specifying all input file names and config file names in your drawing application.

Todo:

should add some kind of validataConfigs() method to got through all of the specified config files and make sure that all provided options are valid and all necessary options are provided as it can be pretty annoying and difficult to identify what's going wrong when yaml just fails to find an option at runtime

Definition at line 27 of file PlottingManager.cpp.

                                 {
  _plottingConfig = M3OpenConfig(_configFileName);
 
  MACH3LOG_DEBUG("Initialising PlottingManager with plotting congif {}", _configFileName);
  // read options from the config
  YAML::Node managerOptions = _plottingConfig["ManagerOptions"];
 
  std::string translationConfig = managerOptions["translationConfig"].as<std::string>();
  if (translationConfig == "")
  {
    translationConfig = DEFAULT_TRANSLATION_CONFIG;
    MACH3LOG_DEBUG("PlottingManager: Using default translation config file name");
  }
  
  MACH3LOG_DEBUG("PlottingManager: Using translation config file: {}", translationConfig);
 
  std::string styleConfig = managerOptions["styleConfig"].as<std::string>();
  if (styleConfig == "")
  {
    styleConfig = DEFAULT_STYLE_CONFIG;
    MACH3LOG_DEBUG("PlottingManager: Using default style config file name");
  }
 
  MACH3LOG_DEBUG("PlottingManager: Using style config file: {}", styleConfig);
 
  // create the StyleManager
  _styleMan = std::make_unique<StyleManager>(styleConfig);
 
  // create the InputManager and add all the files to it
  _inputMan = std::make_unique<InputManager>(translationConfig, _fileNames);
}

input()

const InputManager& M3::Plotting::PlottingManager::input ( ) const

inline

Get the InputManager contained within this PlottingManager, for doing input related things.

Definition at line 165 of file PlottingManager.h.

{ return *_inputMan; }

parseFileLabels()

void M3::Plotting::PlottingManager::parseFileLabels	(	std::string	labelString,
		std::vector< std::string > &	labelVec
	)

Parse string of labels into a vector of strings.

Parameters

labelString	string of labels of the form "label1;label2;...".
labelVec	vector that the individual label strings will be placed into.

Definition at line 271 of file PlottingManager.cpp.

                                                                                           {
  // take in a string defining labels of the form "label1;label2;...;labelN" and parse it into a
  // vector containing the labels
 
  size_t end = labelString.find(";");
  while (end != std::string::npos)
  { // Loop until no delimiter is left in the string.
    labelVec.push_back(labelString.substr(0, end));
    labelString.erase(labelString.begin(), labelString.begin() + end + 1);
    end = labelString.find(";");
  }
  labelVec.push_back(labelString.substr(0, end));
}

parseInputs()

void M3::Plotting::PlottingManager::parseInputs	(	int	argc,
		char *const *	argv
	)

Parse command line arguments.

Parameters

argc	The number of command line arguments.
argv	The arguments themselves.

Takes in c style command line arguments and parses particular general ones that are useful for a wide variety of plotting scripts.

Please also keep these options in mind and use them in your own plotting scripts.

General cmd line interface for a plotting script will look like:

./ScriptName [options] [FileName1 FileName2 FileName3 ...]
 
[options]
  -o <_outputName> name of the file to output plots to
  -l <FileLabelStr> string of labels for each file in the format Label1;Label2;... to be parsed
  by parseFileLabels(), number of labels should match exactly the number of files -c
  <PlottingConfig> specify a plotting config file to be used in place of the default one
  when initialising this manager -d <DrawOptions> extra draw options to be passed when making
  plots, see https://root.cern/doc/master/classTHistPainter.html#HP01a for examples
 
  -s where possible, will try to split plots made by sample
  -r where possible, make ratio plots comparing the different input files
  -g where possible, draw a grid on the produced plots for improved readability
 
  -h print the help message for the current executable and exit
 
unnamed options are treated as files to be processed

Todo:

make this able to return any un-parsed arguments so that user can specify their own arguments for use in their plotting scripts

Definition at line 90 of file PlottingManager.cpp.

                                                              {
  if (argc < 2)
  {
    usage();
    MACH3LOG_ERROR("no arguments were specified :(");
    throw MaCh3Exception(__FILE__, __LINE__);
  }
 
  // parse the inputs
  int c;
  while ((c = getopt(argc, argv, "o:l:d:c:srgh")) != -1)
  {
    if (c < 0)
      break;
    switch (c)
    {
    case 'o': {
      setOutFileName(optarg);
      break;
    }
    case 's': {
      _splitBySample = true;
      break;
    }
    case 'r': {
      _plotRatios = true;
      break;
    }
    case 'g': {
      _drawGrid = true;
      break;
    }
    case 'h': {
      usage();
      break;
    }
    case 'l': {
      parseFileLabels(optarg, _fileLabels);
      MACH3LOG_INFO("Specified file labels: ");
      for (std::string label : _fileLabels)
        MACH3LOG_INFO("  {}", label);
      break;
    }
    case 'c': {
      _configFileName = optarg;
      break;
    }
    case 'd': {
      _extraDrawOptions = optarg;
      break;
    }
    case '?':
    default:
    {
      MACH3LOG_ERROR("Unknown or malformed option");
      usage();
      throw MaCh3Exception(__FILE__, __LINE__);
    }
    }
  }
 
  MACH3LOG_INFO("Input files provided");
  // optind is for the extra arguments that are not parsed by the program
  for (; optind < argc; optind++)
  {
    _fileNames.push_back(argv[optind]);
    MACH3LOG_INFO(argv[optind]);
    _defaultFileLabels.push_back(argv[optind]);
  }
  
  if (_splitBySample)
    MACH3LOG_INFO("Splitting by sample");
 
  if (_plotRatios && _fileNames.size() == 0)
  {
    MACH3LOG_ERROR("you specified -r <_plotRatios> = true but didn't specify any files to compare against, was this a mistake?");
  }
 
  if (_fileLabels.size() == 0)
  {
    MACH3LOG_INFO("No file labels specified, will just use the file names");
    _fileLabels = _defaultFileLabels;
  }
 
  if ((_fileLabels.size() != 0) && (_fileLabels.size() != _fileNames.size()))
  {
    MACH3LOG_ERROR("hmmm, you gave me {} labels but {} files", _fileLabels.size(), _fileNames.size());
  }
 
  initialise();
}

parseInputsVec()

void M3::Plotting::PlottingManager::parseInputsVec ( const std::vector< std::string > &  argv )

inline

Parse vector of command line arguments.

This mainly just exists for the sake of the python binding.

Parameters

argv	The arguments to parse.

Definition at line 80 of file PlottingManager.h.

                                                               {
    std::vector<char *> charVec;
    MACH3LOG_DEBUG("Parsing Inputs :: was given vector:");
    for( const std::string &arg : argv ) 
    {
      charVec.push_back( const_cast<char *>(arg.c_str()) );
      MACH3LOG_DEBUG("  - {}", arg );
    }
    parseInputs(int(argv.size()), charVec.data());
  }

setExec()

void M3::Plotting::PlottingManager::setExec

(

const std::string &

execName

)

Internally set the name of the executable that manager is being used in.

Parameters

execName

Name of the current executable, will also need to be defined in the plotting config file.

This is used by e.g. getOption() so the PlottingManager knows where to look for the option in the plotting config file.

Definition at line 264 of file PlottingManager.cpp.

                                                       {
  MACH3LOG_DEBUG("Setting internal exec name to {}", execName);
  _execOptions = _plottingConfig[execName];
  if (_outputName == "Plot.pdf")
    setOutFileName(getOption<std::string>("defaultOutputName"));
}

setOutFileName()

void M3::Plotting::PlottingManager::setOutFileName

(

const std::string &

saveName

)

Parse and set the output file name, if extension specified, check its one root supports, if not, default to pdf.

Parameters

fileName

the name of the output file.

Will check the provided saveName for file extensions, if it is one of .pdf or .eps, then just use the provided string as the full output name. If no file extension is specified, append .pdf so plots will be saved as pdf. if some other file extension is specified, replace with .pdf as only .pdf and .eps support printing multiple plots to one file in root.

Definition at line 230 of file PlottingManager.cpp.

                                                              {
  std::filesystem::path path(saveName);
  if (!path.has_extension()) {
    path.replace_extension(".pdf");
    _outputName = path.string();
    return;
  }
 
  std::string ext = path.extension().string();
  if (ext == ".pdf" || ext == ".ps" || ext == ".eps") {
    _outputName = saveName;
    return;
  }
 
  MACH3LOG_WARN("file extension '{}' that you provided doesnt support multiple plots in one file", ext);
  MACH3LOG_WARN("should be one of .pdf, .eps .ps, will use pdf");
  _outputName = saveName + ".pdf";
}

style()

const StyleManager& M3::Plotting::PlottingManager::style ( ) const

inline

Get the StyleManager contained within this PlottingManager, for doing style related things.

Definition at line 161 of file PlottingManager.h.

{ return *_styleMan; }

usage()

void M3::Plotting::PlottingManager::usage

(

)

const

Print a usage message for the current executable.

Todo:

could add some function to allow user to specify the help message for their particular script, then auto generate what the cmd line syntax looks like based on user specified options?

Definition at line 198 of file PlottingManager.cpp.

                                  {
  MACH3LOG_INFO("========================================");
  MACH3LOG_INFO("PlottingManager usage:");
  MACH3LOG_INFO("========================================");
 
  MACH3LOG_INFO("Required:");
  MACH3LOG_INFO("  <input files>               One or more input files (positional args)");
 
  MACH3LOG_INFO("");
  MACH3LOG_INFO("Options:");
  MACH3LOG_INFO("  -o <file>                   Output file name");
  MACH3LOG_INFO("  -l <labels>                 Comma/space-separated file labels");
  MACH3LOG_INFO("  -c <config>                 Configuration file name");
  //MACH3LOG_INFO("  -d <options>                Extra draw options");
  //MACH3LOG_INFO("  -s                          Split by sample");
  //MACH3LOG_INFO("  -r                          Plot ratios (requires multiple input files)");
  MACH3LOG_INFO("  -g                          Draw grid");
  MACH3LOG_INFO("  -h                          Show this help message");
 
  MACH3LOG_INFO("");
  MACH3LOG_INFO("Examples:");
  MACH3LOG_INFO("  ./plot file1.root -f FancyName");
  MACH3LOG_INFO("========================================");
}

Member Data Documentation

_configFileName

std::string M3::Plotting::PlottingManager::_configFileName = std::string(std::getenv("MACH3")) + "/plotting/PlottingConfig.yaml"

private

Definition at line 169 of file PlottingManager.h.

_defaultFileLabels

std::vector<std::string> M3::Plotting::PlottingManager::_defaultFileLabels

private

Definition at line 178 of file PlottingManager.h.

_drawGrid

bool M3::Plotting::PlottingManager::_drawGrid = false

private

Definition at line 187 of file PlottingManager.h.

_execOptions

YAML::Node M3::Plotting::PlottingManager::_execOptions

private

Definition at line 173 of file PlottingManager.h.

_extraDrawOptions

std::string M3::Plotting::PlottingManager::_extraDrawOptions = ""

private

Definition at line 182 of file PlottingManager.h.

_fileLabels

std::vector<std::string> M3::Plotting::PlottingManager::_fileLabels

private

Definition at line 177 of file PlottingManager.h.

_fileNames

std::vector<std::string> M3::Plotting::PlottingManager::_fileNames

private

Definition at line 176 of file PlottingManager.h.

_inputMan

std::unique_ptr<InputManager> M3::Plotting::PlottingManager::_inputMan

private

Definition at line 191 of file PlottingManager.h.

_outputName

std::string M3::Plotting::PlottingManager::_outputName = "Plot.pdf"

private

Definition at line 181 of file PlottingManager.h.

_plotRatios

bool M3::Plotting::PlottingManager::_plotRatios = false

private

Definition at line 186 of file PlottingManager.h.

_plottingConfig

YAML::Node M3::Plotting::PlottingManager::_plottingConfig

private

Definition at line 171 of file PlottingManager.h.

_splitBySample

bool M3::Plotting::PlottingManager::_splitBySample = false

private

Definition at line 185 of file PlottingManager.h.

_styleMan

std::unique_ptr<StyleManager> M3::Plotting::PlottingManager::_styleMan

private

Definition at line 190 of file PlottingManager.h.

DEFAULT_PLOTTING_CONFIG

const std::string M3::Plotting::PlottingManager::DEFAULT_PLOTTING_CONFIG

Initial value:

=
      std::string(std::getenv("MACH3")) +
      "/plotting/PlottingConfig.yaml"

The default plotting config config to use when instantiating new PlottingManager objects.

Definition at line 49 of file PlottingManager.h.

DEFAULT_STYLE_CONFIG

const std::string M3::Plotting::PlottingManager::DEFAULT_STYLE_CONFIG

Initial value:

=
      std::string(std::getenv("MACH3")) +
      "/plotting/StyleConfig.yaml"

The default style config config to be used by PlottingManager instances when instantiating the StyleManager.

Definition at line 44 of file PlottingManager.h.

DEFAULT_TRANSLATION_CONFIG

const std::string M3::Plotting::PlottingManager::DEFAULT_TRANSLATION_CONFIG

Initial value:

=
      std::string(std::getenv("MACH3")) +
      "/plotting/universalTranslator.yaml"

The default translation config to be used by PlottingManager instances when instantiating the InputManager.

Definition at line 39 of file PlottingManager.h.

---

The documentation for this class was generated from the following files:

• Utils/Plotting/PlottingManager.h
• Utils/Plotting/PlottingManager.cpp