TTask derived class to monitor RNO-G data over certain time periods. More...

#include "RnoMonitor.h"

Inheritance diagram for RnoMonitor:

Detailed Description

TTask derived class to monitor RNO-G data over certain time periods.

Copyright(c) 2022, RNO-G Experiment at Summit Station. All rights reserved.
 
Author: The RNO-G NCFS-based Offline Project.
Contributors are mentioned in the code where appropriate.
 
Permission to use, copy, modify and distribute this software and its
documentation 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.
The authors make no claims about the suitability of this software for
any purpose. It is provided "as is" without express or implied warranty.

// Class RnoMonitor
// TTask derived class to perform RNO-G data monitoring over certain time periods.
//
// This processor can be used to e.g. search for recurrent astrophysical signals
// due to the rotation of the Earth.
// For this, several 24 hour time windows are defined in different time conventions
// (i.e. Universal Time, Local Time and Local Mean Sidereal Time) in which event
// data is recorded in histograms based on the event time stamps.
// Data recording is performed in a "stacked" fashion, meaning that events that
// occurred at different days but at approximately the same daytime, will be 
// recorded within the same histogram bin.
// This procedure will amplify signals recurring at the same daytime, whereas
// random occurrences will be averaged out.
//
// During the processing, various histograms are created which can be
// written to an output file by invoking the member function WriteHistograms()
// after the processing of all data has completed. 
//
// This monitoring can be performed "on the fly" by declaring this facility
// as a sub-task of RnoConvert, as can be seen in the ROOT macro convert.cc
// which is located in the folder /rnopack/macros.
//
// However, this task can also be performed on the rnopack data structures
// which reside in the files that are created by RnoConvert.
// An example of such an implementation can be seen in the ROOT macro analyze.cc
// which is also located in the folder /rnopack/macros.
//
// Note : Events that have been rejected by invokation of NcEventSelector
//        will not be taken into account for the monitoring.
//
//--- Author: Nick van Eijndhoven, IIHE-VUB, Brussel, July 6, 2022  09:51Z
//- Modified: Nick van Eijndhoven, IIHE-VUB, Brussel, May 17, 2023  08:37Z

Definition at line 16 of file RnoMonitor.h.

Public Member Functions
	RnoMonitor (const char name="RnoMonitor", const char title="RNO-G data monitoring")

virtual	~RnoMonitor ()

void	DefineStatistic (TString mode)

virtual void	Exec (Option_t *opt)

void	ListHistograms () const

void	SetBandFilters (TArray &freqs, Int_t n)

void	SetBaselineMode (Int_t mode, Int_t n=128, Double_t nrms=1.2, Double_t fpr=0.1)

void	SetDevices (TString devclass, Int_t ista=-1, Int_t ichan=-1)

void	SetDeviceSample (Int_t j)

void	SetNbins24 (Int_t n)

void	SetSampleVariable (Int_t i, TString f="-")

void	SetSampleVariable (TString name, TString f="-")

void	WriteHistograms (TString filename)

Protected Attributes
TString	fAvMode

TArrayD	fBands

Int_t	fBasemode

NcBlocks	fBB

Int_t	fBlocksize

Int_t	fChan

TString	fDevClass

Int_t	fDevSample

NcDSP	fDSP

RnoEvent *	fEvt

Bool_t	fFirst

Double_t	fFPR

TGraph	fGin

TGraph	fGout

TH1F	fHblock

TObjArray	fHistos

Int_t	fNbins24

Int_t	fNkernel

Double_t	fNrms

Double_t	fOffset

Int_t	fSta

NcSample	fValues

TF1 *	fVarFunc

Int_t	fVarIndex

TString	fVarName

Constructor & Destructor Documentation

◆ RnoMonitor()

RnoMonitor::RnoMonitor	(	const char *	name = "RnoMonitor",
		const char *	title = "RNO-G data monitoring" )

// Default constructor.

Definition at line 63 of file RnoMonitor.cxx.

◆ ~RnoMonitor()

RnoMonitor::~RnoMonitor ( )

virtual

// Default destructor.

Definition at line 90 of file RnoMonitor.cxx.

Member Function Documentation

◆ DefineStatistic()

void RnoMonitor::DefineStatistic ( TString mode )

