tdub.rex¶

A module for parsing TRExFitter results and producing additional plots/tables.

Class Summary¶

`FitParam`([name, label, pre_down, pre_up, ...])	Fit parameter description as a dataclass.
`GroupedImpact`([name, avg, sig_lo, sig_hi])	Fit grouped impact summary.

Function Summary¶

`available_regions`(rex_dir)	Get a list of available regions from a TRExFitter result directory.
`chisq`(rex_dir, region[, stage])	Get prefit \(\chi^2\) information from TRExFitter region.
`chisq_text`(rex_dir, region[, stage])	Generate nicely formatted text for \(\chi^2\) information.
`compare_nuispar`(name, rex_dir1, rex_dir2[, ...])	Compare nuisance parameter info between two fits.
`compare_uncertainty`(rex_dir1, rex_dir2[, ...])	Compare uncertainty between two fits.
`comparison_summary`(rex_dir1, rex_dir2[, ...])	Summarize a comparison of two fits.
`data_histogram`(rex_dir, region[, fit_name])	Get the histogram for the Data in a region from a TRExFitter result.
`delta_param`(param1, param2)	Calculate difference between two fit parameters.
`delta_poi`(rex_dir1, rex_dir2[, fit_name1, ...])	Calculate difference of a POI between two results directories.
`fit_parameter`(fit_file, name[, prettify])	Retrieve a parameter from fit result text file.
`grouped_impacts`(rex_dir[, include_total])	Grab grouped impacts from a fit workspace.
`grouped_impacts_table`(rex_dir[, tablefmt, ...])	Construct a table of grouped impacts.
`meta_axis_label`(region, bin_width[, meta_table])	Construct an axis label from metadata table.
`meta_text`(region, stage)	Construct a piece of text based on the region and fit stage.
`nuispar_impact`(rex_dir, name[, label])	Extract a specific nuisance parameter from a fit.
`nuispar_impacts`(rex_dir[, sort])	Extract a list of nuisance parameter impacts from a fit.
`nuispar_impact_plot_df`(nuispars)	Construct a DataFrame to organize impact plot ingredients.
`nuispar_impact_plot_top20`(rex_dir[, thesis])	Plot the top 20 nuisance parameters based on impact.
`plot_all_regions`(rex_dir, outdir[, stage, ...])	Plot all regions discovered in a TRExFitter result directory.
`plot_region_stage_ff`(args)	Free (multiprocessing compatible) function to plot a region + stage.
`prefit_total_and_uncertainty`(rex_dir, region)	Get the prefit total MC prediction and uncertainty band for a region.
`prefit_histogram`(root_file, sample, region)	Get a prefit histogram from a file.
`prefit_histograms`(rex_dir, samples, region)	Retrieve sample prefit histograms for a region.
`prettify_label`(label)	Fix parameter label to look nice for plots.
`postfit_available`(rex_dir)	Check if TRExFitter result directory contains postFit information.
`postfit_total_and_uncertainty`(rex_dir, region)	Get the postfit total MC prediction and uncertainty band for a region.
`postfit_histogram`(root_file, sample)	Get a postfit histogram from a file.
`postfit_histograms`(rex_dir, samples, region)	Retrieve sample postfit histograms for a region.
`stability_test_standard`(umbrella[, outdir, ...])	Perform a battery of standard stability tests.
`stability_test_parton_shower_impacts`(...[, ...])	Perform a battery of parton shower impact stability tests.
`stack_canvas`(rex_dir, region[, stage, ...])	Create a pre- or post-fit plot canvas for a TRExFitter region.

Reference¶

class tdub.rex.FitParam(name='', label='', pre_down=0.0, pre_up=0.0, post_down=0.0, post_up=0.0, central=0.0, sig_lo=0.0, sig_hi=0.0, post_max=0.0)[source]¶

Fit parameter description as a dataclass.

name¶

Technical name of the nuisance parameter.

Type:: str

label¶

Pretty name for plotting.

Type:: str

pre_down¶

Prefit down variation impact on mu.

Type:: float

pre_up¶

Prefit up variation impact on mu.

Type:: float

post_down¶

Postfit down variation impact on mu.

Type:: float

post_up¶

Postfit up variation impact on mu.

Type:: float

central¶

Central value of the NP.

Type:: float

sig_lo¶

Lo error on the NP.

Type:: float

sig_hi¶

Hi error on the NP.

Type:: float

class tdub.rex.GroupedImpact(name='', avg=0.0, sig_lo=0.0, sig_hi=0.0)[source]¶

Fit grouped impact summary.

name¶

Technical name for the group.

Type:: str

avg¶

Average impact estimate.

Type:: float

sig_lo¶

Down fluctuation estimate.

Type:: float

sig_hi¶

Up flucuation estimate.

Type:: float

property org_entry¶

