Tool 1 Basic Usage
This is the repository for the HCC-Swanson Project and contains all of the development documentations.After installation and environmental setup tool one can easily be ran. To see a list of all of the command line and other options simply run python HCCTool1.py or if the file has been given executable permissions HCCTool1.py.
The following are the command line options available to the tool and the values that they require. The two required arguments (input file and tree name) are listed first
-h, --help show this help message and exit
-f FILE, --file=FILE ROOT input file
-t TREENAME, --tree=TREENAME Tree to parse
-m MAXBRANCH, --firstN=MAXBRANCH Display only the first N buckets of the file on the graph
-d, --display Show interactive matplotlib display
-b, --top_level Color by only the top level branch
-o OUTPUT, --output_file=OUTPUT The name of the output file
-n TOPN, --top_n=TOPN Color Only the top N branches in the file
-e EVENTS, --eventFilter=EVENTS Plot only up to this event number or this range of events
-l, --list_trees List the available trees in file
-r BRANCHREGEX, --branch_regex=BRANCHREGEX Regular expression to filter out branches
Below each one of these inputs are described and examples are shown for each one of the flags as well as the effects of these flags in combination with one another.
A valid ROOT file is required to run the program and is specified using the -f flag in the output. If no file is specified the program will display an error message and exit.
The program only parses one tree within the root file at a time. To successfully run the program must have a tree to parse using the -t argument. If no argument is specified the program will display an error message and exit.
The program also allows the user to list all of the trees contained in a ROOT file for reference and to aid in deciding which tree to display on the graphic. This option is enabled by passing in the -l flag. If this is passed in the program will display the name of all trees in the file and exit as shown below on an example root file.
./HCCTool1.py -f example.root -l
The following trees are in the file: Metadata
ParameterSets
Parentage
Events
LuminosityBlocks
Runs
Passing in the -d option will allow an interactive matplotlib display to be shown if properly configured in your working environment.
The -o flag allows the user to specify the name of the output file. Changing the suffix of the file will allow the changing of the filetype. Any legal matplot lib file type can be saved. For further information see Matplotlib documentation
The following two figures were generated using HCCTool1 with only the example root file and the tree events passed into the program using the following argument .\HCCTool1.py -f example.root -t Events.
The program will only color the top 30 branches by size within the file and color the rest black. This is due to both a limitation of unique colors and the size of the legend that can be produced. Fewer branches can be colored using a command line option which will be discussed later. Without specifying an output file name the program will simply produce a PNG image file with the .root name removed. It will also create an additional file that contains a legend entitled filename_legend.png.
As you can see the resulting image contains a lot of data. HCCTool1 has many other flags to help reduce the amount of data presented in the graph and hopefully make a useful display from the graphics. B
Using the -m flag will graph only display the first N buckets encountered in the file. Any positive integer can be used with this flag. Below is a figure with only the first 1000 buckets plotted on the chart.
Often a user only desires to see where buckets falling under a top level branch will fall. This tool provides the option to color only the top level branches within a file by passing the -b option flag into the program.
The first images below show the results of the program ran without any additional arguments on a file that has 4 top level branches. As you can see the program identified many more branches and the 30 branch limit for coloring is exceeded. When the -b option is passed on the 4 top level branches are colored as shown below.
Using the -n arg flag makes HCCTool1 color only the top arg flags by size before resorting to coloring the rest black. Any positive integer can be passed but the value is clamped at thirty.
The following output is with only the largest branch recoTracks_generalTracks__RECO.obj of the first example file above colored blue and all others colored black. A better example of the utility of this method is shown below when combining this method with coloring the top N buckets as well.
Tool 1 also allows filtering based on event numbers within a file within the file. Using the -e flag can enables this method. Passing in a single number only plots from 0 up to that event number in the file. Passing in two numbers separated by a : will display from the lower to the upper event number within the file.
Below are the results of two different filters applied to the same file. The first is one displaying only the first 1000 events in the example file. The second is one displaying events 1000-2000 of the same file.
HCCTool1 allows for the filtering out of branches based on a python regular expression. In this mode only branches that match the passed regular expression are added to the graph and further parsed. Any legal python regular expression is allowed. For more information on python regular expressions see the Python documenation
The following is an example of the original file parsed using the regular expression Track*. When a regular expression is used all of the data on the graph is colored black.
Any of these flags can be used in combination with each other to manipulate the data in a desired way. The only two that should not be mixed are filtering by branch numbers and filtering by event numbers. If the two flags are used in tandem erroneous results will be graphed. Below is an example of using two flags at once.
This is an example of the output generated by HCCTool1 when only the first 1000 baskets encountered in the file are graphed and only the top 10 branches by size are given a specific color in the produced output.
Tool1 allows the specification of only displaying the first N number of baskets within the root file. Any integer can be used in this argument. After parsing the file the program finds the Nth bucket and discards any that occur after it in the file.
The second option that is displayed in this graphic is the top 10 branch feature. With this feature enabled only the top 10 branches within the file are given a distinct color in the color map. All other branches are colored in black. When this mode is used a separate legend file is produced. In the future this legend will be produced alongside the original graphic.