// Specify the statistic to be used for monitoring of the (function) values
// val(i) of the selected sample variable, as specified by SetSampleVariable().
//
// Supported (case sensitive) input for "mode" is :
// ------------------------------------------------
// "Mean"         : The mean of all val(i)
// "Median"       : The median of all val(i)
// "RMS"          : The Root Mean Square of all val(i)
//                  Note : This is NOT the RMS deviation defined as sqrt(variance)
// "SpreadMean"   : The average of all |mean-val(i)|
// "SpreadMedian" : The average of all |median-val(i)|
// "RMSdeviation" : The Root Mean Square deviation from the mean of all val(i)
//                  This is also known as sqrt(variance)
// Notes :
// -------
// 1) The statistics "Mean", "Median" and "RMS" are sensitive to pedestal offsets,
//    whereas all statistics are sensitive to baseline variations within the recorded time trace.
//    Please refer to the member function SetBaselineMode() to mitigate these effects.
// 2) For large data samples, the statistics "Median", "SpreadMean" and "SpreadMedian"
//    may lead to long(er) CPU times.
//
// In the default constructor mode="RMSdeviation" is initialised.

Definition at line 199 of file RnoMonitor.cxx.

◆ Exec()

void RnoMonitor::Exec ( Option_t * opt )

virtual

// Implementation of the monitoring procedures.
//
// Note : The determination of the final bin values and errors is performed
//        in the member function WriteHistograms() after all data 
//        have been processed.

Definition at line 399 of file RnoMonitor.cxx.

◆ ListHistograms()

void RnoMonitor::ListHistograms ( ) const

// Provide a list of all the stored histograms.

Definition at line 711 of file RnoMonitor.cxx.

◆ SetBandFilters()

void RnoMonitor::SetBandFilters	(	TArray &	freqs,
		Int_t	n )

// Specify the frequency bands to be used for digital filtering the recorded waveform before extracting
// the values of the statistic selected for monitoring, as specified by DefineStatistic().
//
// The filtering procedure is based on a convolution of the various provided Blackman
// single Low Pass and/or High Pass and/or Band Pass and/or Band Reject filters (see below).
//
// Large values of "n" will result in sharp transitions at the edges of the specified bands,
// but may result in long(er) computation times.
// On the contrary, small values of "n" will result in less sharp transitions at the edges
// of the specified bands, but result in short(er) computation times.
//
// Rule of thumb :
// ---------------
// The transition bandwidth (BW) at the edges of the specified bands (aka roll-off)
// may be approximated as BW=4/n, where BW is expressed as a fraction of the sampling frequency.
//
// Notes :
// -------
// 1) The size of the TArray "freqs" must be even and at least twice the number of
//    frequency bands to be specified (see below).
// 2) Specifying the same frequency band more than once will further suppress the unwanted frequencies. 
//
// For further details, please refer to the docs of the memberfunction FilterMultiBand() of the class NcDSP.
//
// Input arguments :
// -----------------
// freqs  : Array containing the lower and upper bounds of the frequency band(s) in MHz.
//          The array elements represent the various pairs [flow,fup] to define the frequency bands,
//          ordered as (f1low,f1up,f2low,f2up,...).
//          The following conventions are used :
//          flow>0 and fup>0 --> Apply a Band Pass filter over [flow,fup]
//          flow<0 and fup<0 --> Apply a Band Reject filter over [|flow|,|fup|]
//          flow<0 and fup>0 --> Apply a Low Pass filter with fcut=fup
//          flow>0 and fup<0 --> Apply a High Pass filter with fcut=flow
//          In case flow=0 or fup=0 the pair [flow,fup] is neglected.
// n      : The number of points in the corresponding filter kernels
//          For best functionality this must be an odd integer.
//          An even value of "n" will be increased by 1 to obtain an odd value. 
//
// In case the provided array has a length 0 or n<1, all band filter settings will be removed.

Definition at line 304 of file RnoMonitor.cxx.

◆ SetBaselineMode()

void RnoMonitor::SetBaselineMode	(	Int_t	mode,
		Int_t	n = 128,
		Double_t	nrms = 1.2,
		Double_t	fpr = 0.1 )