Org table entry (rounded).

Type:: str

property org_entry_raw¶

Org table entry (raw numbers).

Type:: str

tdub.rex.available_regions(rex_dir)[source]¶

Get a list of available regions from a TRExFitter result directory.

Parameters:: rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
Returns:: Regions discovered in the TRExFitter result directory.
Return type:: list(str)

tdub.rex.chisq(rex_dir, region, stage='pre')[source]¶

Get prefit \(\chi^2\) information from TRExFitter region.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
region (str) – TRExFitter region name.
stage (str) – Drawing fit stage, (‘pre’ or ‘post’).

Returns:

float – \(\chi^2\) value for the region.
int – Number of degrees of freedom.
float – \(\chi^2\) probability for the region.

tdub.rex.chisq_text(rex_dir, region, stage='pre')[source]¶

Generate nicely formatted text for \(\chi^2\) information.

Deploys tdub.rex.chisq() for grab the info.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
region (str) – TRExFitter region name.
stage (str) – Drawing fit stage, (‘pre’ or ‘post’).

Returns:

Formatted string showing the \(\chi^2\) information.

Return type:

str

tdub.rex.compare_nuispar(name, rex_dir1, rex_dir2, label1=None, label2=None, np_label=None, print_to=None)[source]¶

Compare nuisance parameter info between two fits.

Parameters:

name (str) – Name of the nuisance parameter.
rex_dir1 (str or pathlib.Path) – Path of the first TRExFitter result directory.
rex_dir2 (str or pathlib.Path) – Path of the second TRExFitter result directory.
label1 (str, optional) – Define label for the first fit (defaults to rex_dir1).
label2 (str, optional) – Define label for the second fit (defaults to rex_dir2).
np_label (str, optional) – Give the nuisance parameter a label other than its name.
print_to (io.TextIOBase, optional) – Where to print results (defaults to sys.stdout).

tdub.rex.compare_uncertainty(rex_dir1, rex_dir2, fit_name1='tW', fit_name2='tW', label1=None, label2=None, poi='SigXsecOverSM', print_to=None)[source]¶

Compare uncertainty between two fits.

Parameters:

rex_dir1 (str or pathlib.Path) – Path of the first TRExFitter result directory.
rex_dir2 (str or pathlib.Path) – Path of the second TRExFitter result directory.
fit_name1 (str) – Name of the first fit.
fit_name2 (str) – Name of the second fit.
label1 (str, optional) – Define label for the first fit (defaults to rex_dir1).
label2 (str, optional) – Define label for the second fit (defaults to rex_dir2).
poi (str) – Name of the parameter of interest.
print_to (io.TextIOBase, optional) – Where to print results (defaults to sys.stdout).

tdub.rex.comparison_summary(rex_dir1, rex_dir2, fit_name1='tW', fit_name2='tW', label1=None, label2=None, fit_poi='SigXsecOverSM', nuispars=None, nuispar_labels=None, print_to=None)[source]¶

Summarize a comparison of two fits.

Parameters:

rex_dir1 (str or pathlib.Path) – Path of the first TRExFitter result directory.
rex_dir2 (str or pathlib.Path) – Path of the second TRExFitter result directory.
fit_name1 (str) – Name of the first fit.
fit_name2 (str) – Name of the second fit.
label1 (str, optional) – Define label for the first fit (defaults to rex_dir1).
label2 (str, optional) – Define label for the second fit (defaults to rex_dir2).
fit_poi (str) – Name of the parameter of interest.
nuispars (list(str), optional) – Nuisance parameters to compare.
nuispar_labels (list(str), optional) – Labels to give each nuisance parameter other than the default name.
print_to (io.TextIOBase, optional) – Where to print results (defaults to sys.stdout).

tdub.rex.data_histogram(rex_dir, region, fit_name='tW')[source]¶

Get the histogram for the Data in a region from a TRExFitter result.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
region (str) – TRExFitter region name.
fit_name (str) – Name of the Fit

Returns:

Histogram for the Data sample.

Return type:

tdub.root.TH1

tdub.rex.delta_param(param1, param2)[source]¶

Calculate difference between two fit parameters.

Parameters:

param1 (tdub.rex.FitParam) – First fit parameter.
param2 (tdub.rex.FitParam) – Second fit parameter.

Returns:

float – Difference between the central values
float – Up uncertainty
float – Down uncertainty

tdub.rex.delta_poi(rex_dir1, rex_dir2, fit_name1='tW', fit_name2='tW', poi='SigXsecOverSM')[source]¶

Calculate difference of a POI between two results directories.

The default arguments will perform a calculation of \(\Delta\mu\) between two different fits. Standard error propagation is performed on both the up and down uncertainties.

Parameters:

