NCFS-Pack
A generic (astro)particle physics analysis framework
 
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
NcBlocks Class Reference

(Bayesian) Block treatment of sequential data. More...

#include "NcBlocks.h"

Detailed Description

(Bayesian) Block treatment of sequential data.

Copyright(c) 2021 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 NcBlocks
// Class for (Bayesian) Block treatment of sequential data.
//
// This class provides a tool set to detect and characterize local variability
// in sequential data.
//
// A very common case are observations in the form of time series, and as such
// this will be used for illustration in the documentation. However, the various
// procedures provided in this class apply to any form of sequential data.
//
// Time series can be divided in three categories, called Data Modes :
//
// 1) Recorded times of events, so called Time-Tagged Event (TTE) data.
// 2) Counts of events in time bins.
// 3) Measurements of a (quasi) continuous observable at a sequence of points in time.
//
// A Bayesian Block analysis provides a procedure to automatically detect local
// variability in the data stream by a dynamic partitioning of the dataset, resulting
// in data blocks of different length over which the event rate, event count or
// measured value can be regarded as constant.
//
// For each Data Mode a dedicated Bayesian Block analysis procedure is provided via
// the various GetBlocks() member functions.
//
// On the other hand, this class also provides GetBlocks() member functions which allow
// the user to form blocks defined by a fixed number of "n" samplings c.q. bins.
// In this case the height of each block is defined by the mean (or median) value of the
// recorded values within each set of "n" samplings.
// These member functions provide an efficient way to identify (pedestal) variations in case
// these might be expected to occur after recording "n" samples due to the specific DAQ design.
// In principle a Bayesian Block analysis would also be able to identify these variations
// over the sets of "n" samplings, but the analysis over a fixed number of "n" samplings
// is much faster than the dynamic Bayesian Block analysis.
//
// In a Bayesian Block analysis, local variability in the sequential data stream is indicated
// by so called Change Points, at which a step is introduced in e.g. the event rate, event count
// or measured value.
//
// Since the data treatment is inherently sequential, it is also possible to
// trigger c.q. stop after the occurrence of a certain number of Change Points.
// For instance, an online trigger system may be obtained by specifying to stop at the
// first occurrence of a Change Point.
// Please refer to the documentation of the GetBlocks() member functions for further details.
//
// Details of the various Bayesian Block algorithms can be found in the publication :
//
// J.D. Scargle et al., The Astrophysical Journal 764 (2013) 167. (ArXiv:1207.5578).
//
//
// Some coding examples:
// =====================
//
//
// Example 1: Unbinned data (Data Mode 1)
// --------------------------------------
//
// gSystem->Load("ncfspack");
//
// NcBlocks q;
//
// NcSample s("Event times");
// s.SetStoreMode();
// s.SetNames("Time");
//
// // Construct and store artificial event times
// Int_t nevt=100;
// Float_t t=0;
// Int_t low=nevt/4;
// Int_t mid=nevt/2;
// Int_t up=3*nevt/4;
// Float_t add=0;
// for (Int_t i=1; i<=nevt; i++)
// {
// if (i<low)
// {
// add=1;
// }
// else if (i<mid)
// {
// add=0.1;
// }
// else if (i<up)
// {
// add=1;
// }
// else
// {
// add=0.2;
// }
// t+=add;
// s.Enter(t);
// }
//
// Float_t fpr=0.1;
// TH1F hblock;
// hblock.SetName("hblock");
// q.GetBlocks(s,1,fpr,&hblock);
//
// TCanvas c("c","c");
// c.Divide(1,2);
// c.cd(1);
// TH1D hs=s.Get1DHistogram(1,0,kFALSE,1000);
// hs.Draw();
// c.cd(2);
// hblock.Draw();
//
//
// Example 2: Binned data (Data Mode 2)
// ------------------------------------
//
// gSystem->Load("ncfspack");
//
// NcBlocks q;
//
// TH1F h("h","Example 2: Binned data (Data Mode 2);Time in sec.;Weighted counts",100,0,100);
//
// h.Fill(0,1.5);
// h.Fill(1,1.0);
// h.Fill(2,1.3);
// h.Fill(3,0.9);
// h.Fill(5,1.1);
// h.Fill(6,1.2);
// h.Fill(7,1.1);
// h.Fill(8,1.3);
// h.Fill(9,2);
// h.Fill(10,2.5);
// h.Fill(11,3.3);
// h.Fill(12,5);
// h.Fill(13,6);
// h.Fill(14,6);
// h.Fill(30,8.1);
// h.Fill(31,8.3);
// h.Fill(32,8.5);
// h.Fill(33,8.2);
// h.Fill(40,2);
// h.Fill(41,2);
// h.Fill(42,2);
// h.Fill(43,2);
// h.Fill(60,1);
// h.Fill(61,1);
// h.Fill(62,1);
// h.Fill(63,1);
// h.Fill(80,-3);
// h.Fill(81,-5.5);
// h.Fill(82,-8);
// h.Fill(83,-3.2);
// h.Fill(90,1);
// h.Fill(91,1);
// h.Fill(92,1);
// h.Fill(93,1);
//
// Float_t fpr=0.1;
// TH1F hblock;
// hblock.SetName("hblock");
// q.GetBlocks(&h,fpr,&hblock);
//
// // Subtract the Block values from the original histogram bin contents
// // without scaling w.r.t. the bin size
// TH1F hdif;
// q.Add(&h,&hblock,&hdif,0,-1);
//
// TCanvas c("c","c");
// c.Divide(1,3);
// c.cd(1);
// h.SetLineWidth(2);
// h.Draw();
// hblock.Draw("same");
// c.cd(2);
// hblock.Draw();
// c.cd(3);
// hdif.SetLineWidth(2);
// hdif.Draw();
//
//
// Example 3: Measurement data (Data Mode 3)
// -----------------------------------------
//
// gSystem->Load("ncfspack");
//
// NcBlocks q;
//
// NcRandom ran;
//
// TGraphErrors gr;
// gr.SetName("Cosine");
// gr.SetTitle("Example 3 : Measurement data (Data Mode 3);x in radians;cos(x)");
//
// // Create and store some artificial measurements
// Double_t pi=acos(-1.);
// Float_t x=0;
// Float_t y=0;
// Float_t ex=0;
// Float_t ey=0;
// Int_t nloop=100;
// Int_t jpoint=0;
// Double_t step=2.*pi/float(nloop);
// Int_t itest=0;
// for (Int_t i=0; i<=nloop; i++)
// {
// y=cos(x);
// ex=0.1;
// ey=fabs(0.1*y);
// y+=ey*ran.Uniform(-1.,1.);
// itest=i%5;
// if (!itest)
// {
// itest=i;
// gr.SetPoint(jpoint,x,y);
// gr.SetPointError(jpoint,ex,ey);
// jpoint++;
// }
// x+=step;
// }
//
// Float_t fpr=0.1;
// TH1F hblock;
// hblock.SetName("hblock");
// q.GetBlocks(gr,fpr,&hblock);
//
// // Subtract the Block values from the original graph
// TGraphErrors gdif;
// q.Add(&gr,&hblock,&gdif,-1);
//
// TCanvas c("c","c");
// c.Divide(1,3);
// c.cd(1);
// gr.Draw("A*");
// hblock.Draw("same");
// c.cd(2);
// hblock.Draw();
// c.cd(3);
// gdif.Draw("A*");
//
//
// Example 4: Triggering
// ---------------------
//
// gSystem->Load("ncfspack");
//
// NcBlocks q;
//
// TH1F h("h","Example 4: Triggering;Time in sec.;Weighted counts",100,0,100);
//
// h.Fill(0,1.5);
// h.Fill(1,1);
// h.Fill(2,1.3);
// h.Fill(3,0.9);
// h.Fill(5,1.1);
// h.Fill(6,1.2);
// h.Fill(7,1.1);
// h.Fill(8,1.3);
// h.Fill(9,2);
// h.Fill(10,2.5);
// h.Fill(11,3.3);
// h.Fill(12,5);
// h.Fill(13,6);
// h.Fill(14,6);
// h.Fill(30,8.1);
// h.Fill(31,8.3);
// h.Fill(32,8.5);
// h.Fill(33,8.2);
// h.Fill(40,2);
// h.Fill(41,2);
// h.Fill(42,2);
// h.Fill(43,2);
// h.Fill(60,1);
// h.Fill(61,1);
// h.Fill(62,1);
// h.Fill(63,1);
// h.Fill(80,-3);
// h.Fill(81,-5.5);
// h.Fill(82,-8);
// h.Fill(83,-3.2);
// h.Fill(90,1);
// h.Fill(91,1);
// h.Fill(92,1);
// h.Fill(93,1);
// h.Fill(97,5);
// h.Fill(98,7);
// h.Fill(99,10);
//
// // Trigger on the first rising edge by regarding
// // the histogram data as a realtime incoming data stream
// Float_t fpr=0.1;
// Int_t ntrig=1;
// TH1F hblock;
// hblock.SetName("hblock");
// Double_t xtrig=q.GetBlocks(&h,fpr,&hblock,ntrig);
//
// cout << " Data stream triggered at : " << xtrig << endl;
//
// TCanvas c("c","c");
// h.SetLineWidth(2);
// h.Draw();
// hblock.Draw("same");
//
//
// Example 5: Real time animation
// ------------------------------
//
// gSystem->Load("ncfspack");
//
// NcBlocks q;
//
// Float_t fpr=0.1;
// Int_t nevt=100;
// Float_t arr[nevt];
//
// Float_t t=0;
// Int_t low=nevt/4;
// Int_t mid=nevt/2;
// Int_t up=3*nevt/4;
// Float_t add=0;
// TH1F hblock;
// hblock.SetName("hblock");
// TCanvas c("c","c");
// // Construct and store artificial event times
// for (Int_t i=1; i<=nevt; i++)
// {
// if (i<low)
// {
// add=1;
// }
// else if (i<mid)
// {
// add=0.1;
// }
// else if (i<up)
// {
// add=1;
// }
// else
// {
// add=0.2;
// }
// t+=add;
// arr[i-1]=t;
//
// // Display the Block histogram step by step
// if (i>1)
// {
// q.GetBlocks(i,arr,fpr,&hblock);
// hblock.Draw();
// c.Update();
// gSystem->Sleep(25);
// }
// }
//
//--- Author: Nick van Eijndhoven, IIHE-VUB, Brussel, September 7, 2021 08:06Z
//- Modified: Nick van Eijndhoven, IIHE-VUB, Brussel, December 5, 2024 14:54Z

