Mu2e Home
Mu2e Data Products
Search
Mu2e@Work


Introduction

You can think of a "data product" as a piece of information to which you may get access by calling an appropriate get function on the event object. Equivalently, you can think of the art::Event object as an art::EventId plus a collection of data products. Most data products are collections of simpler objects but a few are just a single object; an example of a single object is the StatusG4 object that describes the completion status of Geant4.

Actually, the definition of a data product is slightly broader than this. The art::Run object is just an art::RunId object plus a collection of data products; similarly for the art::SubRun object. When we intialize Geant4, we do it in the beginRun method of Mu2eG4/src/G4_plugin.cc. At the end of Geant4 initialization we create a std::vector of all physical volumes known to G4 and we put this information into the art::Run object as a PhysicalVolumeInfoCollection. The SimParticle class holds two indices into this collection; one describes the volume in which the particle was born and the other describes the volume in which the particle stopped.

When you look at a class like StrawHitCollection, you will see that it is just a typedef to std::vector<StrawHit>. Why do we do this? Suppose that one day we wish to extend StrawHitCollection so that it behaves like a std::vector<StrawHit> plus some additional features. When we do this, your code should continue to work without any editing. We have already done this once. In the early days, SimParticleCollection was an std::vector<SimParticle> but it is now a cet::map_vector<SimParticle>. This change was required because we changed the behaviour G4 so that there are some missing track numbers; when we made this change, no one noticed.

You can read some background information about data products; in particular you can read about the naming conventions for data products.

The tables below list the data products that are supported for general use within Mu2e. A few are still in draft form and may change; these include the two StrawCluster classes. In each table, the first column lists that name of the class that produces them. Remember that data products are labeled by the label of the module that created them, not by the name of the class that created them; but you need to know the class name to find the code that created the data product. For a class named XXXXX you can find the corresponding code in XXXXX_plugin.cc. The second column lists the data type of the product; the definitions of the data products can be found in the header files in DataProducts/inc, MCDataProducts/inc or RecoDataProduct/inc. When one class may produce more than one data product of the same data type, these are distinguished using the instance name field in the data product id; the third column lists instance names; an empty string is a valid instance name.

The known data products as of June 2011 are:

Data Products in Mu2e Event Objects

Module    Data Type    Instance Name   Comment
EventGenerator GenParticleCollection Particles produced by the event generators
G4BeamlineGenerator G4BeamlineInfoCollection Additional per particle info for particles from G4beamline
GenParticleCollection Particles produced by the event generators
G4 StatusG4 Detailed description of G4 status for this event
StepPointMCCollection tracker Steps in straw gas volumes.
StepPointMCCollection virtualdetector Steps in any virtual detector
StepPointMCCollection calorimeter Steps in any calorimeter crystal
StepPointMCCollection calorimeterRO Steps in an APD volume attached to a crystal.
StepPointMCCollection stoppingtarget Steps in any stopping target foil
SimParticleCollection Particles created within G4; includes generated particles
PointTrajectoryCollection Useful for graphics.
MakeStrawHit StrawHitCollection Data-like simulated hits in the L/T Tracker
StrawHitMCTruthCollection MC truth for StrawHits
DPIndexVectorCollection StrawHitMCPtr Links to StepPointMCs that contributed to each StrawHit
MakeCaloReadoutHits CaloHitCollection Data-like simulated readout of a single APD.
CaloHitMCTruthCollection MCTruth for CaloHits
CaloCrystalOnlyHitCollection
DPIndexVectorCollection CaloHitMCCrystalPtr
DPIndexVectorCollection CaloHitMCReadoutPtr
MakeCaloCrystalHits CaloCrystalHitCollection Data-like info about hit crystals.
MakeStrawCluster StrawClusterCollection Ask Hans Wenzel or Hogan Nguyen
MakeDPIStrawCluster DPIndexVectorCollection DPIStrawCluster Ask Hans Wenzel or Hogan Nguyen


Data Products in Mu2e Run Objects

Module    Data Type    Instance Name   Comment
G4 PhysicalVolumeInfoCollection Names of physical volumes known to G4.


Data Products in Mu2e SubRun Objects

At present there are no data products stored in the SubRun object.


How to List All Data Products in a File

The recommended way to get a list of all data products in a Mu2e event-data file is:

 mu2e -c Analyses/test/fileDumper.fcl -s <input_file_name> -n <N>
 >>>>>>> after v6_0_0 moved to Print/fcl/fileDumper.fcl