rex_dir1 (str or pathlib.Path) – Path of the first TRExFitter result directory.
rex_dir2 (str or pathlib.Path) – Path of the second TRExFitter result directory.
fit_name1 (str) – Name of the first fit.
fit_name2 (str) – Name of the second fit.
poi (str) – Name of the parameter of interest.

Returns:

float – Central value of delta mu.
float – Up uncertainty on delta mu.
float – Down uncertainty on delta mu.

tdub.rex.fit_parameter(fit_file, name, prettify=False)[source]¶

Retrieve a parameter from fit result text file.

Parameters:

fit_file (pathlib.Path) – Path of the TRExFitter fit result text file.
name (str) – Name of desired parameter.
prettify (bool) – Prettify the parameter label using tdub.rex.prettify_label().

Raises:

ValueError – If the parameter name isn’t discovered.

Returns:

Fit parameter description.

Return type:

tdub.rex.FitParam

tdub.rex.grouped_impacts(rex_dir, include_total=False)[source]¶

Grab grouped impacts from a fit workspace.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory.
include_total (bool) – Include the FullSyst entry.

Yields:

GroupedImpact – Iterator of grouped impacts in the fit.

tdub.rex.grouped_impacts_table(rex_dir, tablefmt='orgtbl', descending=False, **kwargs)[source]¶

Construct a table of grouped impacts.

Uses the https://pypi.org/project/tabulate project.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
tablefmt (str) – Format passed to tabulate.
descending (bool) – Sort by descending order
**kwargs (dict) – Passed to grouped_impacts()

Returns:

Table representation.

Return type:

str

tdub.rex.plot_all_regions(rex_dir, outdir, stage='pre', fit_name='tW', show_chisq=True, n_test=-1, internal=True, thesis=False, save_png=False)[source]¶

Plot all regions discovered in a TRExFitter result directory.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
outdir (str or pathlib.Path) – Path to save resulting files to
stage (str) – Fitting stage (“pre” or “post”).
fit_name (str) – Name of the Fit
show_chisq (bool) – Print \(\chi^2\) information on ratio canvas.
n_test (int) – Maximum number of regions to plot (for quick tests).
internal (bool) – Flag for internal label.
thesis (bool) – Flag for thesis label.
save_png (bool) – Save png versions along with the pdf versions of plots.

tdub.rex.plot_region_stage_ff(args)[source]¶

Free (multiprocessing compatible) function to plot a region + stage.

This function is designed to be used internally by plot_all_regions(), where it is sent to a multiprocessing pool. Not meant for generic usage.

Parameters:: args (list(Any)) – Arguments passed to stack_canvas().

tdub.rex.meta_axis_label(region, bin_width, meta_table=None)[source]¶

Construct an axis label from metadata table.

Parameters:

region (str) – TRExFitter region to use.
bin_width (float) – Bin width for y-axis label.
meta_table (dict, optional) – Table of metadata for labeling plotting axes. If None (default), the definition stored in the variable tdub.config.PLOTTING_META_TABLE is used.

Returns:

str – x-axis label for the region.
str – y-axis label for the region.

tdub.rex.meta_text(region, stage)[source]¶

Construct a piece of text based on the region and fit stage.

Parameters:

region (str) – TRExFitter Region to use.
stage (str) – Fitting stage (“pre” or “post”).

Returns:

Resulting metadata text

Return type:

str

tdub.rex.nuispar_impact(rex_dir, name, label=None)[source]¶

Extract a specific nuisance parameter from a fit.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory.
name (str) – Name of the nuisance parameter.
label (str, optional) – Give the nuisance parameter a label other than its name.

Returns:

Desired nuisance parameter summary.

Return type:

tdub.rex.FitParam

tdub.rex.nuispar_impacts(rex_dir, sort=True)[source]¶

Extract a list of nuisance parameter impacts from a fit.

Parameters:: rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory.
Returns:: The nuisance parameters.
Return type:: list(tdub.rex.FitParam)

tdub.rex.nuispar_impact_plot_df(nuispars)[source]¶

Construct a DataFrame to organize impact plot ingredients.

Parameters:: nuispars (list(FitParam)) – The nuisance parameters.
Returns:: DataFrame describing the plot ingredients.
Return type:: pandas.DataFrame

tdub.rex.nuispar_impact_plot_top20(rex_dir, thesis=False)[source]¶

Plot the top 20 nuisance parameters based on impact.

Parameters:

rex_dir (str, pathlib.Path) – Path of the TRExFitter result directory.
thesis (: bool) – Flag for thesis label.

tdub.rex.prefit_total_and_uncertainty(rex_dir, region)[source]¶

Get the prefit total MC prediction and uncertainty band for a region.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory.
region (str) – Region to get error band for.

Returns:

tdub.root.TH1 – The total MC expectation histogram.
tdub.root.TGraphAsymmErrors – The error TGraph.

