r20 - 13 Jul 2012 - 09:36:13 - MichelSorelYou are here: TWiki >  NEXT Web  >  NextSoftware > SoftwareOffline > SoftwareOfflineUsersGuide

Users Guide

For all sections except the last two in this Users Guide, we heavily reference the "master" documentation of the FMWK base code at: https://cdcvs.fnal.gov/redmine/projects/nusoft/wiki/Documentation, with only some additional clarifications.
In the second-to-last section, we briefly summarize the NEXT-specific available packages and what they are for.
In the last section, we discuss the choices you have to perform your own analysis of a FMWK DST.

The "ana" executable and its command line arguments

The framework provides a single executable ana which can be configured at run time to perform any of the reconstruction and analysis tasks provided by the experiment.
The available ana command-line arguments are explained at: https://cdcvs.fnal.gov/redmine/projects/nusoft/wiki/Binaries, and can also be found typing:
ana --help

FMWK XML Configuration Data: JobControl? and Module Directives

XML files are used to configure both the overall reconstruction/analysis job, as well as each individual module within it.
A description of the JobControl? directives can be found at: https://cdcvs.fnal.gov/redmine/projects/nusoft/wiki/JobControl.
The JobControl? XML file is in charge of:
  • loading the shared libraries needed for the job (typically, but not necessarily, one library per module)
  • loading pre-defined XML configuration files for each module, or define user-specific module configuration data
  • building the job: list and order of modules to be executed
A description of the module directives can be found at: https://cdcvs.fnal.gov/redmine/projects/nusoft/wiki/Config.

FMWK Module Methods

In the JobControl? XML configuration data, one can find lines for each module of the type:
<node module="io::BHEPReader" config="detsim" reco="1" ana="0"/>
While this Section really belongs more to the  SoftwareOfflineDevelopersGuide, in order to understand what the reco and ana switches mean, we put a brief discussion of FMWK module methods here.
The mandatory methods that need to be implemented by the user:
  • Constructor that takes a version string, where initialization stuff can be placed
  • Update method to load module configuration data
In addition, there are a number of pre-defined base methods that can be implemented, and which get called during important transitions in a job, see JobControl /Module.h for details:
  • Event-level processing: Reco() and Ana()
  • Start/end of FMWK files: NewFile() and EndFile()
  • Start/end of data runs: NewRun() and EndRun(), as determined by the run info stored in the FMWK event header
  • Start/end subruns: NewSubrun() and EndSubrun(), as determined by the subrun info stored in the FMWK event header
Note that there is no explicit "job summary" phase for the module: for that, just use the destructor. Of course, a module can declare and implement any additional methods the user wants.
Some more details are given at: https://cdcvs.fnal.gov/redmine/projects/nusoft/wiki/JobControl

FMWK Event Data

I/O of FMWK event data is controlled by several ana command-line options, -i and -o being the most important. Type ana --help for a complete list.

FMWK provides a very flexible scheme to read/write event-level data. Each event is subdivided into several branches corresponding to different stages of data processing. Several subfolders can live in each branch, eg to store reconstruction/analysis objects (such as hits, tracks, etc.) from different detectors or data streams.

The EventDataModel? FMWK base package provides the FMWK event data functionality. Documentation can be found at: https://cdcvs.fnal.gov/redmine/projects/nusoft/wiki/EventDataModel

FMWK Histogram Data

Output of FMWK "histogram" data is controlled by the -o command-line option for ana. A number of default histograms on job resources and event data statistics are created in this file. In addition, "histograms" declared within a module are automatically booked into their own subdirectory in the file, based on module name/version, preventing accidental overwriting. In addition, ctrl-c or HUP signal shuts program down nicely, closing histogram files.
In fact, "histogram data" is a bit of a misnomer: any type of ROOT object can be stored, not just histograms. For example, ROOT ntuples or trees with information that is not event-based (eg, run-level info). 

