Analysis-Utilities 26.9.9
C++/ROOT utilities for nuclear measurement data analysis
Loading...
Searching...
No Matches

Unbinned extended maximum-likelihood photopeak fitting on RooFit. More...

#include <RooFitUtils.hpp>

Public Member Functions

 RooFitUtils ()
 Construct in simultaneous mode.
 RooFitUtils (const std::vector< Double_t > &events, Float_t fit_range_low, Float_t fit_range_high, Float_t display_bin_width_kev, Bool_t use_flat_background=kFALSE, Bool_t use_step=kFALSE, Bool_t use_low_exp_tail=kFALSE, Bool_t use_low_lin_tail=kFALSE, Bool_t use_high_exp_tail=kFALSE)
 Construct in single-channel mode.
 ~RooFitUtils ()
 Destroys every RooFit object this instance created.
void SetBackgroundModel (Bool_t use_flat_background)
 Choose the background shape.
void SetStep (Bool_t use_step=kTRUE)
 Offer the step shelf to the component search.
void SetLowExpTail (Bool_t use_low_exp_tail=kTRUE)
 Offer the low-energy exponential tail.
void SetLowLinTail (Bool_t use_low_lin_tail=kTRUE)
 Offer the low-energy linear tail.
void SetHighExpTail (Bool_t use_high_exp_tail=kTRUE)
 Offer the high-energy exponential tail.
void SetInteractive (Bool_t interactive=kTRUE)
 Open the GUI editor after the automated fit.
void SetFitDebug (Bool_t fit_debug=kTRUE)
 Un-suppress RooFit evaluation errors during a simultaneous fit.
void SetRefitAfterLoad (Bool_t refit=kTRUE)
 Treat saved interactive parameters as a seed, not as the answer.
void SetTailRatioMax (Double_t ratio_max)
 Cap the dimensionless tail decay ratio tau / sigma.
void SetManualParameters (const std::vector< Double_t > &params)
 Supply explicit starting values for every parameter.
void SetManualParameter (Int_t index, Double_t value)
 Override one starting value.
void ClearManualParameters ()
 Discard manual starting values and return to automatic guesses.
void PlotFitSinglePeak (const TString input_name, const TString peak_name, const TString label="")
 Draw and save the single-peak fit with its residual panel.
void PlotFitDoublePeak (const TString input_name, const TString peak_name, const TString label="")
 Draw and save the double-peak fit with its residual panel.
void PlotFitTriplePeak (const TString input_name, const TString peak_name, const TString label="")
 Draw and save the triple-peak fit with its residual panel.
FitResult FitSinglePeak (const TString input_name, const TString peak_name)
 Fit one peak, pruning components that do not earn their place.
FitResult FitDoublePeak (const TString input_name, const TString peak_name, Double_t mu1_init, Double_t mu2_init, Bool_t link_sigma=kFALSE)
 Fit two peaks from centroid guesses.
FitResult FitDoublePeak (const TString input_name, const TString peak_name, const PeakFitResult &constrained_peak, Double_t mu2_init)
 Fit two peaks with the first constrained by an earlier fit.
FitResult FitTriplePeak (const TString input_name, const TString peak_name, const FitResult &constrained_peaks, Double_t mu3_init)
 Fit three peaks with the first two constrained by an earlier fit.
void AddChannel (const TString &name, const std::vector< Double_t > &events, Float_t fit_range_low, Float_t fit_range_high, Float_t display_bin_width_kev, Int_t num_peaks, const std::vector< Double_t > &mu_inits, Bool_t use_flat_background=kFALSE, Bool_t use_step=kFALSE, Bool_t use_low_exp_tail=kFALSE, Bool_t use_low_lin_tail=kFALSE, Bool_t use_high_exp_tail=kFALSE, const std::vector< Bool_t > &mu_fixed=std::vector< Bool_t >(), Bool_t bkg_yield_fixed=kFALSE, Bool_t bkg_slope_fixed=kFALSE, Bool_t lock_shape_after_seed=kFALSE, const std::vector< Bool_t > &use_step_per_peak=std::vector< Bool_t >(), const std::vector< Bool_t > &shape_lock_per_peak=std::vector< Bool_t >())
 Register one spectrum as a channel of the simultaneous fit.