// Specify the (variable) baseline to be subtracted from the recorded waveform before extracting
// the values of the statistic selected for monitoring, as specified by DefineStatistic().
// Variable baseline subtraction will allow to obtain a time trace with an overall baseline at 0.
//
// Input arguments :
// -----------------
// mode : 0 --> No baseline subtraction
//        1 --> Represent the baseline as fixed blocks of "n" consecutive samplings
//              with as amplitude the mean of the corresponding "n" samplings
//        2 --> Represent the baseline as fixed blocks of "n" consecutive samplings
//              with as amplitude the median of the corresponding "n" samplings
//        3 --> Represent the baseline as dynamic Bayesian Blocks obtained with the
//              parameters "nrms" and "fpr" as outlined below.
//
// The input argument "nrms" tailors the sensitivity to fluctuations for the
// Bayesian Block baseline analysis, in case that is selected.
// Each recorded value in the time trace is given an error of "nrms" times the
// RMS deviation of all the recorded values.
// The input argument "fpr" represents the False Positive Rate for the Bayesian Block analysis.
// See NcBlocks::GetBlocks() for further details.
//
// Notes :
// -------
// 1) All statistics are sensitive to baseline variations within the recorded time trace.
//    If mode>0, the corresponding baseline correction of the time trace is performed to
//    correct for pedestal offsets c.q. baseline variations.
//    In general this will result in a time trace with a baseline at 0.
// 2) Parameter values (n, nrms or fpr) that are not applicable to the selected "mode"
//    are set to the unphysical value -1.
// 3) For large data samples, the invokation of the Bayesian Block analysis may lead
//    to rather long CPU times.
//
// In the default constructor mode=0 is initialised, which also implies n=-1, nrms=-1 and fpr=-1.
// At invokation of this member function, the default values are n=128, nrms=1.2 and fpr=0.1. 

Definition at line 242 of file RnoMonitor.cxx.

◆ SetDevices()

void RnoMonitor::SetDevices	(	TString	devclass,
		Int_t	ista = -1,
		Int_t	ichan = -1 )

// Specify the devices to be analysed.
//
// Input arguments :
// -----------------
// devclass : The class of the (derived) devices to be analysed.
// ista     : The station number (<0 means all available stations)
// ichan    : The channel number (<0 means all available channels)
//
// In the default constructor devclass is set to "RnoGANT" to select all antenna types
// and also all channels and all stations are selected.
// At invokation of this member function, the default values are ista=-1 and ichan=-1.

Definition at line 105 of file RnoMonitor.cxx.

◆ SetDeviceSample()

void RnoMonitor::SetDeviceSample ( Int_t j )

// Specify the sample (1=first) to be used from the stored device samples.
//
// In the default constructor this is set to 1 to select the first sample.

Definition at line 128 of file RnoMonitor.cxx.

◆ SetNbins24()

void RnoMonitor::SetNbins24 ( Int_t n )

// Set the number of bins for the 24 hour monitoring histograms.
// In the default constructor the number of bins is set to 24,
// which corresponds to a daily time resolution of 1 hour.

Definition at line 379 of file RnoMonitor.cxx.

◆ SetSampleVariable() [1/2]

void RnoMonitor::SetSampleVariable	(	Int_t	i,
		TString	f = "-" )

// Specify the (function of the) sample variable to be used for monitoring.
//
// Input arguments :
// -----------------
// i : Index (1=first) of the sample variable to be used
// f : Function of the specified variable to obtain the observable to be monitored.
//
// The 1D function "f" has to be specified following the TF1 string format convention.
// In case f="-" (which is the default) is specified, just the value of the i-th variable is used.  
//
// In the default constructor i=1 and f="-" are set.

Definition at line 141 of file RnoMonitor.cxx.

◆ SetSampleVariable() [2/2]

void RnoMonitor::SetSampleVariable	(	TString	name,
		TString	f = "-" )

// Specify the (function of the) sample variable to be used for monitoring.
//
// Input arguments :
// -----------------
// name : Name of the sample variable to be used
// f    : Function of the specified variable to obtain the observable to be monitored.
//
// The 1D function "f" has to be specified following the TF1 string format convention.
// In case f="-" (which is the default) is specified, just the value of the specified variable is used.  

Definition at line 171 of file RnoMonitor.cxx.

◆ WriteHistograms()

void RnoMonitor::WriteHistograms ( TString filename )

// Write the baseline parameter settings and all the generated histograms

// to a ROOT file with the specified filename.