The Available Packages in nextoffline (as of current production release)


  • The ASCITables module computes the probability for a EL photon produced in a specific position within the EL grid to hit and be detected in a specific photodetector at the anode or cathode plane. Such light detection tables, produced for a given step size in the EL grid position and a given photodetector array configuration, are obtained by processing NEXUS MC anabase::Event objects stored in the DetSim branch. In such MC events, a large number of isotropically-distributed photons are produced in a given EL grid point. The module configuration parameters PMTTableFile and ELTableFile direct to input tables specifying index and positions of PMTs and EL grid points, respectively. The parameter PMTParamFile specifies the name for the output look-up table
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/ASCITables/trunk/xml/ASCITables.xml?view=markup&root=next


  • AnaBase is the library defining the analysis-level objects anabase::Event, anabase::Run and anabase::MCTrack, and no FMWK modules. anabase::Event is simply a bhep::event that can be stored in a FMWK event branch, such as DetSim or Summary. This is accomplished by having anabase::Event inherit from TObject (required by FMWK) and from bhep::event. Typically this will be either a MC event from the detector simulation, or a DST event after full reconstruction. Likewise, anabase::run is a bhep::run that can be stored in a FMWK histogram file, containing run-level (as opposed to event-level) information. Typically this will be either run-level information from the detector simulation, or run-level information after full reconstruction.


  • io::BHEPReader is a FMWK module to load an entire bhep::event stored in a ROOT file. The event is loaded into one of the available branches of the FMWK event: MC, DetSim, DAQ, Raw, RawAux, Cal, Reco, User, or Summary, as specified by the module's BranchID module configuration parameter. Typically, one will want to load a nexus (detector simulation) event into the DetSim branch, and a DST evet into the Summary branch. The ROOT filenames are specified by the InputFiles parameter. The number of events to read is instead set on the ana executable command line. This module is an event generator: it generates a FMWK event from scratch.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/BHEPReader/trunk/xml/BHEPReader.xml?view=markup&root=next







  • reco::CreateMCTracks is a FMWK module performing a very simplistic track reconstruction on MC events by "cheating", that is using MC truth information. This algorithm first defines track segments. One track segment is the collection of reconstructed hits of a single MC truth particle. Track segments can be merged into a reco::MCTrack as follows. If the distance between at least one hit of a track segment and at least one hit of a different track segment is less than the WireWidth parameter, then the totality of hits of the two track segments are merged into a single MCTrack. The procedure is then iterated to allow merging between two tracks, where one or both of the tracks are composed by more than one track segment. Once MCTracks are created, we define the track energy as the sum of the energy of all reconstructed hits associated to the track. We also define the effective track size as the maximum distance between two hits belonging to this track. If this distance is less than the IsolatedBlobMaximumSize parameter, then the track is classified as isolated blob type, otherwise it is classified as wire type. For a track (of wire or isolated blob type) to be considered as such, the total track energy has to be greater than the TrackMinimumEnergy parameter . This energy threshold condition is only applied after the track merging algorithm, not on individual track segments.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/CreateMCTracks/trunk/xml/CreateMCTracks.xml?view=markup&root=next





  • reco::DSTMaker is a FMWK module creating a summary (DST) information for a particular event, typically after reconstruction has been performed. This module creates a anabase::Event in the Summary branch of a FMWK event, starting from recobase objects stored after calibration and reconstruction. This module has no configuration parameters.


  • io::Database is a FMWK module that allows to perform queries to the MySQL?-based NEXT offline database from within any other FMWK module. All you have to do is to add Database at the beginning of your job, or in any case before the module(s) where DB queries are performed. The MySQLConfigurationFile parameter specifies the name for the MySQL? configuration file to be used. This library also defines io::Table objects that are used to store tabular information, coming either from a remote MySQL? connection or from a local (that is, stored on your hard drive) table in xml format. Therefore, one needs to link against this library even if only a local database is used.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/Database/trunk/xml/Database.xml?view=markup&root=next




  • The EnergyReconstruction module reconstructs the deposited energy per event. A few corrections to the basic energy observable, namely the integrated charge of the cathode sum, can be applied in this package. Such corrections are related to photodetector gain intercaibration, attachment of ionization electrons along drift, radial effects due to finite reflectivity of light tube walls. The algorithm writes instances of the recobase::Energy object in the Reco() branch. The Mode and ValidPMTID configuration parameters define the basic energy observable, namely whether the charge for the complete pedestal-subtracted waveform is used as opposed to using the charge contained in the waveform recobase:.Peak only, and which channels are summed together to define the energy estimator. This uncorrected energy estimator can be refined by applying corrections, specified by the RadialCorrectionPar1, DriftCorrectionPar1, WidthCorrectionPar1 parameters. The module can also compute such corrections from the data themselves, depending on the value for the ComputeRadialCorrection, ComputeDriftCorrection, ComputeWidthCorrection flags. Gain intercalibration correction is applied via the CalibrationFactors parameter.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EnergyReconstruction/trunk/xml/EnergyReconstruction.xml?view=markup&root=next


  • io::EventDump is a simple FMWK module: all it does is dump on screen FMWK event info. This module has no configurable parameters