void LinkParameter (const TString &target, const TString &source)
 Tie one parameter to another, fitting them as one degree of freedom.
void ConstrainPeakSeparation (const TString &channel, Int_t peak_hi, Int_t peak_lo, Double_t delta, Double_t sigma)
 Constrain the spacing between two peaks to a known value.
void LinkPeakShape (const TString &target_channel, Int_t target_peak, const TString &source_channel, Int_t source_peak)
 Tie a peak's whole shape to another peak's.
void SeedChannel (const TString &channel_name, const FitResult &result)
 Use a prior single-channel fit as starting values for a channel.
std::vector< FitResultFitSimultaneous (const TString &input_name, const TString &base_label)
 Run one joint extended-likelihood fit across every channel.
void DumpChannelCSV (const TString &channel, const TString &csv_path, Int_t npts=1000)
 Export a converged channel to CSV for plotting elsewhere.

Static Public Member Functions

static std::vector< Double_t > LoadEventsFromTree (TTree *tree, const TString &branch_name)
 Read a branch into the event vector the constructor expects.
static TH1F * BuildDisplayHistogramFrom (const std::vector< Double_t > &events, Float_t fit_range_low, Float_t fit_range_high, Float_t display_bin_width_kev)
 Bin events into a display histogram.
static void RefillDisplayHistogram (TH1 *hist, const std::vector< Double_t > &events, Float_t fit_range_low, Float_t fit_range_high, Float_t display_bin_width_kev)
 Rebin an existing display histogram in place.

Static Public Attributes

static constexpr const char * kFitRangeName = "fitrange"
 Name of the RooFit range this class fits over.

Detailed Description

Unbinned extended maximum-likelihood photopeak fitting on RooFit.

The counterpart to FittingUtils, which fits the same model by binned chi-squared. Both take the same constructor arguments, expose the same Set* component flags, and return the same FitResult.

Two modes, selected by which constructor is used:

Input is an event-level std::vector<Double_t>. The bin width is used only for display and for the post-hoc reduced chi-squared that drives component pruning — the fit itself never bins.

Warning
Yields, not heights. The amplitude fields of PeakFitResult carry RooFit event counts here, where FittingUtils puts peak heights. Nothing in the type distinguishes them, so a result moved between backends is silently wrong by the normalisation. Only the ratio component_amplitude / gaus_amplitude is the same quantity in both.
Note
RooRealVar::enableSilentClipping() is on, so observable values outside the current range are clipped rather than throwing.

Definition at line 280 of file RooFitUtils.hpp.

Constructor & Destructor Documentation

◆ RooFitUtils() [1/2]

RooFitUtils::RooFitUtils ( )

Construct in simultaneous mode.

Register spectra with AddChannel(), then call FitSimultaneous(). The single-channel Fit* methods do not apply to an instance built this way.

Definition at line 176 of file RooFitUtils.cpp.

◆ RooFitUtils() [2/2]

RooFitUtils::RooFitUtils ( const std::vector< Double_t > & events,
Float_t fit_range_low,
Float_t fit_range_high,
Float_t display_bin_width_kev,
Bool_t use_flat_background = kFALSE,
Bool_t use_step = kFALSE,
Bool_t use_low_exp_tail = kFALSE,
Bool_t use_low_lin_tail = kFALSE,
Bool_t use_high_exp_tail = kFALSE )

Construct in single-channel mode.

Parameters
eventsEvent-level observable values. Copied.
fit_range_lowLower fit bound.
fit_range_highUpper fit bound.
display_bin_width_kevBin width for the display histogram and the post-hoc reduced chi-squared. Does not affect the likelihood, which is unbinned.
use_flat_backgroundkTRUE for a constant background, kFALSE (default) for a linear one.
use_stepEnable the step shelf.
use_low_exp_tailEnable the low-energy exponential tail.
use_low_lin_tailEnable the low-energy linear tail.
use_high_exp_tailEnable the high-energy exponential tail.

Definition at line 181 of file RooFitUtils.cpp.

◆ ~RooFitUtils()

RooFitUtils::~RooFitUtils ( )

Destroys every RooFit object this instance created.

Definition at line 218 of file RooFitUtils.cpp.

Member Function Documentation