Definition at line 731 of file RnoMonitor.cxx.

Member Data Documentation

◆ fAvMode

TString RnoMonitor::fAvMode

protected

Definition at line 46 of file RnoMonitor.h.

◆ fBands

TArrayD RnoMonitor::fBands

protected

Definition at line 56 of file RnoMonitor.h.

◆ fBasemode

Int_t RnoMonitor::fBasemode

protected

Definition at line 47 of file RnoMonitor.h.

◆ fBB

NcBlocks RnoMonitor::fBB

protected

Definition at line 49 of file RnoMonitor.h.

◆ fBlocksize

Int_t RnoMonitor::fBlocksize

protected

Definition at line 48 of file RnoMonitor.h.

◆ fChan

Int_t RnoMonitor::fChan

protected

Definition at line 38 of file RnoMonitor.h.

◆ fDevClass

TString RnoMonitor::fDevClass

protected

Definition at line 36 of file RnoMonitor.h.

◆ fDevSample

Int_t RnoMonitor::fDevSample

protected

Definition at line 39 of file RnoMonitor.h.

◆ fDSP

NcDSP RnoMonitor::fDSP

protected

Definition at line 55 of file RnoMonitor.h.

◆ fEvt

RnoEvent* RnoMonitor::fEvt

protected

Definition at line 34 of file RnoMonitor.h.

◆ fFirst

Bool_t RnoMonitor::fFirst

protected

Definition at line 58 of file RnoMonitor.h.

◆ fFPR

Double_t RnoMonitor::fFPR

protected

Definition at line 51 of file RnoMonitor.h.

◆ fGin

TGraph RnoMonitor::fGin

protected

Definition at line 52 of file RnoMonitor.h.

◆ fGout

TGraph RnoMonitor::fGout

protected

Definition at line 54 of file RnoMonitor.h.

◆ fHblock

TH1F RnoMonitor::fHblock

protected

Definition at line 53 of file RnoMonitor.h.

◆ fHistos

TObjArray RnoMonitor::fHistos

protected

Definition at line 44 of file RnoMonitor.h.

◆ fNbins24

Int_t RnoMonitor::fNbins24

protected

Definition at line 43 of file RnoMonitor.h.

◆ fNkernel

Int_t RnoMonitor::fNkernel

protected

Definition at line 57 of file RnoMonitor.h.

◆ fNrms

Double_t RnoMonitor::fNrms

protected

Definition at line 50 of file RnoMonitor.h.

◆ fOffset

Double_t RnoMonitor::fOffset

protected

Definition at line 35 of file RnoMonitor.h.

◆ fSta

Int_t RnoMonitor::fSta

protected

Definition at line 37 of file RnoMonitor.h.

◆ fValues

NcSample RnoMonitor::fValues

protected

Definition at line 45 of file RnoMonitor.h.

◆ fVarFunc

TF1* RnoMonitor::fVarFunc

protected

Definition at line 42 of file RnoMonitor.h.

◆ fVarIndex

Int_t RnoMonitor::fVarIndex

protected

Definition at line 40 of file RnoMonitor.h.

◆ fVarName

TString RnoMonitor::fVarName

protected

Definition at line 41 of file RnoMonitor.h.

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

rnopack/source/RnoMonitor.h
rnopack/source/RnoMonitor.cxx

Detailed Description

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ RnoMonitor()

◆ ~RnoMonitor()

Member Function Documentation

◆ DefineStatistic()

◆ Exec()

◆ ListHistograms()

◆ SetBandFilters()

◆ SetBaselineMode()

◆ SetDevices()

◆ SetDeviceSample()

◆ SetNbins24()

◆ SetSampleVariable() [1/2]

◆ SetSampleVariable() [2/2]

◆ WriteHistograms()

Member Data Documentation

◆ fAvMode

◆ fBands

◆ fBasemode

◆ fBB

◆ fBlocksize

◆ fChan

◆ fDevClass

◆ fDevSample

◆ fDSP

◆ fEvt

◆ fFirst

◆ fFPR

◆ fGin

◆ fGout

◆ fHblock

◆ fHistos

◆ fNbins24

◆ fNkernel

◆ fNrms

◆ fOffset

◆ fSta

◆ fValues

◆ fVarFunc

◆ fVarIndex

◆ fVarName