Project

General

Profile

Running the EventDisplay

Updated Resources.

Here are various Event Display (EVD) tutorials given over the years:
Michael Baird, 2014 Offline Tutorial slides docdb-10991, video
Fernanda Psihas, 2016 Workshop slides docdb-15022, video
Teresa Lackey, 2020 YN Tutorial slides docdb-45705

The executable

The event display is run using the nova executable. You can double check that the executable is running typing which nova in the terminal.
It can take all the same command line options as the batch executable, nova, ie

$nova -h
nova <options> [config-file]:
  -h [ --help ]          produce help message
  -c [ --config ] arg    Configuration file.
  -s [ --source ] arg    Source data file (one only).
  -T [ --TFileName ] arg File name for TFileService.
  -o [ --output ] arg    Event output stream file.
  -n [ --nevts ] arg     Number of events to process.
  -e [ --estart ] arg    Event # of first event to process.
  --nskip arg            Number of events to skip.

A typical event display session can be opened doing

$nova -c evd.fcl -s /nova/data/art/genie_gen.root

The display

The event display looks like

Example event from Monte Carlo

The top panel shows the XZ view of the detector, the middle panel shows the YZ view, the bottom left panel shows the timing distribution of the recorded digits and the bottom right shows the ADC distribution of the recorded digits. The colors on the plots reflect the colors used to render the hits. In this example, the hits are assigned colors based on their ADC values. One can alternately choose to color the hits based on their time values. It is also possible to assign the size of the hit based on the amount of charge deposited. The Drawing Options section below should have more information about all the options available for drawing.

When the display shows a MC event, the particles involved in it (along with their initial momenta) could be observed on top of the timing histogram. In the example above, a 2.3 GeV/c muon neutrino interacts with a proton. At the end of the reaction equation, the type of neutrino interaction is also shown (when available). The option for showing this text is available under: Edit -> Configure Drawing -> SimulationDrawingOptions - select the 'short' option under Text. The following is the color code for the particles' attributes shown in the MC drawing options, which includes: trajectories, hits, vectors and the text.

  • electron, electron neutrino
  • muon, muon neutrino
  • gamma
  • neutral pion
  • charged pion
  • proton
  • neutron

Configuration

Drawing Options

Drawing options menu

Drawing options are selected under the Edit pull down menu at the top of the window. This will bring up a window listing the parameters and settings used for drawing hits, MC information, Geometry information, etc. The default values originate from the evd_services.fcl file. If you find yourself frequently switching the drawing options you may want to consider putting a version of evd_services.fcl into your test release job directory and editing to match your preferred settings. You can also add these settings to the end of a local version of evd.fcl.

GeometryDrawingOptions

  • DimDisabled: Dims channels marked bad by the Bad Channel service.
  • Disabled/EnabledColor: Default color for disabled/enabled channels.
  • Fiducial Bounds: Defines borders for a fiducial box that can be drawn by checking the fiducial-user box under Outline. [xmin, ymin, zmin, xmax, ymax, zmax]
  • Flip: Can flip the direction of any axis. Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    Set with (example for flipping x and z):
    services.GeometryDrawingOptions.Flip.val: 5
    or
    services.GeometryDrawingOptions.Flip.val: 0x5
    • x (1, 0x1) CAREFUL! The numbers on the x and y axes do not flip correctly. Compass directions and hits will be flipped.
    • y (2, 0x2) CAREFUL! The numbers on the x and y axes do not flip correctly. Compass directions and hits will be flipped.
    • z (4, 0x4)
  • HighlightCell/Plane: Choose plane-cell combination to draw a red box around.
  • Label: Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    Set with (example for setting both):
     services.GeometryDrawingOptions.Label.val: 3
    or
    services.GeometryDrawingOptions.Label.val: 0x3
    • plane-cell numbers (1, 0x1): Prints plane and cell number every 4 planes/cells.
    • compass (2, 0x2): Prints east, west, north, and south on axes.
  • Outline: Select physical objects you want to draw an outline around. Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    Set with (example for outlining detector and cells):
    services.GeometryDrawingOptions.Outline.val: 17
    or
    services.GeometryDrawingOptions.Outline.val: 0x11
    • detector (1, 0x1)
    • fiducial-user (2, 0x2): Need to set FiducialBounds.
    • grid (4, 0x4)
    • DCMs (8, 0x8)
    • cells (16, 0x10)
    • badboxes (32, 0x20)
  • SliceBoxSize: Define size of box to draw around slice [x, y, z]. Middle of box determined by finding midpoint of slice.MinXYZ() and slice.MaxXYZ().
  • ViewingAngles3D: Allows for rotation of view. Default values are [35, 120, -75]. [θ, φ, ψ]
  • ZRange: Sets z upper bound for when the partial Zoom option is selected.
  • Zoom: Value to set the option at the fcl level in parentheses - can only choose one option. All zoom options do their best to maintain the same aspect ratio for XZ and YZ projections.
    • full (0, default): Show full detector.
    • hits (1): Zooms in on a box just larger than the extent of all raw digits in the event.
    • truth (2): Zooms in on a box just larger than the extent of all FLS hits (that have a corresponding CellHit) in the event. Might not work if file does not have CellHits - there doesn't appear to be a fall-back on RawDigits built into this function.
    • slice (3): Zooms in on a box just larger than the extent of the slice (uses slice.MinXYZ() and slice.MaxXYZ()).
    • sliceBox (4): Zooms in on a box centered on the slice, with the size determined by user input in SliceBoxSize.
    • partial (5): Zooms in on (centered) box showing half of the detector. User can set ZRange to determine upper bound on z.

