NAME:  pick_events.py

Pick events from SAM.                             v01-00-00, HLM

USAGE:

  pick_events [options] eventlist

OPTIONS:

  --help             --  Print help.
  --check            --  Check that events are available.
  --rerun            --  Rerun mode.  Assumes dataset already exists.

  Batch job options

  --batch            --  Submit job to batch queue. [default]
  --queue=queue      --  Override batch queue [default = short]
  --out=file.out     --  Override output file [default = pick_events.out]
  --log=file.log     --  Override output file [default = pick_events.log]
  --machine=machine  --  Override machine where job is submitted [default = d0mino]
  --interactive      --  Run job interactively

  Other options

  --debug            --  Debug script (experts only).


DESCRIPTION:

pick_events may be used to extract interesting events from SAM.  The
command creates a dataset for the user that is made up of files
containing the desired events.  The command then runs copysam, which
is available in the D0 release area.  This command goes through the
dataset, and extracts the desired events.

Users must create an ASCII file that contains the following
information: user selected definition name for this set of events, the
SAM group the user wants to use to for this data set, the name of the
output file which should be created to include these events, the data
tier for the events (e.g. raw, reconstructed), and a brief description
of the selected sample.  Finally, the user should include in the ASCII
file the list of (run, events) desired (one line per pair, with a
space separating them). An example file is shown below.

Normally, a user would first check that their event list is OK, by
issuing the command:

  pick_events --check eventlist.dat

This will perform the 'sam translate constraints' command.

After checking, the user can try to get the events copied to their
specificied output file, by doing:

  pick_events eventlist.dat

To retrieve a sample that has already been defined, you can use

  pick_events --rerun eventlist.dat

When the job has completed, users should check the .out and .log
files, to see whether all events have been delivered.  There is no
guarantee that all events will be accessible in SAM when the job was
submitted.

By default, all pick_events commands create batch jobs to perform the
desired operation.  You may override this by using the --interactive
option.


EXAMPLE EVENTLIST FILE:

defname = test-pick-events-1
group = algo
datatier = raw
outfile = /home/melanson/projects/rawdata/out1
description = 'Test event list'

129194 595425
129194 599906
130573 887911


REQUIREMENTS:

Users must setup a D0 release that contains copysam.  This is
currently only available in the latest test release.  You can check by
looking for copysam.x in the bin area of a release.  Also, users must
setup the d0tools product.


LIMITATIONS:

 1. Currently only supports batch mode on d0mino.
 2. No automatic error recovery for events not available in SAM.
 3. Currently, event_number queries to SAM can be quite slow.
 4. There is a 'Python C API version mismatch for module cdr'
    This does not seem to be a problem.
 5. If you run a few batch jobs from the same area, using the
    same .out and .log files, the results will be appended to
    those files (new jobs at the bottom).