where <input_file_name> is the name of a Mu2e event-data file and where <N> is the number of events to do.

Here is , an example of the output from this tool. It was created by

mu2e -c Analyses/test/fileDumper.fcl -s data_03.root -n 5
where data_03.root is the output file created by Mu2eG4/test/g4test_03.fcl. In the example output there is a block of printout for each of the first 5 events. For each data product, the first 4 columns contain the elements of the 4-part data product identifier. The fifth column contains the number of entries in each data product, provided that information is available; for most data products this will change from event to event. If the number of entries in the data product is not available, the fifth column will contain a dash or a question mark. The rules are: Many of the StepPointMC data products have a size of 0; this is normal since g4test_03.fcl creates only a few particles, all of which originate in the stopping target. Therefore the example does not produce particles that cover the full Mu2e apparatus.

Following the printout for the 5 events, there is similar printout describing the data products found in the SubRun record and the Run record.

You can change the behaviour of the fourth column, which contains the data type of the data product. The example illustrated shows the full class name. Instead you can choose to display the art "Friendly Classname"; to do so, edit fileDumper.fcl and change the value of the wantProductFullClassName parameter:

dumper : {
      module_type              : FileDumperOutput
      wantProductFullClassName : false
}
You may even ask that both names be printed, which will add an extra column to the output:
dumper : {
      module_type                  : FileDumperOutput
      wantProductFullClassName     : true
      wantProductFriendlyClassName : true
}

You may notice that the file dumper is implemented as an output module, not as an analyzer module. This is due to technical constaints inside art: the code that knows if a data product has a size function, is part of the art::Wrapper<T> class template. The Wrapper of a data product is not accessible to analyzer or producer modules but it is accessible to input and output modules. The code for the FileDumperOutput_module.cc is part of art, not part of Mu2e.

There is subtlety that was missed above. Each data product has an associated provenance that describes how the data product was made:

Suppose that module MA has no input data products (for example an event generator) and that it produces a data product DPA. Further suppose that module MB reads DPA and produces data product DPB. In this circumstance both data products A and B have an entry in the provenance registry. Now suppose that only the data product DPB is written to the output file. When that file is read in again, the data product DPA is not present but both provenances remain in the provenance registry; art does this because the provenance of DPA is part of the provenance of DPB and art always keeps complete proveances.

If we read this output file and write a new one in which we do NOT write data product DPB, then neither DPA nor DPB will be present in the output. In this case the provenances for both DPA and DPB will be removed from the registry that is written to the output file.

The general rule is that a provenance is retained in the registry so long as at least one of the following is true:

The actual behaviour of the file dumper module is that it loops over all provenances found in the provenance registry (not over all of the data products found in the file!). If a provenance is present in the registry but the corresponding data product is not present inthe file, then the last column contains a question mark.

In the example above, there are no provenances without a data product present in the file - so there are no lines that end in a question mark.

An example that contains provenance entries with no corresponding data product can be seen by:

mu2e -c Analyses/test/fileDumper.fcl -n 5 -s \
 /mu2e/data/tdr/beam/g4s1p1/tdr.beam.g4s1.primary.1025a.13797238/good/00000/dataBeamPrimaryToTS3DS23.root
You can look at the output of this command; many of the data products produced by the module labeled g4run were filtered by the g4filter module to produce compressed data products. Most of the products produced by g4run were not written to the output file. More details about how this file was produced are available in Mu2e DocDB-3774.

There are several other optional parameters for the file dumper module:


The Old Way to List All Data Products in a File

To list all data products in a file of event-data, you can run the command:

 mu2e -c Analyses/test/dumpDataProducts.fcl -s input_file_name.root
 >>>>>>> after v6_0_0 moved to Print/fcl/dumpDataProducts.fcl
If you wish to understand how this works, the source code is in Analyses/src/DataProductDump_plugin.cc.

Normally you should prefer to use fileDumper.fcl. However dumpDataProducts has been retained as an example of how to access provenance information.


Fermilab at Work ]  [ Mu2e Home ]  [ Mu2e @ Work ]  [ Mu2e DocDB ]  [ Mu2e Search ]

For web related questions: Mu2eWebMaster@fnal.gov.
For content related questions: kutschke@fnal.gov
This file last modified Tuesday, 11-Oct-2016 16:21:39 CDT
Security, Privacy, Legal Fermi National Accelerator Laboratory