PlotDrawingOptions

Reconstruction modules may choose to produce histograms on an event-by-event basis to help monitor and debug their performance. These plots can be displayed along side the event by openning the PlotsView under the Edit pull-down menu. Once open, the PlotsView is configured using the PlotDrawingOptions.

Before plots can be viewed in the event display, they must be stored in the event. To store histograms in an event the user would do
something like this:

In the constructor:

 this->produces< std::vector<TH1F> >; 

...and in the produce() method:
auto_ptr< std::vector<TH1F> > histos1d(new std::vector< TH1F >);
TH1F myhisto("myhisto","title;xaxis;yaxis",100,0,1);
// ...Do your thing... Fill the histogram...
histos1d->push_back(myhisto);
evt.put(histos1d);

The example is for TH1F but several other ROOT plotting classes (TH1F, TH2F, TH1D, TH2D, TGraph, TGraphErrors, TProfile) are also supported. The one configuration parameter in the PlotDrawingOptions is PadDescription which is probably best demonstrated with an example. Suppose you have two modules Module1 and Module2 which produce histograms histoA, histoB, histoC, and histoD. You would then set the PadDescription to something like:

PadDescription: [
  "Module1/histoA",
  "Module1/histoB/hist,lcolor=2,lwidth=2",
  "Module2/histoC/hist,lcolor=2,lwidth=2 + Module2/histoD/e1,mtype=24" 
]

This will create 3 pads on the event display view. The first will show just histogram A. The second will show histogram B with a thick red line. The third pad will show histogram C using a thick red line with histogram D superimposed using open circles and error bars. The list of supported options are:

logx, logy, logz, gridx, gridy
lstyle=[int], lwidth=[int], lcolor=[int]
mstyle=[int], msize=[int], mcolor

RawDrawingOptions

  • ADCBinSize/Range: Change binning and range for ADC histogram on lower right corner of pad.
  • CellHitsModules: What was the module label for CellHits?
  • CellHitsModulesAdd: If the correct label was not listed above, enter it here.
  • Color: Toggle how to color hits. Value to set the option at the fcl level in parentheses - can only choose one option.
    • by charge (0)
    • by time (1)
  • Hit3DStyle: How to render hits on 3D display. Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    • boxes (1, 0x1)
    • towers (2, 0x2))
    • crossings (4, 0x4)
  • RawDigitsModules: What was the module label for RawDigits?
  • RawDigitsModulesAdd: If the correct label was not listed above, enter it here.
  • RawDrawingOpt: Choose what level of hits you wish to display. Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    Set with (example for scaling hits and suppressing ghosted hits):
    services.RawDrawingOptions.RawDrawingOpt.val: 6
    or
    services.RawDrawingOptions.RawDrawingOpt.val: 0x6
    • mask bad channels (1, 0x1): Don't draw channels marked bad by the Bad Channel service.
    • scale hits by charge (2, 0x2): Larger charge deposits -> larger hits. Can change ScaleFactor below.
    • suppress ghosted hits (4, 0x4): Don't display greyed out hits (hits out-of-time or out-of-slice).
    • ghost dimmed hits (8, 0x8): Mark hits in other slices to be ghosted so you can suppress them.
  • ScaleFactor: Factor for scaling hits by charge.
  • THistogram: Display time histogram? Value to set the option at the fcl level in parentheses - can only choose one option.
    • off (0)
    • on (1)
  • TimeAutoZoomTruth: Zooms in time histogram on true time of FLS hits.
  • TimeBinSize/Range: Change binning and range for time histogram on bottom middle of pad.
  • WhichHits: Display RawDigits or CellHits? Value to set the option at the fcl level in parentheses - can only choose one option.
    • RAW (0): RawDigits
    • CAL (1): CellHits (output of calhit).
  • WhichQ: Display PE or PECorr? Value to set the option at the fcl level in parentheses - can only choose one option.
    • PE (0): PE calculated by just applying gain to ADC.
    • PECOR (1): PE with attenuation corrections added.

