LCIO Command Line Tool

Overview

The LCIO command line tool provides a number of useful utilities from the command line.The command line tool

Installation

To install the runnable LCIO jar, execute the following is launched with the script ./bin/lcio from the LCIO base root directory.

$LCIO/bin/lcio [command] [arguments]

...

mvn 

This will create a standalone, runnable jar such as:

target/lcio-2.4.4-SNAPSHOT-bin.jar

The exact file name will depend on the LCIO version.

Overview

The command line tool is launched using the java command, with the following syntax.

java -jar ./target/lcio-[VERSION]-bin.jar [command] [arguments]

For instance, this is the command that will print out the usage instructions on my system.

java -jar target/lcio-2.4.4-SNAPSHOT-bin.jar

With no arguments, the usage statement is printed.

usage: LcioCommandLineTool
Commands:
compare
concat
validate
siodump
print
stdhep
split
random
count
merge
 -h    Print lcio command-line tool usage.
 -v    Set the verbosity.

...

The compare command takes 2 or more input LCIO files and compares them to find differences.

usage: compare
 -f    Add a file to compare (Must have at least 2).
 -n    Set number of events to compare.
 -s    Set number of events to skip.
 -v    Set verbosity level (must be between 1 and 4).

For instance, this command will compare the second events of files file1 and file2, with high verbosity.

lcio compare -f file1.slcio -f file2.slcio -n 1 -s 1 -v 4

Extra arguments will be interpretted as additional input files, so the above could be written this way instead.

lcio compare -n 1 -s 1 -v 4 file1.slcio file2.slcio

...

The concat command takes 2 or more input LCIO files and concatenates them together into a single output file.

usage: concat
 -f    List of input files, 1 per line.
 -i    Add an input file.
 -o    Set the name of the output file.

The following will concatenate together file1 and file2 into outputfile.

lcio concat -f file1.slcio -f file2.slcio -o outputfile

The concat command also accepts lists of files, with one file per line.

file1
file2
...

Supposing that the above was contained in a file called flist.txt, the concat command can read this file list and concatenate together all the files in the list.

lcio concat -i flist.txt -o outputfile

...

The validate command takes 1 or more LCIO files as input and performs two simple checks on them. Firstly, a simple read test is done. If the read test fails, the LCIO file is considered invalid. Secondly, a comparison is performed between the major and minor LCIO version numbers in the file and from command line arguments. Any version mismatches are printed to the terminal.

usage: validate
 -M    Set major version.
 -f    Add an LCIO file to validate.
 -m    Set minor version.
 -n    Set number of events to read.

This command will perform one read test and check if the files were generated with the LCIO 1.5 version.

lcio validate -f file1.slcio -M 1 -m 5 -n 1

As in other commands, extra arguments are interpretted as paths to additional input files, so the "-f" switch can be dropped.

lcio validate file1.slcio -M 1 -m 5 -n 1

...

The siodump command prints out detailed information about the SIO blocks in LCIO files using the SIODump utility (written by Tony Johnson).

usage: siodump
 -f    Set the input LCIO file.
 -n    Set number of events to dump.  (Must be > 0) .
 -s    Set number of events to skip.  (Must be >= 0) .
 -v    Set verbosity level.  (Must be between 1 and 4) .

The following command will read the file file1, skip 1 event, and dump 2 events, with low verbosity.

lcio siodump -f file1.slcio -n 2 -s 1 -v 1

...

The print command prints detailed information about LCEvents, including tables of records for each LCCollection of LCObjects. This command is a rewrite of the C++ dumpevent utility (written by Frank Gaede).

usage: print
 -f    Set the LCIO file to dump.
 -m    Set the maximum number of records to print per collection.
 -n    Set the maximum number of events to dump.
 -s    Set the number of events to skip.

The following command will dump 2 events from the file file1, skipping the first event and limiting the number of objects printed from collections to 100.

lcio print -f file1.slcio -m 100 -n 2 -s 1

...

The stdhep command reads in a StdHep file and converts the HEPEVT blocks into LCCollections of MCParticles according to an algorithm by Ron Cassell (Java implementation by Tony Johnson).

usage: stdhep
 -i    Input Stdhep file.
 -o    Output LCIO file.

This command converts events.stdhep into lcio_events.slcio.

lcio stdhep -i events.stdhep -o lcio_events.slcio

...

The split command takes a single LCIO file and splits it into smaller chunks.

usage: split
 -i    The input LCIO file.
 -n    The number of events to split.

The following command will split the file file1.slcio into multiple files, each with a maximum of 5 events.

lcio split -i file1.slcio -n 5

...

The random command generates LCIO events filled with random data (which is basically nonsensical!). These LCIO files can be used for testing purposes.

usage: random
 -h    Print random usage.
 -m    Set the maximum number of objects in a collection.
 -n    Set the number of random events to generate.
 -o    Set the LCIO output file name.

The following command will generate 5 random events to the output file events.slcio, with maximum of 100 objects per LCCollection.

lcio random -m 100 -n 5 -o events.slcio

...

The count command counts the number of event and/or run headers found in the input LCIO files.

usage: count
 -e    Print number of event headers.
 -f    Add an input LCIO file.
 -h    Print count usage.
 -r    Print number of run headers.
 -t    Print totals of all files processed.

The following command will print the number of run and event headers found in the files file1.slcio and file2.slcio, plus the total numbers overall.

lcio count -f file1.slcio -f file2.slcio -e -r -t

...

The merge command overlays events from different LCIO files into one output file. It is a rather complicated command with a lot of possible options.

usage: LCIO Merge command
merge command
 -i    Set input file list with format:
       [file_name],[n_reads_per_event],[start_time],[delta_time]
       This option is not usable with the -f argument.
 -T    Set the starting time (ns).
 -e    Set number of events to merge in from each input file per merged
       event.  (Default is 1)
 -f    Add an input file.
 -h    Print merge usage.
 -n    Set maximum number of output events.
 -o    Set the output file.
 -t    Set delta time (ns).

In its simplest form, this command accepts a number of input files, reads one event from each input file, and writes the resulting overlayed event into an output file. For instance, to merge together file1.slcio and file2.slcio into file3.slcio, execute this command.

lcio merge -f file1.slcio -f file2.slcio -o file3.slcio

...

The command above could be replicated as follows if the file flist.txt contains the following lines.

/path/to/file1.slcio,1,0.0,0.0
/path/to/file2.slcio,1,0.0,0.0

The merge command then references this list.

lcio merge -i flist.txt

A delta time can be applied for simulating pileup, as in the following. This will pileup 5 events from the same input file, incrementing all times in the data objects by 5 nanoseconds per event.

/path/to/events.slcio,1,0.0,5.0

Backgrounds can also be overlayed using this command. One event will be read from events.slcio for each merged event, while 5 events will be read from backgrounds.slcio with a 5 nanosecond time increment for each background event.

/path/to/events.slcio,1,0.0,0.0
/path/to/backgrounds.slcio,5,0.0,5.0

In general, any arguments in the file list will override those from the command line.

select

usage: select
 -f    Set the input LCIO file.
 -h    Print select usage.
 -i    Add a pattern to include.
 -o    Set the output LCIO file.
 -t    Add an LCIO type to include.

...

This command selects all SimCalorimeterHits from an event file.

lcio select -f events.slcio -o calhits.slcio -t SimCalorimeterHit

This command selects all collections starting with "Hcal".

lcio select -f events.slcio -o hcal.slcio -i Hcal.*