tdub.rex.prefit_histogram(root_file, sample, region)[source]¶

Get a prefit histogram from a file.

Parameters:

root_file (uproot.reading.ReadOnlyDirectory) – File containing the desired prefit histogram.
sample (str) – Physics sample name.
region (str) – TRExFitter region name.

Returns:

Desired histogram.

Return type:

tdub.root.TH1

tdub.rex.prefit_histograms(rex_dir, samples, region, fit_name='tW')[source]¶

Retrieve sample prefit histograms for a region.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
samples (Iterable(str)) – Physics samples of the desired histograms
region (str) – Region to get histograms for
fit_name (str) – Name of the Fit

Returns:

Prefit histograms.

Return type:

dict(str, tdub.root.TH1)

tdub.rex.prettify_label(label)[source]¶

Fix parameter label to look nice for plots.

Replace underscores with whitespace, TeXify some stuff, remove unnecessary things, etc.

Parameters:: label (str) – Original label.
Returns:: Prettified label.
Return type:: str

tdub.rex.postfit_available(rex_dir)[source]¶

Check if TRExFitter result directory contains postFit information.

Parameters:: rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
Returns:: True of postFit discovered
Return type:: bool

tdub.rex.postfit_total_and_uncertainty(rex_dir, region)[source]¶

Get the postfit total MC prediction and uncertainty band for a region.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory.
region (str) – Region to get error band for.

Returns:

tdub.root.TH1 – The total MC expectation histogram.
tdub.root.TGraphAsymmErrors – The error TGraph.

tdub.rex.postfit_histogram(root_file, sample)[source]¶

Get a postfit histogram from a file.

Parameters:

root_file (uproot.reading.ReadOnlyDirectory) – File containing the desired postfit histogram.
sample (str) – Physics sample name.

Returns:

Desired histogram.

Return type:

tdub.root.TH1

tdub.rex.postfit_histograms(rex_dir, samples, region)[source]¶

Retrieve sample postfit histograms for a region.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory
region (str) – Region to get histograms for
samples (Iterable(str)) – Physics samples of the desired histograms

Returns:

Postfit histograms detected in the TRExFitter result directory.

Return type:

dict(str, tdub.root.TH1)

tdub.rex.stability_test_standard(umbrella, outdir=None, tests='all')[source]¶

Perform a battery of standard stability tests.

This function expects a rigid umbrella directory structure, based on the output of results that are generated by rexpy.

Parameters:

umbrella (pathlib.Path) – Umbrella directory containing all fits run via rexpy’s standard fits.
outdir (pathlib.Path, optional) – Directory to save results (defaults to current working directory).
tests (str or list(str)) –
Which tests to execute. (default is “all”). The possible tests include:
- "sys-drops", which shows the stability test for dropping some systematics.
- "indiv-camps", which shows the stability test for limiting the fit to individual campaigns.
- "regions", which shows the stability test for limiting the fit to subsets of the analysis regions.
- "b0-check", which shows the stability test for limiting the fit to individual analysis regions and checking the B0 eigenvector uncertainty.

tdub.rex.stability_test_parton_shower_impacts(herwig704, herwig713, outdir=None)[source]¶

Perform a battery of parton shower impact stability tests.

This function expects a rigid pair of Herwig 7.0.4 and 7.1.3 directories based on the output of results that are generated by rexpy.

Parameters:

herwig704 (pathlib.Path) – Path of the Herwig 7.1.4 fit results
herwig713 (pathlib.Path) – Path of the Herwig 7.1.3 fit results
outdir (pathlib.Path, optional) – Directory to save results (defaults to current working directory).

tdub.rex.stack_canvas(rex_dir, region, stage='pre', fit_name='tW', show_chisq=True, meta_table=None, log_patterns=None, internal=True, thesis=False, combine_minor=True)[source]¶

Create a pre- or post-fit plot canvas for a TRExFitter region.

Parameters:

rex_dir (str or pathlib.Path) – Path of the TRExFitter result directory.
region (str) – Region to get error band for.
stage (str) – Drawing fit stage, (“pre” or “post”).
fit_name (str) – Name of the Fit
show_chisq (bool) – Print \(\chi^2\) information on ratio canvas.
meta_table (dict, optional) – Table of metadata for labeling plotting axes.
log_patterns (list, optional) – List of region patterns to use a log scale on y-axis.
internal (bool) – Flag for internal label.
thesis (bool) – Flag for thesis label.
combine_minor (bool) – Combine minor backgrounds into a single contribution (Zjets, Diboson, and MCNP will be labeled “Minor Backgrounds”).

Returns:

matplotlib.figure.Figure – Figure for housing the plot.
matplotlib.axes.Axes – Main axes for the histogram stack.
matplotlib.axes.Axes – Ratio axes to show Data/MC.