TTask derived class to perform Chi-squared track fitting. More...

#include "IceChi2.h"

Inheritance diagram for IceChi2:

Detailed Description

TTask derived class to perform Chi-squared track fitting.

Copyright(c) 2003, IceCube Experiment at the South Pole. All rights reserved.
 
Author: The IceCube NCFS-based Offline Project.
Contributors are mentioned in the code where appropriate.
 
Permission to use, copy, modify and distribute this software and its
documentation strictly for non-commercial purposes is hereby granted
without fee, provided that the above copyright notice appears in all
copies and that both the copyright notice and this permission notice
appear in the supporting documentation.
The authors make no claims about the suitability of this software for
any purpose. It is provided "as is" without express or implied warranty.

// Class IceChi2
// TTask derived class to perform track fitting via chi-squared minimisation.
//
// In case an event has been rejected by an NcEventSelector (based) processor,
// this task (and its sub-tasks) is not executed.
//
// For the minimisation process the TFitter facility, which is basically Minuit,
// is used. Minimisation is performed by invokation of the SIMPLEX method,
// followed by an invokation of HESSE to determine the uncertainties on the results.
// The statistics of the TFitter result are stored as an NcSignal object
// in the track, which can be obtained via the GetFitDetails memberfunction.
// After the chi-squared minimisation procedure has been performed, an overall
// plausibility for the fitted track will be determined based on a convoluted
// Pandel pdf value for each used hit.
// This track plausibility is expressed in terms of a Bayesian psi value
// w.r.t. a Convoluted Pandel PDF.
// The Baysian psi value is defined as -loglikelihood in a decibel scale.
// This implies psi=-10*log10(L) where L=p(D|HI) being the likelihood of
// the data D under the hypothesis H and prior information I.
// Since all (associated) hits contribute independently to the Bayesian psi
// value, this psi value is built up by summation of the various hit contributions.
// As such, the FitDetails entries contain the statistics of all the different
// hit contributions, like PsiMedian, PsiMean, and PsiSigma.
// The Bayesian psi value is available in the fit details under the name "PsiSum".
// In addition the standard Minuit results like IERFIT, FCN, EDM etc... are
// also available from the FitDetails.
//
// The convoluted Pandel value is evaluated in various areas in the distance-time
// space as described in Astropart. Phys. 28 (2007) 456-462 by N. van Eijndhoven,
// O. Fadiran and G. Japaridze
// In case the distance-time point of a certain hit falls outside the
// validity rectangle, the point is moved onto the corresponding side location
// of the rectangle. For this new location the Pandel value is evaluated for
// this hit and an extra penalty is added to the corresponding psi value
// for this hit. 
// By default this penalty value amounts to 0 dB, but the user can
// modify this penalty value via the memberfunction SetPenalty.
// This allows investigation/tuning of the sensitivity to hits with
// extreme distance and/or time residual values.
//
// A separate treatment of the phase and group velocities is introduced
// which will provide more accurate time residuals due to the different
// velocities of the Cerenkov wave front (v_phase) and the actually detected
// photons (v_group).
// This distinction between v_phase and v_group can be (de)activated via the
// memberfunction SetVgroupUsage(). By default the distinction between v_phase
// and v_group is activated in the constructor of this class.
//
// Use the UseTracks memberfunction to specify the first guess tracks
// to be processed by the minimiser.
// By default only the first encountered IceDwalkA and/or IceDwalkI track(s)
// will be processed.
//
// Use the SelectHits memberfunction to specify the hits to be used.
// By default all hit cleaning survived hits are used of those detector systems
// (e.g. Amanda, InIce) that were used to construct the first guess track.
//
// Information about the actual parameter settings can be found in the event
// structure itself via the device named "IceChi2".
//
// The fit processor printlevel can be selected via the memberfunction
// SetPrintLevel. By default all printout is suppressed (i.e. level=-2).
//
// An example of how to invoke this processor after Xtalk, hit cleaning
// and a direct walk first guess estimate can be found in the ROOT example
// macro icechi2.cc which resides in the /macros subdirectory.
// 
// The minimisation results are stored in the IceEvent structure as
// tracks with as default the name "IceChi2".
// A suffix "A" for an Amanda (OM) track, a suffix "I" for an InIce (DOM) track
// or a suffix "C" for a combined Amanda/InIce (i.e. OM and DOM) track will be added
// to the name automatically (just like the first guess results of e.g. IceDwalk).
// This track name identifier can be modified by the user via the
// SetTrackName() memberfunction. This will allow unique identification
// of tracks which are produced when re-processing existing data with
// different criteria.
// Note that a suffix "A", "I" or "C" will always be generated automatically.
// By default the charge of the produced tracks is set to 0, since
// no distinction can be made between positive or negative tracks.
// However, the user can define the track charge by invokation
// of the memberfunction SetCharge().
// This facility may be used to distinguish tracks produced by the
// various reconstruction algorithms in a (3D) colour display
// (see the class NcHelix for further details).  
// A pointer to the first guess track which was used as input is available
// via the GetParentTrack facility of these "IceChi2" tracks.
// Furthermore, all the hits that were used in the minisation are available
// via the GetSignal facility of a certain track.
//
// An example of how the various data can be accessed is given below,
// where "evt" indicates the pointer to the IceEvent structure.
//
// Example for accessing data :
// ----------------------------
// TObjArray* tracks=evt->GetTracks("IceChi2");
// if (!tracks) return;
// NcPosition* r0=0;
// Float_t psi=0;
// for (Int_t jtk=0; jtk<tracks->GetEntries(); jtk++)
// {
//  NcTrack* tx=(NcTrack*)tracks->At(jtk);
//  if (!tx) continue;
//  tx->Data("sph");
//  r0=tx->GetReferencePoint();
//  if (r0) r0->Data();
//  sx=(NcSignal*)tx->GetFitDetails();
//  if (sx) psi=sx->GetSignal("PsiSum");
//  NcTrack* tx2=tx->GetParentTrack();
//  if (!tx2) continue;
//  tx2->Data("sph");
//  r0=tx2->GetReferencePoint();
//  if (r0) r0->Data();
// }
//
// Notes :
// -------
// 1) This processor only works properly on data which are Time and ADC
//    calibrated and contain tracks from first guess algorithms like
//    e.g. IceDwalk.
// 2) In view of the usage of TFitter/Minuit minimisation, a global pointer
//    to the instance of this class (gIceChi2) and a global static
//    wrapper function (IceChi2FCN) have been introduced, to allow the
//    actual minimisation to be performed via the memberfunction FitFCN.
//    This implies that in a certain processing job only 1 instance of
//    this IceChi2 class may occur.
//
//--- Author: Nick van Eijndhoven 16-may-2006 Utrecht University
//- Modified: NvE $Date: 2012-01-03 14:30:57 +0100 (Tue, 03 Jan 2012) $ NCFS