RecoDrawingOptions

The event display can be configured to draw various reconstruction objects like tracks, cluster, vertices, prongs and showers. To access these options, click : Edit->Configure Drawing->RecoDrawingOptions. Here, you can specify the module label/s of the objects you want to draw. You can also specify which particular track/cluster/vertex/prong you want to draw by using the index options. The default index is -1 and all the objects of a given type from a given module-label will be drawn. If you specify a number 'i' within 0 to (vector size - 1), it will draw only the ith object in the vector. If no number is specified, it will draw all the objects in that vector. If indices outside the vector's range are specified, they will just be ignored.

The module label names and index FHiCL parameters in the RecoDrawingOptions are implemented as std::vector's of strings and std::vectors of std::vectors of ints respectively. It comes in handy in case you want to draw objects from more than one modules like so:

 ClusterModules : ["slicer","recojmshower"]
 ClusterIndex:    [ [-1], [0,1]]
 DrawClusters:    [2]

This will draw all the slicer clusters and only the 0th and the 1st clusters in the vector of clusters from recojmshower.

NOTE: When zoomed in on a time window, you will still see all clusters and tracks unless you step through slice-by-slice. Only in-time prongs are displayed.

  • CellHits: What was the module label for CellHits?
  • CellHitsAdd: If the correct label was not listed above, enter it here.
  • ClusterIndex: Which cluster do you want to draw? Set to -1 to draw all. This doesn't currently appear to have any effect on what is drawn.
  • ClusterStyle: Drawing style for cluster. Value to set the option at the fcl level in parentheses - can choose multiple (though that's not very useful in this case), simply add the values for each option you want together. Can also choose to use hex representation. If you select both tight box and convex hull at the same time, it will default to just drawing the tight box.
    Set with (example for tight box only):
    services.RecoDrawingOptions.ClusterStyle.val: 1
    • tight box (1, 0x1): Tight box cluster drawing option.
    • markers (2, 0x2): Markers cluster drawing option.
    • convex hull (4, 0x4): Convex hull cluster drawing option.
  • Clusters: What was the module label for the cluster you wish to view?
  • ClustersAdd: If the correct label was not listed above, enter it here.
  • Hough: What was the module label for hough lines?
  • HoughAdd: If the correct label was not listed above, enter it here.
  • HoughOpt: Value to set the option at the fcl level in parentheses - can only choose one option.
    • off (0): Don't draw hough lines.
    • on (1): Draw hough lines.
    • color by index (2): Draw hough lines, color-coded by index. Color order is: kAzure+6, kPink+1, kGreen-9, kOrange+1, kViolet-5, kTeal+1, kYellow-9, kCyan+1, kRed-7, kSpring+10, kAzure+6, kPink+1.
  • OfflineChans: Need to use Add option below.
  • OfflineChansAdd: What was the module that created geo::OfflineChans? Most standard files won't have this.
  • ProngIndex: Which prong do you want to draw? Set to -1 to draw all.
  • ProngOpt: Value to set the option at the fcl level in parentheses - can choose multiple (though that's not very useful in this case), simply add the values for each option you want together. Can also choose to use hex representation.
    • as cluster (1, 0x1): Will use whichever option(s) you have selected for ClusterStyle.
    • as prong (2, 0x1): Similar to the markers option for clusters.
  • Prongs: What was the module label for prongs? (Can select more than one.)
  • ProngsAdd: If the label you want was not listed above, enter it here.
  • ShowerOpt: Value to set the option at the fcl level in parentheses - can only choose one option.
    • off (0): Don't draw showers.
    • on (1): Draw showers.
  • Showers: Need to use Add option below.
  • ShowersAdd: What was the module that created @rb::Shower@s Most standard files won't have this. Showers are drawn the same as prongs (they're just prongs with length).
  • TrackIndex: Which track do you want to draw? Set to -1 to draw all.
  • TrackOpt: Drawing style for tracks. Value to set the option at the fcl level in parentheses - can choose multiple (though that's not very useful in this case), simply add the values for each option you want together. Can also choose to use hex representation.
    Set with (example for as track and ortho hits):
    services.RecoDrawingOptions.TrackOpt.val: 12
    • as cluster (1, 0x1): Will use whichever option(s) you have selected for ClusterStyle.
    • as prong (2, 0x2)
    • as track (4, 0x4)
    • ortho hits (8, 0x8): Only works in combination with as track.
  • Tracks: What was the module label for tracks? (Can select more than one.)
  • TracksAdd: If the label you want was not listed above, enter it here.
  • VertexIndex: Which vertex do you want to draw? Set to -1 to draw all.
  • VertexOpt: Value to set the option at the fcl level in parentheses - can only choose one option.
    • off (0): Don't draw vertices.
    • on (1): Draw vertices.
  • Vertices: What was the module label for vertices? (Can select more than one.)
  • VerticesAdd: If the label you want was not listed above, enter it here.

SimulationDrawingOptions

If one draws FLS hits, one sees many blue and red hits. The color indicates the type of particle that created the hit; namely, blue for muon and red for electron. The PDG code assigned is the particle that ultimately deposits the energy, so you see a lot of red hits even on muon tracks. Please see here for further color information of FLS hits (or scroll up to just above the Configuration section on this page).

  • Draw: What MC Truth objects do you want displayed? Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    Set with (example for drawing vertex, hits, and gammas)
    services.SimulationDrawingOptions.Draw.val: 41
    or
    services.SimulationDrawingOptions.Draw.val: 0x29
    • vertex (1, 0x1)
    • vectors (2, 0x2)
    • trajectories (4, 0x4)
    • hits (8, 0x8)
    • neutrals (16, 0x10)
    • gammas (32, 0x20)
  • FLSHitListModules: What was the module label for FLSHits?
  • FLSHitStyle: Value to set the option at the fcl level in parentheses - can only choose one option.
    • dots (0)
    • lines (1)
  • FLSHitThresh: Hits that deposit less than 0.001*FLSHitThresh in the cell are not drawn.
  • MCTruthModules: What was the module label for MCTruth objects?
  • Text: Display interaction information. Value to set the option at the fcl level in parentheses - can choose multiple, simply add the values for each option you want together. Can also choose to use hex representation.
    • short (1, 0x1): Displays interaction on the canvas.
    • long (2, 0x2): Prints out particles and their energies in the terminal.
  • TextDepthLimit: How far down the daughter tree do you want to go? -1 to print all.
  • TextIncludeDirections: Display momentum vectors (Px, Py, Pz). Value to set the option at the fcl level in parentheses - can only choose one option.
    • off (0)
    • on (1)
  • TextIncludeVertex: Display vertices (X, Y, Z, t). Value to set the option at the fcl level in parentheses - can only choose one option.
    • off (0)
    • on (1)

Trouble Shooting

Add any issues and solutions you have here.

Running the Event Display with no Database Connections

If there is database maintenance or some ongoing connection issue, you can run the Event Display without connecting to any databases. The only things you lose access to when running like this is the Bad Channel and Live Geometry bad box information. This means you won't be able to draw cell outlines or bad box outlines, but most features should still work. Simply copy evd.fcl (or whichever custom version you're using) locally, and edit the services block to look like the one below (just comment out the core_services line and add the 3 services essential for running the EVD):

services:
{
  RandomNumberGenerator: {} #ART native random number generator
  #@table::core_services
  Geometry: @local::standard_geo
  CMap: @local::standard_cmap
  Detector: @local::standard_detector

  # EVD services
  PlotDrawingOptions:       @local::standard_plotdrawingopt
  GeometryDrawingOptions:   @local::standard_geomdrawingopt
  SimulationDrawingOptions: @local::standard_simdrawingopt
  RawDrawingOptions:        @local::standard_rawdrawingopt
  RecoDrawingOptions:       @local::standard_recodrawingopt
  ScanOptions:              @local::standard_scanopt
  SliceNavigator:           @local::standard_slicenavigator
  Colors:                   @local::standard_colors
  EventDisplay:             @local::standard_evd
}

Hand Scan dialog box

It is possible to define a hand scan by setting the fields in the ScanOptions service from within a .fcl file. The ScanOptions service has 5 fields that must be supplied:

  1. IncludeMCInfo: bool, Set to True(False) if the MC information is (not) desired in the output file
  2. FileNameBase: std::string, Base name for the output file. The username will be appended to this base to tag who created the output.
  3. Categories: std::vector<std::string>, Collection of categories for grouping information from the scan.
  4. FieldLabels: std::vector<std::string>, Collection of labels for each field specified in the scan.
  5. FieldTypes: std::vector<std::string>, Collection of types for each field in the scan. Options include: RadioButton, CheckButton, Number, and Text.
  6. FieldsPerCategory: std::vector<unsigned int>, Number of fields in each category, used to separate the FieldLabels and FieldTypes collections into their categories.

The scan dialog box is started by clicking on the "Window" menu of the event display and selecting Scan Window. The code then interprets the options from the service and produces a dialog box with the fields laid out by category.

The screen shot below is from an sample scan. The "Prev" and "Next" buttons navigate through events in the input file, while the "Record" button saves entries in the dialog box to the output file and then advances to the next event in the file.

Sample hand scan dialog