Package: goodruns
Aboutgoodruns provides an implementation of an ATLAS Good Run List (GRL)
reader/writer in Python, and collection of useful command-line tools.Requirementsgoodruns requires at least Python 2.5. Unlike the standard ATLAS GoodRunsLists
package, goodruns does not depend onROOTfor XML
processing unless you are reading from or writing to a ROOT file (see below).
For faster XML reading/writing goodruns will optionally uselxmlif installed. InstallPyYAMLif you would like to convert GRLs into
YAML format.InstallationInstall the latest released version of goodruns withpip:pip install --user goodrunsOmit the--userfor a system-wide installation (requires root privileges).
Add${HOME}/.local/binto your${PATH}if using--userand if
it is not there already (put this in your .bashrc):export PATH=${HOME}/.local/bin${PATH:+:$PATH}To upgrade an existing installation, add the-Uoption in thepipcommand above.UsageAn example of how to use goodruns:from goodruns import GRL

grl = GRL('grl.xml')
# or:
grl = GRL('http://atlasdqm.web.cern.ch/atlasdqm/grlgen/path/to/grl.xml')
# or (if '/path/to/grl' is a ROOT.TObjString in data.root):
grl = GRL('data.root:/path/to/grl')

# check if the GRL contains the lumiblock 231 in run 186356:
if (186356, 231) in grl:
    # do something
    passThe GRL is automatically optimized (lumiblocks are merged and sorted):>>> from goodruns import GRL
>>> a = GRL()
>>> a.insert(1, (1,4))
>>> a.insert(1, (7,10))
>>> a
---------------
RUN: 1
LUMIBLOCKS:
  1 - 4
  7 - 10
>>> a.insert(1, (6,7))
>>> a
---------------
RUN: 1
LUMIBLOCKS:
  1 - 4
  6 - 10
>>> a.insert(1, (5,5))
>>> a
---------------
RUN: 1
LUMIBLOCKS:
  1 - 10Command-line Toolsgoodruns also provides a collection of command-line tools
for combining, manipulating, and inspecting GRLs. As above
GRLs may be XML files, URLs, or in ROOT files.grl diffUsegrl diffto determine the GRL containing the runs/lumiblocks inA.xmlbut not inB.xml:grl diff A.xml B.xmlIn other words,B.xmlis subtracted fromA.xml.
All command-line tools print on stdout. Redirect stdout to a file to save
the result:grl diff A.xml B.xml > C.xmlYou may supply more than two GRLs togrl diff:grl diff A.xml B.xml C.xml D.xml > E.xmlwhich results in the GRL E=((A-B)-C)-D). This is equivalent to:grl diff A.xml B.xml | grl diff C.xml | grl diff D.xml > E.xmlThe output of one command can be piped into any of the other commands
in goodruns.grl and, grl or, grl xorThese scripts implement logical combinations of GRLs. Logical AND:grl and A.xml B.xml > C.xmlOR:grl or A.xml B.xml > C.xmland XOR (exclusive OR):grl xor A.xml B.xml > C.xmlAgain, these commands can be combined arbitrarily:grl and A.xml B.xml | grl or C.xml | grl xor D.xml > E.xmland any GRL argument can also be a ROOT file or URL:grl and data.root:/path/to/grl http://atlasdqm.web.cern.ch/path/to/grl.xmlgrl clipUsegrl clipto truncate a GRL between a starting run/lumiblock and ending
run/lumiblock:grl clip --help
usage: grl clip [-h] [-o OUTPUT] [-f FORMAT] [--startrun STARTRUN]
                [--startlb STARTLB] [--endrun ENDRUN] [--endlb ENDLB]
                [grl]

positional arguments:
  grl

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output filename (optional)
  -f FORMAT, --format FORMAT
                        Output format: xml, yml, txt, py, cut
  --startrun STARTRUN   Start run
  --startlb STARTLB     Start lumiblock
  --endrun ENDRUN       End run
  --endlb ENDLB         End lumiblockgrl convertgrl convertcan convert a GRL from XML format into YAML:grl convert -f yml A.xml
186178:
- !!python/tuple [125, 156]
- !!python/tuple [158, 161]
186179:
- !!python/tuple [382, 388]
- !!python/tuple [390, 390]
- !!python/tuple [396, 396]
- !!python/tuple [398, 415]
- !!python/tuple [417, 431]
- !!python/tuple [433, 453]
- !!python/tuple [455, 469]
- !!python/tuple [471, 474]
- !!python/tuple [476, 479]
186180:
- !!python/tuple [114, 116]
- !!python/tuple [118, 124]
- !!python/tuple [126, 140]
- !!python/tuple [144, 149]
- !!python/tuple [151, 170]
- !!python/tuple [173, 176]
...or plain text:grl convert -f txt A.xml
---------------
RUN: 186178
LUMIBLOCKS:
  125 - 156
  158 - 161
---------------
RUN: 186179
LUMIBLOCKS:
  382 - 388
  390
  396
  398 - 415
  417 - 431
  433 - 453
  455 - 469
  471 - 474
  476 - 479
---------------
RUN: 186180
LUMIBLOCKS:
  114 - 116
  118 - 124
  126 - 140
  144 - 149
  151 - 170
  173 - 176
...grl convertwill also convert a GRL into Python code (dict of lists of
tuples) or (as a joke) a ROOT TCut expression.grl runsgrl runssimply prints the run numbers, one per line, contained
within a GRL:grl runs A.xml
186178
186179
186180
...Quickly print the runs contained in a GRL from a URL:grl runs http://atlasdqm.web.cern.ch/path/to/grl.xmlgrl findgrl findprints the GRLs containing a run number and lumiblock number (if
any). The lumiblock number is optional, and if left unset all GRLs containing
the run will be printed. For example, you can determine which ROOT file contains
the run 215643 and lumiblock 400 with the following command:grl find --path Lumi/tau --pattern "*.root*" --run 215643 --lb 400 globbed*path*