Definition at line 22 of file IceChi2.h.

Public Member Functions
	IceChi2 (const char name="", const char title="")

virtual	~IceChi2 ()

virtual void	Exec (Option_t *opt)

void	FitFCN (Int_t &, Double_t , Double_t &, Double_t , Int_t)

Double_t	GetPsi (NcTrack *t)

void	SelectHits (Int_t mode=1)

void	SetCharge (Float_t charge)

void	SetPenalty (Float_t val)

void	SetPrintLevel (Int_t level)

void	SetTrackName (TString s)

void	SetVgroupUsage (Int_t flag)

void	UseTracks (TString classname, Int_t n=-1)

Protected Attributes
Float_t	fCharge

IceEvent *	fEvt

Int_t	fFirst

NcSignal *	fFitstats

TFitter *	fFitter

TObjArray *	fHits

Float_t	fPenalty

Int_t	fPrint

NcSample	fPsistats

Int_t	fSelhits

NcTrack *	fTkfit

TString	fTrackname

TObjArray *	fUseNames

TArrayI *	fUseNtk

Int_t	fVgroup

Constructor & Destructor Documentation

◆ IceChi2()

IceChi2::IceChi2	(	const char *	name = "",
		const char *	title = "" )

// Default constructor.

Definition at line 168 of file IceChi2.cxx.

◆ ~IceChi2()

IceChi2::~IceChi2 ( )

virtual

// Default destructor.

Definition at line 195 of file IceChi2.cxx.

Member Function Documentation

◆ Exec()

void IceChi2::Exec ( Option_t * opt )

virtual

// Implementation of the hit fitting procedure.

Definition at line 235 of file IceChi2.cxx.

◆ FitFCN()

void IceChi2::FitFCN	(	Int_t &	,
		Double_t *	,
		Double_t &	f,
		Double_t *	x,
		Int_t	)

// The chi-squared function used for the minimisation process.

Definition at line 695 of file IceChi2.cxx.

◆ GetPsi()

Double_t IceChi2::GetPsi ( NcTrack * t )

// Provide Bayesian psi value for a track w.r.t. a Convoluted Pandel PDF.
// The Baysian psi value is defined as -loglikelihood in a decibel scale.
// This implies psi=-10*log10(L) where L=p(D|HI) being the likelihood of
// the data D under the hypothesis H and prior information I.
// In case of error or incomplete information a psi value of -1 is returned.

Definition at line 765 of file IceChi2.cxx.

◆ SelectHits()

void IceChi2::SelectHits ( Int_t mode = 1 )

// Specification of the hits to be used in the minimisation.
//
// mode = 0 : All hit cleaning survived hits of the complete event are used
//        1 : Only the associated hits are used for each first guess track
//        2 : All hit cleaning survived hits are used of those detector systems
//            (e.g. Amanda, InIce) that were used to construct the first guess track.
//
// By default mode=2 is set in the constructor of this class.

Definition at line 616 of file IceChi2.cxx.

◆ SetCharge()

void IceChi2::SetCharge ( Float_t charge )

// Set user defined charge for the produced tracks.
// This allows identification of these tracks on color displays.
// By default the produced tracks have charge=0 which is set in the
// constructor of this class.

