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;
// const 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, UTC June 14, 2026  11:07

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 2126 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 1960 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 2416 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 2236 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 "abs(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.
// 4) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 962 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 "abs(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.
// 4) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 1042 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 1703 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 1777 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 "abs(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.
// 3) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 808 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 1591 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 "abs(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.
// 3) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 917 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 1664 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 1851 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 "abs(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.
// 3) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 1382 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 "abs(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.
// 3) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 1244 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 "abs(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.
// 3) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 1312 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 "abs(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.
// 3) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 1122 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 "abs(fpr)", and provide the results in the 1-D histogram "hout".
//
// Notes :
// -------
// 1) Both "hin" and "hout" must be existing 1-dimensional histograms.
// 2) For fpr<0 a fast(er) procedure will be applied by skipping the already created blocks in the processing.
//
// 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 1456 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 2543 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:

• ncfspack/source/NcBlocks.h
• ncfspack/source/NcBlocks.cxx