◆ AddChannel()

void RooFitUtils::AddChannel ( const TString & name,
const std::vector< Double_t > & events,
Float_t fit_range_low,
Float_t fit_range_high,
Float_t display_bin_width_kev,
Int_t num_peaks,
const std::vector< Double_t > & mu_inits,
Bool_t use_flat_background = kFALSE,
Bool_t use_step = kFALSE,
Bool_t use_low_exp_tail = kFALSE,
Bool_t use_low_lin_tail = kFALSE,
Bool_t use_high_exp_tail = kFALSE,
const std::vector< Bool_t > & mu_fixed = std::vector<Bool_t>(),
Bool_t bkg_yield_fixed = kFALSE,
Bool_t bkg_slope_fixed = kFALSE,
Bool_t lock_shape_after_seed = kFALSE,
const std::vector< Bool_t > & use_step_per_peak = std::vector<Bool_t>(),
const std::vector< Bool_t > & shape_lock_per_peak = std::vector<Bool_t>() )

Register one spectrum as a channel of the simultaneous fit.

Parameters
nameChannel name, unique within the fit; used to address it from the linking methods.
eventsEvent-level observable values. Copied.
fit_range_lowLower fit bound for this channel.
fit_range_highUpper fit bound for this channel.
display_bin_width_kevDisplay bin width; does not affect the likelihood.
num_peaksPeaks in this channel.
mu_initsStarting centroid per peak; num_peaks entries.
use_flat_backgroundkTRUE for constant, kFALSE for linear.
use_stepEnable the step shelf for this channel.
use_low_exp_tailEnable the low-energy exponential tail.
use_low_lin_tailEnable the low-energy linear tail.
use_high_exp_tailEnable the high-energy exponential tail.
mu_fixedPer-peak; where kTRUE, that centroid is held at its mu_inits value instead of floating. Empty means all float.
bkg_yield_fixedHold this channel's background yield constant.
bkg_slope_fixedHold this channel's background slope constant.
lock_shape_after_seedAfter seeding, fix sigma, the Gaussian yield and every tail and step shape parameter, so only peak positions and normalisations float.
use_step_per_peakPer-peak override of use_step, for a step on some peaks but not others sharing a channel. Empty means use_step applies to all.
shape_lock_per_peakPer-peak refinement of lock_shape_after_seed: entry i controls whether peak i's shape locks. Empty locks every peak.
Note
Simultaneous mode only — the instance must have been default-constructed.

Definition at line 2039 of file RooFitUtils.cpp.

◆ BuildDisplayHistogramFrom()

TH1F * RooFitUtils::BuildDisplayHistogramFrom ( const std::vector< Double_t > & events,
Float_t fit_range_low,
Float_t fit_range_high,
Float_t display_bin_width_kev )
static

Bin events into a display histogram.

Parameters
eventsEvent-level values.
fit_range_lowLower bound.
fit_range_highUpper bound.
display_bin_width_kevBin width.
Returns
A newly allocated histogram; the caller owns it.

Definition at line 107 of file RooFitUtils.cpp.

Referenced by AddChannel(), and FitSimultaneous().

◆ ClearManualParameters()

void RooFitUtils::ClearManualParameters ( )
inline

Discard manual starting values and return to automatic guesses.

Definition at line 587 of file RooFitUtils.hpp.

◆ ConstrainPeakSeparation()

void RooFitUtils::ConstrainPeakSeparation ( const TString & channel,
Int_t peak_hi,
Int_t peak_lo,
Double_t delta,
Double_t sigma )

Constrain the spacing between two peaks to a known value.

Imposes a Gaussian penalty on mu[peak_hi] - mu[peak_lo].

Parameters
channelChannel holding both peaks.
peak_hiIndex of the upper peak.
peak_loIndex of the lower peak.
deltaKnown separation, in the observable's units.
sigmaUncertainty on delta; set it to the literature error, and keep it positive.
Note
This is not the same as locking both centroids — see RooFitSeparationConstraint. Call it before FitSimultaneous().

Definition at line 1922 of file RooFitUtils.cpp.

◆ DumpChannelCSV()

void RooFitUtils::DumpChannelCSV ( const TString & channel,
const TString & csv_path,
Int_t npts = 1000 )