Definition at line 666 of file IceChi2.cxx.

◆ SetPenalty()

void IceChi2::SetPenalty ( Float_t val )

// Set user defined psi penalty value (in dB) for distance-time points that
// fall outside the validity rectangle.
// This allows investigation/tuning of the sensitivity to hits with
// extreme distance and/or time residual values.
// By default the penalty val=0 is set in the constructor of this class.

Definition at line 680 of file IceChi2.cxx.

◆ SetPrintLevel()

void IceChi2::SetPrintLevel ( Int_t level )

// Set the fitter (Minuit) print level.
// See the TFitter and TMinuit docs for details.
//
// Note : level=-2 suppresses also all fit processor warnings.
//        
// The default in the constructor is level=-2. 

Definition at line 544 of file IceChi2.cxx.

◆ SetTrackName()

void IceChi2::SetTrackName ( TString s )

// Set (alternative) name identifier for the produced tracks.
// This allows unique identification of (newly) produced pandel tracks
// in case of re-processing of existing data with different criteria.
// By default the produced tracks have the name "IceChi2" which is
// set in the constructor of this class.

Definition at line 651 of file IceChi2.cxx.

◆ SetVgroupUsage()

void IceChi2::SetVgroupUsage ( Int_t flag )

// (De)activate the distinction between v_phase and v_group of the Cherenkov light.
//
// flag = 0 : No distinction between v_phase and v_group
//      = 1 : Separate treatment of v_phase and v_group
//
// By default the distinction between v_phase and v_group is activated
// in the constructor of this class.

Definition at line 634 of file IceChi2.cxx.

◆ UseTracks()

void IceChi2::UseTracks	(	TString	classname,
		Int_t	n = -1 )

// Specification of the first guess tracks to be used.
//
// classname : Specifies the first guess algorithm (e.g. "IceDwalk");
// n : Specifies the max. number of these tracks to be used
//
// Note : n<0 will use all the existing tracks of the specified classname
//
// The default is n=-1.
//
// Consecutive invokations of this memberfunction with different classnames
// will result in an incremental effect.
//
// Example :
// ---------
// UseTracks("IceDwalk",5);
// UseTracks("IceLinefit",2);
// UseTracks("IceJams");
//
// This will use the first 5 IceDwalk, the first 2 IceLinefit and all the
// IceJams tracks which are encountered in the event structure.

Definition at line 560 of file IceChi2.cxx.

Member Data Documentation

◆ fCharge

Float_t IceChi2::fCharge

protected

Definition at line 49 of file IceChi2.h.

◆ fEvt

IceEvent* IceChi2::fEvt

protected

Definition at line 43 of file IceChi2.h.

◆ fFirst

Int_t IceChi2::fFirst

protected

Definition at line 39 of file IceChi2.h.

◆ fFitstats

NcSignal* IceChi2::fFitstats

protected

Definition at line 52 of file IceChi2.h.

◆ fFitter

TFitter* IceChi2::fFitter

protected

Definition at line 47 of file IceChi2.h.

◆ fHits

TObjArray* IceChi2::fHits

protected

Definition at line 46 of file IceChi2.h.

◆ fPenalty

Float_t IceChi2::fPenalty

protected

Definition at line 50 of file IceChi2.h.

◆ fPrint

Int_t IceChi2::fPrint

protected

Definition at line 40 of file IceChi2.h.

◆ fPsistats

NcSample IceChi2::fPsistats

protected

Definition at line 53 of file IceChi2.h.

◆ fSelhits

Int_t IceChi2::fSelhits

protected

Definition at line 41 of file IceChi2.h.

◆ fTkfit

NcTrack* IceChi2::fTkfit

protected

Definition at line 51 of file IceChi2.h.

◆ fTrackname

TString IceChi2::fTrackname

protected

Definition at line 48 of file IceChi2.h.

◆ fUseNames

TObjArray* IceChi2::fUseNames

protected

Definition at line 44 of file IceChi2.h.

◆ fUseNtk

TArrayI* IceChi2::fUseNtk

protected

Definition at line 45 of file IceChi2.h.

◆ fVgroup

Int_t IceChi2::fVgroup

protected

Definition at line 42 of file IceChi2.h.

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

icepack/source/IceChi2.h
icepack/source/IceChi2.cxx

Detailed Description

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ IceChi2()

◆ ~IceChi2()

Member Function Documentation

◆ Exec()

◆ FitFCN()

◆ GetPsi()

◆ SelectHits()

◆ SetCharge()

◆ SetPenalty()

◆ SetPrintLevel()

◆ SetTrackName()

◆ SetVgroupUsage()

◆ UseTracks()

Member Data Documentation

◆ fCharge

◆ fEvt

◆ fFirst

◆ fFitstats

◆ fFitter

◆ fHits

◆ fPenalty

◆ fPrint

◆ fPsistats

◆ fSelhits

◆ fTkfit

◆ fTrackname

◆ fUseNames

◆ fUseNtk

◆ fVgroup