Definition at line 16 of file NcBlocks.h.

Public Member Functions

 NcBlocks ()
 
 NcBlocks (const NcBlocks &q)
 
virtual ~NcBlocks ()
 
Int_t Add (TGraph *gr, TH1 *h, TGraph *gout, Double_t c, Double_t d=0)
 
Int_t Add (TH1 *h1, TH1 *h2, TH1 *hout, Bool_t scale, Double_t c, Double_t d=0)
 
Int_t Divide (TGraph *gr, TH1 *h, TGraph *gout, Double_t c, Double_t d=0)
 
Int_t Divide (TH1 *h1, TH1 *h2, TH1 *hout, Bool_t scale, Double_t c, Double_t d=0)
 
Double_t GetBlocks (Int_t n, Double_t *arr, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Double_t GetBlocks (Int_t n, Float_t *arr, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Int_t GetBlocks (Int_t nr, Double_t *arr, TH1 *hout, Int_t n, Int_t mode=0)
 
Int_t GetBlocks (Int_t nr, Float_t *arr, TH1 *hout, Int_t n, Int_t mode=0)
 
Double_t GetBlocks (NcSample s, Int_t i, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Int_t GetBlocks (NcSample s, Int_t i, TH1 *hout, Int_t n, Int_t mode=0)
 
Double_t GetBlocks (NcSample s, TString name, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Int_t GetBlocks (NcSample s, TString name, TH1 *hout, Int_t n, Int_t mode=0)
 
Int_t GetBlocks (TGraph *gr, TH1 *hout, Int_t n, Int_t mode=0)
 
Double_t GetBlocks (TGraph gr, Double_t nrms, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Double_t GetBlocks (TGraph gr, TF1 f, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Double_t GetBlocks (TGraph gr, TString f, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Double_t GetBlocks (TGraphErrors gr, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Double_t GetBlocks (TH1 *hin, Double_t fpr, TH1 *hout, Int_t ntrig=0)
 
Int_t GetBlocks (TH1 *hin, TH1 *hout, Int_t n, Int_t mode=0)
 
Int_t Rebin (TH1 *hin, TH1 *hout, Bool_t scale, Int_t nbins=0, Double_t xmin=0, Double_t xmax=-1)
 

Protected Member Functions

Double_t GetBlockFitness (Double_t n, Double_t len)
 
Double_t GetPrior (Int_t n, Double_t fpr)
 

Protected Attributes

Int_t fMode
 

Constructor & Destructor Documentation

◆ NcBlocks() [1/2]

NcBlocks::NcBlocks ( )
// Default constructor.

Definition at line 395 of file NcBlocks.cxx.

◆ ~NcBlocks()

NcBlocks::~NcBlocks ( )
virtual
// Default destructor.

Definition at line 406 of file NcBlocks.cxx.

◆ NcBlocks() [2/2]

NcBlocks::NcBlocks ( const NcBlocks & q)
// Copy constructor.

Definition at line 415 of file NcBlocks.cxx.

Member Function Documentation

◆ Add() [1/2]

Int_t NcBlocks::Add ( TGraph * gr,
TH1 * h,
TGraph * gout,
Double_t c,
Double_t d = 0 )
// Provide the TGraph gout=gr+c*h+d, where "h" is a 1-dimensional histogram.
// So, for c=-1 and d=0, the values contained in the histogram "h" will be
// subtracted from the corresponding values of the input graph "gr".
//
// Notes :
// -------
// 1) Both graphs "gr" and "gout" as well as histogram "h" must be existing.
// 2) In case both "gr" and "gout" are TGraphErrors objects, the errors
// of "gout" will be set to the values of the errors of the input graph "gr".
//
// The return value indicates whether an error occured (1) or not (0).
//
// This facility is mainly intended for "adding" the variable binned Bayesian Block values
// corresponding to the mode 3 data contained in the graph "gr".
// However, it can be applied to any combination of input graph "gr" and histogram "h".
//
// The default value is d=0.

Definition at line 2090 of file NcBlocks.cxx.

◆ Add() [2/2]

Int_t NcBlocks::Add ( TH1 * h1,
TH1 * h2,
TH1 * hout,
Bool_t scale,
Double_t c,
Double_t d = 0 )
// Provide the 1-dimensional histogram hout=h1+c*h2+d.
// So, for c=-1 and d=0, the values contained in the histogram "h2" will be
// subtracted from the corresponding bin values of the input histogram "h1".
// The output histogram "hout" will be given the same binning as the histogram "h1".
//
// Note : All histograms "h1", "h2" and "hout" must be existing 1-dimensional histograms.
//
// This facility is mainly intended for "adding" the variable binned Bayesian Block values
// (contained in "h2") to the corresponding values contained in the bins of "h1".
// However, it can be applied to other combinations of 1-dimensional histograms as well.
//
// All provided histograms have to be 1-dimensional and histograms with
// variable bin sizes are supported. However, all bin sizes of "h1"
// have to be smaller than or equal to the smallest bin size of "h2".
// Obviously, this is always the case when "h2" contains the Bayesian Block
// partitions of "h1".
//
// The return value indicates whether an error occured (1) or not (0).
//
// The input parameter "scale" allows to scale (kTRUE) or not scale (kFALSE)
// the bin content of "h2" to be "added", to the corresponding bin width of "h1".
//
// Note :
// ------
// Since this facility is mainly intended for "adding" variable binned Bayesian Blocks,
// scaling should *not* be used in case of mode 3 data, whereas for mode 2 data
// the use of scaling will correctly reflect the resulting (event) counts in each bin.
//
// The default value is d=0.

Definition at line 1924 of file NcBlocks.cxx.

◆ Divide() [1/2]

Int_t NcBlocks::Divide ( TGraph * gr,
TH1 * h,
TGraph * gout,
Double_t c,
Double_t d = 0 )
// Provide the TGraph gout=d+gr/(c*h), where "h" is a 1-dimensional histogram.
//
// Notes :
// -------
// 1) Both graphs "gr" and "gout" as well as histogram "h" must be existing.
// 2) In case both "gr" and "gout" are TGraphErrors objects, the errors
// of "gout" will be set to the values of the errors of the input graph "gr".
//
// The return value indicates whether an error occured (1) or not (0).
//
// This facility is mainly intended for dividing the mode 3 data contained in the graph "gr"
// by the corresponding variable binned Bayesian Block values contained in "h".
// However, it can be applied to any combination of input graph "gr" and histogram "h".
//
// The default value is d=0.

Definition at line 2380 of file NcBlocks.cxx.

◆ Divide() [2/2]

Int_t NcBlocks::Divide ( TH1 * h1,
TH1 * h2,
TH1 * hout,
Bool_t scale,
Double_t c,
Double_t d = 0 )
// Provide the 1-dimensional histogram hout=d+h1/(c*h2).
// The output histogram "hout" will be given the same binning as the histogram "h1".
//
// Note : All histograms "h1", "h2" and "hout" must be existing 1-dimensional histograms.
//
// This facility is mainly intended for dividing the values contained in the bins of "h1"
// by the corresponding variable binned Bayesian Block values contained in "h2".
// However, it can be applied to other combinations of 1-dimensional histograms as well.
//
// All provided histograms have to be 1-dimensional and histograms with
// variable bin sizes are supported. However, all bin sizes of "h1"
// have to be smaller than or equal to the smallest bin size of "h2".
// Obviously, this is always the case when "h2" contains the Bayesian Block
// partitions of "h1".
//
// The return value indicates whether an error occured (1) or not (0).
//
// The input parameter "scale" allows to scale (kTRUE) or not scale (kFALSE)
// the bin content of "h2" to the corresponding bin width of "h1".
//
// Note :
// ------
// Since this facility is mainly intended for division by variable binned Bayesian Blocks,
// scaling should *not* be used in case of mode 3 data, whereas for mode 2 data
// the use of scaling will correctly reflect the resulting (event) counts in each bin.
//
// The default value is d=0.

Definition at line 2200 of file NcBlocks.cxx.

◆ GetBlockFitness()

Double_t NcBlocks::GetBlockFitness ( Double_t n,
Double_t len )
protected
// Internal member function to provide the fitness value for a certain block content
// in the case of Data Mode 1 or 2.
//
// Input arguments :
// -----------------
// n : The (weighted) number of events in the block
// len : The length of the block
//
// The length of the block represents the summed time span of the contained Data Cells.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 490 of file NcBlocks.cxx.

◆ GetBlocks() [1/15]

Double_t NcBlocks::GetBlocks ( Int_t n,
Double_t * arr,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for the "n" data recordings (Data Mode 1)
// contained in the data array "arr" with a false positive rate "fpr",
// and provide the results in the 1-D histogram "hout".
// A common case is where the array "arr" contains recorded event times.
//
// Notes :
// -------
// 1) The data in array "arr" are interpreted as Data Mode 1.
// For Data Mode 2 or Data Mode 3 treatment, please use the corresponding GetBlocks() function.
// 2) The data elements in the array "arr" do not need to be ordered.
// 3) "hout" must be an existing 1-dimensional histogram.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the event rate based on the recordings in the provided array.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 932 of file NcBlocks.cxx.

◆ GetBlocks() [2/15]

Double_t NcBlocks::GetBlocks ( Int_t n,
Float_t * arr,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for the "n" data recordings (Data Mode 1)
// contained in the data array "arr" with a false positive rate "fpr",
// and provide the results in the 1-D histogram "hout".
// A common case is where the array "arr" contains recorded event times.
//
// Notes :
// -------
// 1) The data in array "arr" are interpreted as Data Mode 1.
// For Data Mode 2 or Data Mode 3 treatment, please use the corresponding GetBlocks() function.
// 2) The data elements in the array "arr" do not need to be ordered.
// 3) "hout" must be an existing 1-dimensional histogram.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the event rate based on the recordings in the provided array.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 1011 of file NcBlocks.cxx.

◆ GetBlocks() [3/15]

Int_t NcBlocks::GetBlocks ( Int_t nr,
Double_t * arr,
TH1 * hout,
Int_t n,
Int_t mode = 0 )
// Get the block partitions consisting of "n" consecutive elements of the "nr" data recordings
// contained in the data array "arr", and provide the results in the 1-D histogram "hout".
//
// This facility provides an efficient way to identify pedestal variations in case these
// might be expected to occur after recording "n" samples due to the specific DAQ design.
//
// mode = 0 --> Use the mean as average value
// 1 --> Use the median as average value
// 2 --> Use the Root Mean Square (RMS) as average value
// Note : This is NOT the RMS deviation defined as sqrt(variance)
//
// The default value is mode=0;
//
// Notes :
// -------
// 1) The data elements in the array "arr" do not need to be ordered.
// 2) "hout" must be an existing 1-dimensional histogram.
// 3) The blocks represent the bins of "hout", which may have variable length
// in case the sampling was not continuous.
// As such, the structure of the output histogram is comparable to the result
// of a Bayesian Block analysis.
//
// The returned value is the number of produced blocks.
// In case of inconsistent input, the value 0 is returned.

Definition at line 1667 of file NcBlocks.cxx.

◆ GetBlocks() [4/15]

Int_t NcBlocks::GetBlocks ( Int_t nr,
Float_t * arr,
TH1 * hout,
Int_t n,
Int_t mode = 0 )
// Get the block partitions consisting of "n" consecutive elements of the "nr" data recordings
// contained in the data array "arr", and provide the results in the 1-D histogram "hout".
//
// This facility provides an efficient way to identify pedestal variations in case these
// might be expected to occur after recording "n" samples due to the specific DAQ design.
//
// mode = 0 --> Use the mean as average value
// 1 --> Use the median as average value
// 2 --> Use the Root Mean Square (RMS) as average value
// Note : This is NOT the RMS deviation defined as sqrt(variance)
//
// The default value is mode=0;
//
// Notes :
// -------
// 1) The data elements in the array "arr" do not need to be ordered.
// 2) "hout" must be an existing 1-dimensional histogram.
// 3) The blocks represent the bins of "hout", which may have variable length
// in case the sampling was not continuous.
// As such, the structure of the output histogram is comparable to the result
// of a Bayesian Block analysis.
//
// The returned value is the number of produced blocks.
// In case of inconsistent input, the value 0 is returned.

Definition at line 1741 of file NcBlocks.cxx.

◆ GetBlocks() [5/15]

Double_t NcBlocks::GetBlocks ( NcSample s,
Int_t i,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for the (Data Mode 1) i-th variable of NcSample "s"
// with a false positive rate "fpr", and provide the results in 1-D histogram "hout".
// A common case is where the NcSample contains recorded event times.
//
// Notes :
// -------
// 1) The Store Mode of the NcSample must be activated.
// 2) "hout" must be an existing 1-dimensional histogram.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the event rate based on the recordings in the provided NcSample.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 795 of file NcBlocks.cxx.

◆ GetBlocks() [6/15]

Int_t NcBlocks::GetBlocks ( NcSample s,
Int_t i,
TH1 * hout,
Int_t n,
Int_t mode = 0 )
// Get the block partitions consisting of "n" consecutive samplings for the
// i-th variable of NcSample "s", with as block height the mean, median or RMS value
// of the contained "n" samples and provide the results in the 1-D histogram "hout".
//
// This facility provides an efficient way to identify pedestal variations in case these
// might be expected to occur after recording "n" samples due to the specific DAQ design.
//
// mode = 0 --> Use the mean as average value
// 1 --> Use the median as average value
// 2 --> Use the Root Mean Square (RMS) as average value
// Note : This is NOT the RMS deviation defined as sqrt(variance)
//
// The default value is mode=0;
//
// Notes :
// -------
// 1) The Store Mode of the NcSample must be activated.
// 2) "hout" must be an existing 1-dimensional histogram.
// 3) The blocks represent the bins of "hout", which may have variable length
// in case the sampling was not continuous.
// As such, the structure of the output histogram is comparable to the result
// of a Bayesian Block analysis.
//
// The returned value is the number of produced blocks.
// In case of inconsistent input, the value 0 is returned.

Definition at line 1555 of file NcBlocks.cxx.

◆ GetBlocks() [7/15]

Double_t NcBlocks::GetBlocks ( NcSample s,
TString name,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for the (Data Mode 1) named variable of NcSample "s"
// with a false positive rate "fpr", and provide the results in 1-D histogram "hout".
// A common case is where the NcSample contains recorded event times.
//
// Notes :
// -------
// 1) The Store Mode of the NcSample must be activated.
// 2) "hout" must be an existing 1-dimensional histogram.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the event rate based on the recordings in the provided NcSample.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 888 of file NcBlocks.cxx.

◆ GetBlocks() [8/15]

Int_t NcBlocks::GetBlocks ( NcSample s,
TString name,
TH1 * hout,
Int_t n,
Int_t mode = 0 )
// Get the block partitions consisting of "n" consecutive samplings for the
// named variable of NcSample "s", with as block height the mean, median or RMS value
// of the contained "n" samples and provide the results in the 1-D histogram "hout".
//
// This facility provides an efficient way to identify pedestal variations in case these
// might be expected to occur after recording "n" samples due to the specific DAQ design.
//
// mode = 0 --> Use the mean as average value
// 1 --> Use the median as average value
// 2 --> Use the Root Mean Square (RMS) as average value
// Note : This is NOT the RMS deviation defined as sqrt(variance)
//
// The default value is mode=0;
//
// Notes :
// -------
// 1) The Store Mode of the NcSample must be activated.
// 2) "hout" must be an existing 1-dimensional histogram.
// 3) The blocks represent the bins of "hout", which may have variable length
// in case the sampling was not continuous.
// As such, the structure of the output histogram is comparable to the result
// of a Bayesian Block analysis.
//
// The returned value is the number of produced blocks.
// In case of inconsistent input, the value 0 is returned.

Definition at line 1628 of file NcBlocks.cxx.

◆ GetBlocks() [9/15]

Int_t NcBlocks::GetBlocks ( TGraph * gr,
TH1 * hout,
Int_t n,
Int_t mode = 0 )
// Get the block partitions consisting of "n" consecutive samples for measurements
// of an observable with as block height the mean, median or RMS of the values
// of the contained "n" samples and provide the results in the 1-D histogram "hout".
//
// This facility provides an efficient way to identify pedestal variations in case these
// might be expected to occur after recording "n" samples due to the specific DAQ design.
//
// mode = 0 --> Use the mean as average value
// 1 --> Use the median as average value
// 2 --> Use the Root Mean Square (RMS) as average value
// Note : This is NOT the RMS deviation defined as sqrt(variance)
//
// The default value is mode=0;
//
// Notes :
// -------
// 1) "hout" must be an existing 1-dimensional histogram.
// 2) The blocks represent the bins of "hout", which may have variable length
// in case the sampling was not continuous.
// As such, the structure of the output histogram is comparable to the result
// of a Bayesian Block analysis.
//
// The returned value is the number of produced blocks.
// In case of inconsistent input, the value 0 is returned.

Definition at line 1815 of file NcBlocks.cxx.

◆ GetBlocks() [10/15]

Double_t NcBlocks::GetBlocks ( TGraph gr,
Double_t nrms,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for measurements of an observable (Data Mode 3)
// with a false positive rate "fpr", and provide the results in 1-D histogram "hout".
//
// Notes :
// -------
// 1) "hout" must be an existing 1-dimensional histogram.
// 2) The other member function with TGraphErrors input provides more flexibilty.
//
// The error of each y-value is determined by "nrms" times the RMS deviation of all the y-values,
// which often provides an efficient way to ignore noise variations of a background pedestal.
// This provides an easy way to perform quickly a Bayesian Block analysis directly
// on a TGraph object instead of having to convert it first into a TGraphErrors object.
// However, the error setting facility provided here is rather limited, so it
// is intended to serve only for simple situations.
// For more flexibility and accuracy, please refer to the other member function that
// takes a TGraphErrors object as input, or refer to the class NcSample which
// contains a facility to extend TGraph objects into TGraphError objects.
//
// Note :
// ------
// It is essential that the errors on the y-values are provided, since they are
// used as weights in the statistical analysis.
// The errors on the x-values are omitted, since they are not used in the process.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the measured value based on the recordings in the provided TGraphErrors object.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 1347 of file NcBlocks.cxx.

◆ GetBlocks() [11/15]

Double_t NcBlocks::GetBlocks ( TGraph gr,
TF1 f,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for measurements of an observable (Data Mode 3)
// with a false positive rate "fpr", and provide the results in 1-D histogram "hout".
//
// Notes :
// -------
// 1) "hout" must be an existing 1-dimensional histogram.
// 2) The other member function with TGraphErrors input provides more flexibilty.
//
// The error of each y-value is determined by the absolute value of f(y).
// This provides an easy way to perform quickly a Bayesian Block analysis directly
// on a TGraph object instead of having to convert it first into a TGraphErrors object.
// However, the error setting facility provided here is rather limited, so it
// is intended to serve only for simple situations.
// For more flexibility and accuracy, please refer to the other member function that
// takes a TGraphErrors object as input, or refer to the class NcSample which
// contains a facility to extend TGraph objects into TGraphError objects.
//
// Note :
// ------
// It is essential that the errors on the y-values are provided, since they are
// used as weights in the statistical analysis.
// The errors on the x-values are omitted, since they are not used in the process.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the measured value based on the recordings in the provided TGraphErrors object.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 1211 of file NcBlocks.cxx.

◆ GetBlocks() [12/15]

Double_t NcBlocks::GetBlocks ( TGraph gr,
TString f,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for measurements of an observable (Data Mode 3)
// with a false positive rate "fpr", and provide the results in 1-D histogram "hout".
//
// Notes :
// -------
// 1) "hout" must be an existing 1-dimensional histogram.
// 2) The other member function with TGraphErrors input provides more flexibilty.
//
// The error of each y-value is determined by the absolute value of f(y), where the
// function is described by the input argument "f" following the TF1 string format convention.
// This provides an easy way to perform quickly a Bayesian Block analysis directly
// on a TGraph object instead of having to convert it first into a TGraphErrors object.
// However, the error setting facility provided here is rather limited, so it
// is intended to serve only for simple situations.
// For more flexibility and accuracy, please refer to the other member function that
// takes a TGraphErrors object as input, or refer to the class NcSample which
// contains a facility to extend TGraph objects into TGraphError objects.
//
// Note :
// ------
// It is essential that the errors on the y-values are provided, since they are
// used as weights in the statistical analysis.
// The errors on the x-values are omitted, since they are not used in the process.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the measured value based on the recordings in the provided TGraphErrors object.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 1278 of file NcBlocks.cxx.

◆ GetBlocks() [13/15]

Double_t NcBlocks::GetBlocks ( TGraphErrors gr,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for measurements of an observable (Data Mode 3)
// with a false positive rate "fpr", and provide the results in 1-D histogram "hout".
//
// Notes :
// -------
// 1) It is essential that the errors on the y-values are provided, since they are
// used as weights in the statistical analysis.
// The errors on the x-values may be omitted, since they are not used in the process.
// 2) "hout" must be an existing 1-dimenstional histogram.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the measured value based on the recordings in the provided TGraphErrors object.
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 1090 of file NcBlocks.cxx.

◆ GetBlocks() [14/15]

Double_t NcBlocks::GetBlocks ( TH1 * hin,
Double_t fpr,
TH1 * hout,
Int_t ntrig = 0 )
// Get the Bayesian Block partitions for the binned data (Data Mode 2) of histogram "hin"
// with a false positive rate "fpr", and provide the results in the 1-D histogram "hout".
//
// Note : Both "hin" and "hout" must be existing 1-dimensional histograms.
//
// Each new block is started at a so called Change Point, to indicate a significant change
// in the bin contents of the input histogram "hin".
// The various Change Points represent the start of the various (variable) sized bins
// of the resulting histogram "hout".
// Since the data treatment is inherently sequential, the user may use the argument "ntrig"
// to trigger c.q. stop after the occurrence of ntrig Change Points.
// For instance, an online trigger system may be obtained by specifying ntrig=1.
//
// Meaning of the input argument "ntrig" :
// ---------------------------------------
// ntrig >0 : Only consider Change Points indicating a rising edge
// <0 : Only consider Change Points indicating a falling edge
// =0 : No triggering c.q. early stopping of the data processing will be performed
//
// The default value is ntrig=0.
//
// The returned value is the "X-value" of the selected Change Point, e.g. trigger time.
// In case ntrig=0 the return value corresponds to the 1st Change Point, irrespective
// whether that represents a rising or falling edge.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 523 of file NcBlocks.cxx.

◆ GetBlocks() [15/15]

Int_t NcBlocks::GetBlocks ( TH1 * hin,
TH1 * hout,
Int_t n,
Int_t mode = 0 )
// Get the block partitions consisting of "n" consecutive bins for binned data
// contained in histogram "hin" with as block height the mean, median or RMS value
// of the contained "n" bins and provide the results in the 1-D histogram "hout".
//
// This facility provides an efficient way to identify pedestal variations in case these
// might be expected to occur after recording "n" samples due to the specific DAQ design.
//
// mode = 0 --> Use the mean as average value
// 1 --> Use the median as average value
// 2 --> Use the Root Mean Square (RMS) as average value
// Note : This is NOT the RMS deviation defined as sqrt(variance)
//
// The default value is mode=0;
//
// Notes :
// -------
// 1) "hout" must be an existing 1-dimensional histogram.
// 2) The blocks represent the bins of "hout", which may have variable length
// in case the sampling was not continuous.
// As such, the structure of the output histogram is comparable to the result
// of a Bayesian Block analysis.
//
// The returned value is the number of produced blocks.
// In case of inconsistent input, the value 0 is returned.

Definition at line 1420 of file NcBlocks.cxx.

◆ GetPrior()

Double_t NcBlocks::GetPrior ( Int_t n,
Double_t fpr )
protected
// Internal member function to provide the prior fitness value for each individual block.
// The returned value corresponds to -(ncp_prior) of the article of J.D. Scargle et al.
//
// Input arguments :
// -----------------
// n : The number of Data Cells
// fpr : The requested false positive rate
//
// Note :
// ------
// For Data Mode 1 and 2, the result is rather accurate on the full fpr interval [0,1].
// For Data Mode 3 the fit for fpr=0.05 was given in the article of J.D. Scargle et al.
// in the form : prior=c+s*log10(n) with c=1.32 and s=0.577.
// For the fpr values of 0.01, 0.1, 0.2, 0.3, 0.4 and 0.5 the data were read off from
// Fig. 6 in the article of J.D. Scargle et al. and fits of prior vs. N were made to provide
// the parameters c and s for each fpr value.
// These data sets of c and s were then used to provide fits of c vs. fpr and s vs. fpr,
// which allows to determine the parameter values of c and s for a certain fpr value,
// and subsequently the value of the corresponding prior.
//
// In case of inconsistent input, the value 0 is returned.

Definition at line 426 of file NcBlocks.cxx.

◆ Rebin()

Int_t NcBlocks::Rebin ( TH1 * hin,
TH1 * hout,
Bool_t scale,
Int_t nbins = 0,
Double_t xmin = 0,
Double_t xmax = -1 )
// Provide the 1-dimensional histogram "hout" as a uniformly binned version of the
// input 1-dimensional histogram "hin" over the interval [xmin,xmax].
// This will for instance allow a Fourier analysis of a Bayesian Block result in the time domain.
//
// Note : Both histograms "hin" and "hout" must be existing 1-dimensional histograms.
//
// The bin size of "hout" has to be smaller than or equal to the smallest bin size of
// "hin" encountered in the interval [xmin,xmax] (see also notes below).
//
// Function arguments :
// --------------------
// hin : Pointer to the input histogram
// hout : Pointer to the output histogram
// scale : Scale the bin content to the bin width (kTRUE) or not (kFALSE)
// nbins : The number of bins for the output histogram (see notes below)
// xmin : The minimal x-value for the output histogram (see notes below)
// xmax : The maximal x-value for the output histogram (see notes below)
//
// Notes :
// -------
// 1) Since this facility is mainly intended for re-binning variable binned Bayesian Blocks,
// scaling should *not* be used in case of mode 3 data, whereas for mode 2 data
// the use of scaling will correctly reflect the number of (event) counts in each bin.
// 2) If nbins<1 the bin size of "hout" will automatically be set to the smallest bin size of
// "hin" that is encountered in the interval [xmin,xmax].
// 3) In case xmax<xmin, the xmin and xmax values of the input histogram are used.
//
// The return value is the number of bins of the produced output histogram "hout".
//
// The default values are nbins=0, xmin=0 and xmax=-1.

Definition at line 2507 of file NcBlocks.cxx.

Member Data Documentation

◆ fMode

Int_t NcBlocks::fMode
protected

Definition at line 44 of file NcBlocks.h.

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