Export a converged channel to CSV for plotting elsewhere.

Writes two tidy files that pandas.read_csv reads directly, using the same expectedEvents * getVal * bin_width convention as the plotted curve:

  • <base>_spectrum.csv — one row per histogram bin: energy_keV, data_counts, fit_total, fit_background, residual_pull.
  • <base>_fitcurve.csv — a smooth overlay of npts samples: energy_keV, fit_total, fit_background, in counts per bin.
Parameters
channelChannel to export.
csv_pathOutput path base; a trailing .csv is stripped before the two suffixes are appended.
nptsSamples along the smooth overlay curve.
Note
Read-only: evaluates the current parameter state and changes no fit state. Call it after FitSimultaneous().

Definition at line 2786 of file RooFitUtils.cpp.

◆ FitDoublePeak() [1/2]

FitResult RooFitUtils::FitDoublePeak ( const TString input_name,
const TString peak_name,
const PeakFitResult & constrained_peak,
Double_t mu2_init )

Fit two peaks with the first constrained by an earlier fit.

Parameters
input_nameInput identifier.
peak_namePeak identifier.
constrained_peakPreviously fitted peak supplying the constraint.
mu2_initStarting centroid for the free peak.
Returns
The fitted result, with peaks sorted by centroid.

Definition at line 1625 of file RooFitUtils.cpp.

◆ FitDoublePeak() [2/2]

FitResult RooFitUtils::FitDoublePeak ( const TString input_name,
const TString peak_name,
Double_t mu1_init,
Double_t mu2_init,
Bool_t link_sigma = kFALSE )

Fit two peaks from centroid guesses.

Parameters
input_nameInput identifier.
peak_namePeak identifier.
mu1_initStarting centroid for the first peak.
mu2_initStarting centroid for the second.
link_sigmaWhen kTRUE, ties both peaks to a single Gaussian width: the second peak's PDFs are rebuilt to reference the first's sigma and Sigma2 is frozen. Right for close, same-detector lines such as the Pb K-beta group, where a free second width would otherwise trade against the background.
Returns
The fitted result, with peaks sorted by centroid.

Definition at line 1390 of file RooFitUtils.cpp.

◆ FitSimultaneous()

std::vector< FitResult > RooFitUtils::FitSimultaneous ( const TString & input_name,
const TString & base_label )

Run one joint extended-likelihood fit across every channel.

Builds the RooSimultaneous, applies the links and separation constraints, and minimises. With SetInteractive() the simultaneous editor opens afterwards, and accepted parameters are saved and reloaded as for the single-channel editors.

Parameters
input_nameInput identifier, used for saved parameters and output filenames.
base_labelBase label for the per-channel outputs.
Returns
One FitResult per channel, in registration order. These are the only results that carry the Minuit diagnostics — fit_status, cov_qual, edm, min_nll and parameter_diagnostics.
Note
Check fit_status == 0 and cov_qual == 0 before trusting the errors, and inspect parameter_diagnostics for parameters resting against a limit.

Definition at line 2873 of file RooFitUtils.cpp.

◆ FitSinglePeak()

FitResult RooFitUtils::FitSinglePeak ( const TString input_name,
const TString peak_name )

Fit one peak, pruning components that do not earn their place.

Low-side components are enabled as a group and pruned individually; the high-energy tail is tested separately. A component is kept only if it improves the reduced chi-squared.

Parameters
input_nameInput identifier, used for saved parameters and output filenames.
peak_namePeak identifier, used the same way.
Returns
The fitted result; check FitResult::valid.

Definition at line 1268 of file RooFitUtils.cpp.

◆ FitTriplePeak()

FitResult RooFitUtils::FitTriplePeak ( const TString input_name,
const TString peak_name,
const FitResult & constrained_peaks,
Double_t mu3_init )

Fit three peaks with the first two constrained by an earlier fit.

Parameters
input_nameInput identifier.
peak_namePeak identifier.
constrained_peaksPrevious result supplying the two constraints.
mu3_initStarting centroid for the free peak.
Returns
The fitted result, with peaks sorted by centroid.

Definition at line 1772 of file RooFitUtils.cpp.

◆ LinkParameter()

void RooFitUtils::LinkParameter ( const TString & target,
const TString & source )