We have grouped several FMWK modules to perform event selection into this single SRT library. The available filter modules are listed below.



  • DriftTimeFilter is a FMWK module to select events within a certain drift time range. If the drift time is less than DtMin or greater than DtMax, the event is rejected.
  • Default XML configuration file: [[http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EventFilters/trunk/xml/DriftTimeFilter.xml?view=markup&root=next][http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EventFilters/trunk/xml/DriftTimeFilter.xml?view=markup&root=next]


  • EnergyROIFilter is a FMWK module to cut events that lie outside of the energy region of interest. If the event energy is less than the EMin parameter or greater than the EMax parameter, then the event is rejected. Depending on the value of typeoftrack, the energy is taken from recobase::ChamberHit, recobase::Track or recobase::Digit objects in the event. One 1-dim histogram is created, with Nbins equal-width bins between EMin and EMax. If the event energy falls within EMin and EMax, then one entry per event at that energy is filled in the histogram. A second histogram of deposited energy per event is also created, this time before the energy cut.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EventFilters/trunk/xml/EnergyROIFilter.xml?view=markup&root=next




  • flt::PeakTypeCounterFilter is a FMWK module to cut events based on the number and type of recobase::Peak objects that the PeakFinder algorithm finds in the cathode sum waveform. If the number of S1-like recobase::Peak objects in the cathode sum is less than NS1Min or greater than NS1Max, the event is rejected. Likewise, if the number of alpha-like recobase::Peak objects in the cathode sum is less than NS2Min or greater than NS2Max, the event is also rejected.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EventFilters/trunk/xml/PeakTypeCounterFilter.xml?view=markup&root=next



  • flt::RadiusFilter is a FMWK module to cut events based on the radial position (that is, distance from chamber axis) of an assumed single point-like energy deposition within the gas. The algorithm uses as input recobase::ChamberHit objects. If more than one such 3D hit is present in the event, the first hit is used. If the radial position as read from recobase::ChamberHit is less than RMin or greater than RMax, the event is rejected.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EventFilters/trunk/xml/RadiusFilter.xml?view=markup&root=next






We have grouped several FMWK modules to perform event selection based on MC truth information into this single SRT library. The available filter modules are listed below.




  • flt::TrueVetoFilter is a FMWK module to cut MC events that do not satisfy full event containment. The algorithm first identifies all hits in an event with a true (x,y,z) position such that the hit distance to the closest detector wall is less than the MaxDistanceToWall parameter. For those hits, it computes the sum of the hits' true deposited energy. If this energy is greater than MinimumVetoEnergy, the event is rejected. Note that this algorithm requires knowledge of detector geometry, for now read from the nexus BHEP run tree information, and specified as module configuration parameters (DetectorCenter only). Only MC truth quantities are used.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/EventFilters/trunk/xml/TrueVetoFilter.xml?view=markup&root=next





  • The PatternRec module takes recobase::Track objects and return recobase::TrackWithAttributes. Attributes: maximum and next-to-maximum energy, number of blob candidates, maximum distance between blob candidates, l2, energy on the main track length of the track. This module has no configurable parameters.



  • The RawBase library contains the classes stored in raw data files. The following classes are defined:
GasADC and GasEvent (for NEXT-1-IFIC-GasIFIC DAQ files), PMTEvent, PMTEventHeader and PMTRunHeader (for NEXT-1-LBNL DAQ files). The following includes are defined: PMTDefines.h (for NEXT-1-LBNL DAQ files), event.h (for NEXT-1-IFIC-DATE DAQ files) This library is used by the RawDataReader package.


  • Event I/O handles to read from raw data streams. Supports input produced by:
    • NEXT-LBNL prototype: NEXTLBNLEventHandle, NEXTLBNLReadModule, NEXTLBNLReadModuleMaker
    • NEXT-1-IFIC prototype, GasIFIC? raw data format: GasIFICEventHandle, GasIFICReadModule
    • NEXT-1-IFIC prototype, DATE raw data format: NEXT1ELEventHandle, NEXT1ELReadModule
    • Generic DATE raw data format: GenericDATEEventHandle, GenericDATEReadModule


  • RecoBase is the library defining the general-purpose reconstruction-level objects, and no FMWK modules. These are the objects used within FMWK to perform reconstruction. After a full reconstruction job, the most relevant information in these objects is converted into a anabase::Event. Currently the following general-purpose reconstruction-level objects are defined: ChamberHit, DAQDigit, DATEEventHeader, Digit, LBLPeak, LBLSlice, PMT, PMap, PTrack, Peak, Sensor, SensorHit, Track, TrackWithAttributes, Trigger, Voxel, all within the recobase namespace. 



  • This is an administrative package. These are SoftRelTools files specific for the NEXT project, such as: makefile fragments to account for NEXT offline external libraries, SRT scripts customized for NEXT (most notably, to interact with a SVN rather than with a CVS repository, as well as others), NEXT-specific install and setup scripts.



  • cal::SmearHits is a FMWK module to create a reconstructed hit from a MC truth hit in a very simplistic manner. For each true hit, a reconstructed hit (specifically, a recobase::ChamberHit) is created with smeared (x,y,z) position and energy, according to the TransversePositionSigma, LongitudinalPositionSigma and FWHMatQbb parameters. The four smearings are assumed to be uncorrelated: four uncorrelated gaussian random numbers are thrown for each hit, according to the Seed random number seed parameter. The position resolution in (x,y,z) is assumed to be constant. The energy resolution is assumed to follow a sigma_E/E propto 1/sqrt{E} dependence.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/SmearHits/trunk/xml/SmearHits.xml?view=markup&root=next



  • This is an administrative package. More specifically, Software Release Tools (SRT) is a UNIX based software management system for large, collaborative projects that is used by several experiments. The system handles the version control, management, building, and distribution of code written in Fortran, C and C++. A distinguishing feature of the system is its ability to allow rapid asynchronous development of package versions, which can be easily integrated into complete consistent releases of the entire offline software. This is a local copy of the code residing in the FNAL CVS repository (tag F02-00-56). The only reason to make such a copy into our SVN repository rather than pulling out a copy from the FNAL CVS repository was to avoid users and developers to need a CVS client in addition to a SVN client in their machines. 


  • The SumDigits algorithm simply sums the pedestal-subtracted from several channels into one. A typical example of use of this algorithm is to perform the cathode sum. A vector of electronic identifiers of several recobase::Digit instances, the ValidElecID module configuration parameter, is used to decide which channels to sum. The algorithm writes a single recobase::Digit instance with the summed waveform. Optionally, perform (further) zero-suppression on summed waveform, according to the NSigmaZero parameter.
  • Default XML configuration file: http://next.ific.uv.es/viewvc/offline/FMWK/pkgs/SumDigits/trunk/xml/SumDigits.xml?view=markup&root=next




  • Utilities is a library containing global functions and classes providing useful utilities. Utilities include template and non-template operations on strings, vectors and maps; operations on ROOT histograms; a Interval class. Note that this library does not depend on RecoBase, and can be considered "experiment-independent".


  • This library defines the classes performing x/y reconstuction based on tracking plane information. Two reconstruction methods currently exist: barycenter and chi2 method.

I have FMWK DSTs with reconstruction info. How do I make my own analysis of it?

Freedom is left to analyzers on which "code technology" to choose to perform analysis. The only requirement is that the starting point be the reconstruction DSTs in BHEP event format. That means that your code will need to "know" about the BHEP library. Some choices are:

  • FMWK
  • Centella
  • ROOT CINT macros
  • PyROOT?
Examples of the same analysis performed with different "code technology" choices will be posted soon. If you plan to use FMWK also for analysis, you will want to read the SoftwareOfflineDevelopersGuide.   

-- MichelSorel - 04 Oct 2010

Edit | WYSIWYG | Attach | PDF | Raw View | Backlinks: Web, All Webs | History: r20 < r19 < r18 < r17 < r16 | More topic actions
Powered by TWiki
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback