NcDataStreamStats Class Reference

Provide event classification tag statistics. More...

#include "NcDataStreamStats.h"

Inheritance diagram for NcDataStreamStats:

Detailed Description

Provide event classification tag statistics.

---

Copyright(c) 2028 NCFS/IIHE, All Rights Reserved.                           *
                                                                            *
Authors: The Netherlands Center for Fundamental Studies (NCFS).             *
         The Inter-university Institute for High Energies (IIHE).           *                 
                   Website : http://www.iihe.ac.be                          *
           Contact : Nick van Eijndhoven (nickve.nl@gmail.com)              *
                                                                            *
Contributors are mentioned in the code where appropriate.                   *
                                                                            * 
No part of this software may be used, copied, modified or distributed       *
by any means nor transmitted or translated into machine language for        *
commercial purposes without written permission by the IIHE representative.  *
Permission to use the software strictly for non-commercial purposes         *
is hereby granted without fee, provided that the above copyright notice     *
appears in all copies and that both the copyright notice and this           *
permission notice appear in the supporting documentation.                   *
This software is provided "as is" without express or implied warranty.      *
The authors make no claims that this software is free of error, or is       *
consistent with any particular standard of merchantability, or that it      *
will meet your requirements for any particular application, other than      *
indicated in the corresponding documentation.                               *
This software should not be relied on for solving a problem whose           *
incorrect solution could result in injury to a person or loss of property.  *
If you do use this software in such a manner, it is at your own risk.       *
The authors disclaim all liability for direct or consequential damage       *
resulting from your use of this software.                                   *

---

// Class NcDataStreamStats
// TTask derived class to perform statistics of event classification tags.
//
// During data taking or online/offline processing one usually records
// various tags for each event to indicate which trigger or filter criteria
// were fulfilled. This also allows to provide different data streams. 
//
// It is common that a certain tag has the following two indicators
// pass  : Indicates whether the tag criteria have been fulfilled (1) or not (0)
// write : Indicates whether the event is actually labeled to be written (1) or not (0)
//
// In case of high-frequency tag streams it is common that not every event
// will be written to storage in order to limit the data volume.
// In the Data Acquisition (DAQ) system this is implemented by a downscaling
// of the corresponding data stream via so-called prescaler settings.
// The effect is that although for a certain tag the passing criteria have
// been fulfilled (i.e. the "pass" indicator is set), the "write" indicator is not always set,
// but for instance only after every 1000 instances of an activated "pass" indicator.
// This results in a downscale factor of 1000 for that tag stream.
//
// This class provides a processor to analyse data samples and provide an overview
// of the various event tags that were encountered and the corresponding event rates.
//
// In addition to this, it offers also the possibility to tailor a re-tagging procedure,
// of which the results are provided next to the regular tag statistics.
// Via the memberfunctions ActivateTag() and DeactivateTag() the user can (de)activate
// certain tags in order to perform a re-tagging to investigate the effect in view of
// defining specific event samples or background reduction.
// In case none of these memberfunctions ActivateTag() or DeactivateTag() are invoked,
// all tags are regarded to be active in the re-tagging procedure. 
// In case DeactivateTag() is invoked, all tags that are not explicitly activated by the user
// will be considered de-activated in the re-tagging procedure.
// It should be noted that the tags which are explicitly de-activated via DeactivateTag()
// can not be activated anymore via invokation of ActivateTag().
// Please refer to the docs of these memberfunctions for further details.
//
// The input data is specified via the memberfunction AddInputFile().
// All data files that contain NcEvent (or derived) data structures are allowed.
//
// In order to obtain the required data, the NcEvent (or derived) structure should
// contain an NcDevice (based) object with the corresponding name (e.g. Trigger, Filter,...).
//
// The following two varieties of such an NcDevice (based) object may be present :
//
// 1) NcTagger (derived) devices. (The recommended option)
//    These devices have pre-defined memberfunctions and an internal data structure
//    which is tailored for the handling of event tags.
//    Specification of the device to be investigated is performed via invokation of
//    the memberfunction SetDevice().
//
// 2) A generic NcDevice. (Not recommended; Only for backward compatibility with old data files)
//    For a generic NcDevice object to serve as a tagging device, the user has to create a device 
//    in which each tag is stored as a Hit (=NcSignal) with the corresponding tag name (e.g. "LowPt").
//    Each Hit has to have at least 2 signal slots, each with the appropriate name to indicate
//    the "pass" indicator value and the "write" indicator value.
//    Instead of the names "pass" and "write", various other naming conventions
//    (e.g. "condition" and "prescale") are often used.
//    The name of the required device (e.g. "Filter") and the naming conventions of the
//    "pass" indicator and "write" indicator (e.g. "condition" and "prescale", respectively)
//    are specified via the memberfunction SetDeviceNames().
//
// Once the user has provided all necessary information, the analysis is performed
// by invoking the statement "ExecuteTask()" as indicated in the example below.   
//  
// This class is a generalisation of the original trigger-stats.cc and filter-stats.cc
// ROOT macros of Nick van Eijndhoven (IIHE-VUB, Brussel, 09-dec-2009).
//
// Note : The class NcTaggingStats provides a similar facility that can be invoked
//        as a (sub)task in an event-by-event task processing environment, which in some
//        cases might provide more flexibility.
//
// Example 1:
// ==========
//
// // This example performs an analysis of IceCube data contained as IceEvent structures
// // in *.icepack files within a Branch "IceEvent" of a Tree "T".
// // Since these are rather old files, they contain generic NcDevice objects to handle
// // the tags, since the class NcTagger was not yet available at the time of data recording.
// // The "pass" and "write" tags were named "condition" and "prescale", respectively.
//
// // Load the necessary libraries
// gSystem->Load("ncfspack");
// gSystem->Load("icepack");
//
// // Initialisation to perform an analysis of IceCube event filter statistics
// NcDataStreamStats fstat("FilterStats","IceCube event filter statistics");
//
// fstat.AddInputFile("*.icepack","T","IceEvent");
//
// fstat.ListInputFiles();
//
// // Provide a progress output line every 1000 events 
// fstat.SetPrintFrequency(1000);
//
// // Specify that we will access the NcDevice named "Filter"
// // and that the "pass" indicator is called "condition"
// // and the "write" indicator is called "prescale"
// fstat.SetDeviceNames("Filter","condition","prescale");
//
// // The statement below shows the alternative for a "Trigger" analysis
// // where the trigger tags do not have "pass" nor "write" indicators.
// // fstat.SetDeviceNames("Trigger","*","*");
//
// // Activate some tags to investigate re-tagging for a selected event sample
// fstat.ActivateTag("GFU");         // Gamma ray Follow Up stream
// fstat.ActivateTag("HESE");        // High-Energy Starting Event stream
// fstat.ActivateTag("EstresAlert"); // Enhanced Starting track alert stream
// fstat.ActivateTag("EHEAlert");    // Extreme High Energy event alert stream
//
// // De-activate some tags to investigate re-tagging for background reduction
// // This can also be used to de-activate tag names that were activated above
// // because of a matching name pattern.
// fstat.DeactivateTag("EHEAlertFilterHB"); // Extreme High Energy alert Heart Beat stream
//
// // Perform the analysis.
// fstat.ExecuteTask();
//
// Example 2:
// ==========
//
// // This example performs an analysis of RNO-G data contained as RnoEvent structures
// // in *.rnopack files within a Branch "Events" of a Tree "T".
// // At data recording, an NcTagger (derived) object was used and given the name "Trigger".
//
// // Load the necessary libraries
// gSystem->Load("ncfspack");
// gSystem->Load("rnopack");
//
// // Initialisation to perform an analysis of RNO-G event filter statistics
// NcDataStreamStats trigstat("TriggerStats","RNO-G trigger statistics");
//
// trigstat.AddInputFile("*.rnopack","T","Events");
//
// trigstat.ListInputFiles();
//
// // Provide a progress output line every 1000 events 
// trigstat.SetPrintFrequency(1000);
//
// // Specify that we will access the NcTagger (derived) device named "Trigger"
// trigstat.SetDevice("Trigger");
//
// // Activate some tags to investigate re-tagging for a selected event sample
// trigstat.ActivateTag("radiant"); // RADIANT trigger
// trigstat.ActivateTag("lt");      // Low threshold trigger
//
// // De-activate some tags to investigate re-tagging for background reduction
// // This can be used to de-activate tag names that were activated above
// // because of a matching name pattern.
// trigstat.DeactivateTag("radiant_surface"); // Surface trigger (fictative)
//
// // Perform the analysis.
// trigstat.ExecuteTask();
//
//--- Author: Nick van Eijndhoven 15-jun-2018, IIHE-VUB, Brussel
//- Modified: Nick van Eijndhoven, IIHE-VUB, Brussel, December 21, 2022  12:49Z

Definition at line 18 of file NcDataStreamStats.h.

Public Member Functions
	NcDataStreamStats (const char *name="NcDataStreamStats", const char *title="Event tag statistics")
	NcDataStreamStats (const NcDataStreamStats &q)
virtual	~NcDataStreamStats ()
void	AddInputFile (TString file, TString tree, TString branch)
virtual TObject *	Clone (const char *name="") const
virtual void	Exec (Option_t *opt)
void	ListInputFiles (Option_t *opt="") const
void	SetMaxEvt (Int_t n)
void	SetPrintFrequency (Int_t m)
Public Member Functions inherited from NcTaggingBase
	NcTaggingBase (const char *name="NcTaggingBase", const char *title="Base class for event tag processing")
	NcTaggingBase (const NcTaggingBase &q)
virtual	~NcTaggingBase ()
void	ActivateTag (TString name)
void	DeactivateTag (TString name)
void	SetDevice (TString devname, Bool_t passcheck=kTRUE, Bool_t writecheck=kTRUE)
void	SetDeviceNames (TString devname, TString passname, TString writename)
void	SetMaxTag (Int_t n)

Protected Attributes
TString	fBranchname
TChain *	fData
Int_t	fMaxevt
Int_t	fPfreq
Protected Attributes inherited from NcTaggingBase
TArrayI	fAcombis
TObjArray *	fAct
TArrayI	fApass
TArrayI	fAwrites
NcSignal	fCombis
TObjArray *	fDeact
TString	fDevname
NcEvent *	fEvt
NcEvent *	fEvtFirst
NcEvent *	fEvtLast
Bool_t	fFirst
Int_t	fMaxtag
TMatrixF	fMcombis
TMatrixF	fMpass
TMatrixF	fMwrites
Int_t	fNevt
Int_t	fNevtComb
NcSignal	fPass
TString	fPassname
TString	fWritename
NcSignal	fWrites

Additional Inherited Members
Protected Member Functions inherited from NcTaggingBase
void	ListStatistics ()

Constructor & Destructor Documentation

NcDataStreamStats() [1/2]

NcDataStreamStats::NcDataStreamStats	(	const char *	name = "NcDataStreamStats",
		const char *	title = "Event tag statistics" )

// Constructor and initialisation of default parameters.

Definition at line 200 of file NcDataStreamStats.cxx.

~NcDataStreamStats()

NcDataStreamStats::~NcDataStreamStats ( )

virtual

// Default destructor.

Definition at line 214 of file NcDataStreamStats.cxx.

NcDataStreamStats() [2/2]

NcDataStreamStats::NcDataStreamStats

(

const NcDataStreamStats &

q

)

// Copy constructor.

Definition at line 229 of file NcDataStreamStats.cxx.

Member Function Documentation

AddInputFile()

void NcDataStreamStats::AddInputFile	(	TString	file,
		TString	tree,
		TString	branch )

// Add an input file containing NcEvent (or derived) data structures to be analysed.
//
// Input arguments :
// -----------------
// file   : Name of the input file containing the ROOT Tree (wildcards are allowed)
// tree   : Name of the Tree containing the data
// branch : Name of the Branch containing the NcEvent (or derived) data structures
//
// Notes :
// -------
//
// 1) Environment variables may be used as $(...) in the filenname for convenience.
//    For example "$(HOME)/my-data/sample.ncfspack".
// 2) This memberfunction may be invoked several times to accumulate data files.
// 3) The "tree" name may vary for different input files, but the "branch" name
//    has to be the same for all the input files.

Definition at line 530 of file NcDataStreamStats.cxx.

Clone()

TObject * NcDataStreamStats::Clone ( const char * name = "" ) const

virtual

// Make a deep copy of the current object and provide the pointer to the copy.
// This memberfunction enables automatic creation of new objects of the
// correct type depending on the object type, a feature which may be very useful
// for containers when adding objects in case the container owns the objects.

Definition at line 611 of file NcDataStreamStats.cxx.

Exec()

void NcDataStreamStats::Exec ( Option_t * opt )

virtual

// Perform the analysis.
// The input argument "opt" is irrelevant.

Definition at line 244 of file NcDataStreamStats.cxx.

ListInputFiles()

void NcDataStreamStats::ListInputFiles

(

Option_t *

opt = ""

)

const

// Provide an overview of the various input files.
// The input argument "opt" corresponds to the available options of TChain::Print().
// By default opt="".

Definition at line 594 of file NcDataStreamStats.cxx.

SetMaxEvt()

void NcDataStreamStats::SetMaxEvt

(

Int_t

n

)

// Set the maximum number of events to be processed.
// The default constructor has set n=0 which means no limitation.

Definition at line 570 of file NcDataStreamStats.cxx.

SetPrintFrequency()

void NcDataStreamStats::SetPrintFrequency

(

Int_t

m

)

// Set print frequency to provide a progress output line every "m" events.
// The default constructor has set m=0 which means that no progress printout is produced.

Definition at line 582 of file NcDataStreamStats.cxx.

Member Data Documentation

fBranchname

TString NcDataStreamStats::fBranchname

protected

Definition at line 33 of file NcDataStreamStats.h.

fData

TChain* NcDataStreamStats::fData

protected

Definition at line 32 of file NcDataStreamStats.h.

fMaxevt

Int_t NcDataStreamStats::fMaxevt

protected

Definition at line 34 of file NcDataStreamStats.h.

fPfreq

Int_t NcDataStreamStats::fPfreq

protected

Definition at line 35 of file NcDataStreamStats.h.

---

The documentation for this class was generated from the following files:

• ncfspack/source/NcDataStreamStats.h
• ncfspack/source/NcDataStreamStats.cxx