Tie one parameter to another, fitting them as one degree of freedom.

Parameters
targetParameter to tie, as "<channel>:<parameter>".
sourceParameter it follows, in the same form.

Definition at line 2096 of file RooFitUtils.cpp.

Referenced by LinkPeakShape().

◆ LinkPeakShape()

void RooFitUtils::LinkPeakShape ( const TString & target_channel,
Int_t target_peak,
const TString & source_channel,
Int_t source_peak )

Tie a peak's whole shape to another peak's.

Links sigma and every tail and step shape parameter at once, leaving position and normalisation free.

Parameters
target_channelChannel holding the peak to tie.
target_peakIndex of that peak.
source_channelChannel holding the peak it follows.
source_peakIndex of that peak.

Definition at line 2112 of file RooFitUtils.cpp.

◆ LoadEventsFromTree()

std::vector< Double_t > RooFitUtils::LoadEventsFromTree ( TTree * tree,
const TString & branch_name )
static

Read a branch into the event vector the constructor expects.

Parameters
treeTree to read. Must not be null.
branch_nameBranch holding one observable value per entry.
Returns
The values, in entry order; empty if the branch is absent.

Definition at line 78 of file RooFitUtils.cpp.

◆ PlotFitDoublePeak()

void RooFitUtils::PlotFitDoublePeak ( const TString input_name,
const TString peak_name,
const TString label = "" )

Draw and save the double-peak fit with its residual panel.

Parameters
input_nameInput identifier, used in the output filename.
peak_namePeak identifier, used in the output filename.
labelOptional annotation drawn on the plot.

Definition at line 1170 of file RooFitUtils.cpp.

Referenced by FitDoublePeak(), and FitDoublePeak().

◆ PlotFitSinglePeak()

void RooFitUtils::PlotFitSinglePeak ( const TString input_name,
const TString peak_name,
const TString label = "" )

Draw and save the single-peak fit with its residual panel.

Parameters
input_nameInput identifier, used in the output filename.
peak_namePeak identifier, used in the output filename.
labelOptional annotation drawn on the plot.

Definition at line 1124 of file RooFitUtils.cpp.

Referenced by FitSinglePeak().

◆ PlotFitTriplePeak()

void RooFitUtils::PlotFitTriplePeak ( const TString input_name,
const TString peak_name,
const TString label = "" )

Draw and save the triple-peak fit with its residual panel.

Parameters
input_nameInput identifier, used in the output filename.
peak_namePeak identifier, used in the output filename.
labelOptional annotation drawn on the plot.

Definition at line 1218 of file RooFitUtils.cpp.

Referenced by FitTriplePeak().

◆ RefillDisplayHistogram()

void RooFitUtils::RefillDisplayHistogram ( TH1 * hist,
const std::vector< Double_t > & events,
Float_t fit_range_low,
Float_t fit_range_high,
Float_t display_bin_width_kev )
static

Rebin an existing display histogram in place.

What the interactive editor uses when the range slider moves, so binning follows the zoom without reallocating.

Parameters
histHistogram to refill. Must not be null.
eventsEvent-level values.
fit_range_lowNew lower bound.
fit_range_highNew upper bound.
display_bin_width_kevBin width.

Definition at line 129 of file RooFitUtils.cpp.

◆ SeedChannel()

void RooFitUtils::SeedChannel ( const TString & channel_name,
const FitResult & result )

Use a prior single-channel fit as starting values for a channel.

Parameters
channel_nameChannel to seed.
resultPrevious result supplying the starting values.

Definition at line 2133 of file RooFitUtils.cpp.

◆ SetBackgroundModel()

void RooFitUtils::SetBackgroundModel ( Bool_t use_flat_background)
inline

Choose the background shape.

Parameters
use_flat_backgroundkTRUE for constant, kFALSE for linear.

Definition at line 491 of file RooFitUtils.hpp.

◆ SetFitDebug()

void RooFitUtils::SetFitDebug ( Bool_t fit_debug = kTRUE)
inline

Un-suppress RooFit evaluation errors during a simultaneous fit.

Also prints the seed NLL, so an invalid-NLL failure names the offending PDF instead of failing anonymously.

Parameters
fit_debugkTRUE to enable. Off by default; set it before calling FitSimultaneous().

Definition at line 536 of file RooFitUtils.hpp.

◆ SetHighExpTail()

void RooFitUtils::SetHighExpTail ( Bool_t use_high_exp_tail = kTRUE)
inline

Offer the high-energy exponential tail.

Parameters
use_high_exp_tailkTRUE to enable.

Definition at line 509 of file RooFitUtils.hpp.

◆ SetInteractive()

void RooFitUtils::SetInteractive ( Bool_t interactive = kTRUE)
inline

Open the GUI editor after the automated fit.

Accepted parameters are saved to <plots_base>/fits/<peak_name>_<input_name>.roofits and reloaded on later runs, so the manual step happens once. Delete the file to redo it.

Parameters
interactivekTRUE to enable.
Note
The .roofits extension keeps these distinct from the .fits files written by FittingUtils, so both backends can be used on one input.

Definition at line 524 of file RooFitUtils.hpp.

◆ SetLowExpTail()

void RooFitUtils::SetLowExpTail ( Bool_t use_low_exp_tail = kTRUE)
inline

Offer the low-energy exponential tail.

Parameters
use_low_exp_tailkTRUE to enable.

Definition at line 499 of file RooFitUtils.hpp.

◆ SetLowLinTail()

void RooFitUtils::SetLowLinTail ( Bool_t use_low_lin_tail = kTRUE)
inline

Offer the low-energy linear tail.

Parameters
use_low_lin_tailkTRUE to enable.

Definition at line 504 of file RooFitUtils.hpp.

◆ SetManualParameter()

void RooFitUtils::SetManualParameter ( Int_t index,
Double_t value )

Override one starting value.

Parameters
indexParameter index in the active model.
valueInitial value.

Definition at line 262 of file RooFitUtils.cpp.

◆ SetManualParameters()

void RooFitUtils::SetManualParameters ( const std::vector< Double_t > & params)

Supply explicit starting values for every parameter.

Parameters
paramsInitial values, in the model's parameter order.

Definition at line 238 of file RooFitUtils.cpp.

◆ SetRefitAfterLoad()

void RooFitUtils::SetRefitAfterLoad ( Bool_t refit = kTRUE)
inline

Treat saved interactive parameters as a seed, not as the answer.

Interactive simultaneous fits have two historic modes. With a saved .simroofits file present, the parameters were loaded and adopted as the result, with no minimisation at all; without one, the GUI editor opened.

The first mode makes a re-run silently replay a previous session's answer: it still prints a chi-squared, redraws every plot and writes fresh output, while the fitted values cannot respond to anything upstream that has changed. Enabling this makes the saved parameters seed a real minimisation instead.

Parameters
refitkTRUE to re-minimise after loading.
Warning
Defaults to kFALSE so existing callers keep the replay behaviour. Turn it on for any fit whose inputs may change.

Definition at line 556 of file RooFitUtils.hpp.

◆ SetStep()

void RooFitUtils::SetStep ( Bool_t use_step = kTRUE)
inline

Offer the step shelf to the component search.

Parameters
use_stepkTRUE to enable.

Definition at line 496 of file RooFitUtils.hpp.

◆ SetTailRatioMax()

void RooFitUtils::SetTailRatioMax ( Double_t ratio_max)
inline

Cap the dimensionless tail decay ratio tau / sigma.

Applies to both LowExpTailRatio and HighExpTailRatio.

Parameters
ratio_maxUpper bound, in units of sigma.
Warning
The default of 100 is rarely what you want. On a typical fit window it makes tau longer than the window itself, over which the exponential is flat — so the "tail" becomes a constant pedestal, degenerate with the background yield, and absorbs background rather than describing a tail. Set a physically motivated value so the component either describes a real tail or fits to nothing.

Definition at line 573 of file RooFitUtils.hpp.

Member Data Documentation

◆ kFitRangeName

const char* RooFitUtils::kFitRangeName = "fitrange"
staticconstexpr

Name of the RooFit range this class fits over.

Definition at line 417 of file RooFitUtils.hpp.

Referenced by FitDoublePeak(), FitDoublePeak(), FitSimultaneous(), FitSinglePeak(), and FitTriplePeak().


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