Walk Through Tutorial 2025 : Minimizing PROfit

Introduction

This tutorial assumes that you are relatively familiar with the v1.0.x style XML configuration files. If not please read up on the basics at XML tutorial before starting to work though this document.

The purpose of this walk though is to show the commands and output for a variety of different combinations and studies currently possible in PROfit.

Note: This walk-through has been developed and tested on v1.0.3 PROfit release. We will update accordingly.

Basic PROfit executable workflow

The standard PROfit executable command is of the form

PROfit -x my_xml_name.xml -t my_tag SUBCOMMAND

or longform

PROfit --xml my_xml_name.xml --tag my_tag SUBCOMMAND

Where the SUBCOMMAND is further instructions as to what to actually perform. The allowed subcommands can be found with PROfit --help along with other useful information:

PROfit: a PROfessional, PROductive fitting and oscillation framework. Together let's minimize PROfit!
Usage: PROfit [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help                   Print this help message and exit
  -x,--xml TEXT REQUIRED      Input PROfit XML configuration file.
  -v,--verbosity ENUM [3]     Verbosity Level [1-4]->[Error,Warning,Info,Debug].
  -t,--tag TEXT [PROfit]      Analysis Tag used for output identification.
  -o,--output TEXT [v1]       Additional output filename quantifier
  -n,--nthread UINT [1]       Number of threads to parallelize over.
  -m,--max UINT               Max number of events to run over.
  -c,--chi2 TEXT [PROchi]     Which chi2 function to use. Options are PROchi or PROCNP
  -d,--data TEXT              Load from a seperate data xml/data file instead of signal injection. Only used with plot subcommand.
  -i,--inject FLOAT ...       Physics parameters to inject as true signal.
  -s,--seed INT [-1]          A global seed for PROseed rng. Default to -1 for hardware rng seed.
  --inject-systs [TEXT,FLOAT] ...
                              Systematic shifts to inject. Map of name and shift value in sigmas. Only spline systs are supported right now.
  --poisson-throw             Do a Poisson stats throw of fake data.
  --scale TEXT ...            Scale detector POT by a given value.
  --syst-list TEXT ... Excludes: --exclude-systs
                              Override list of systematics to use (note: all systs must be in the xml).
  --exclude-systs TEXT ... Excludes: --syst-list
                              List of systematics to exclude.
  --fit-options [TEXT,FLOAT] ...
                              Parameters for single, detailed global best fit LBFGSB.
  --scan-fit-options [TEXT,FLOAT] ...
                              Parameters for simpier, multiple best fits in PROfile/surface LBFGSB.
  -p,--preset TEXT            Preset fitting params. Available `fast`, `good` and `overkill` .
  -f,--rwfile TEXT            File containing histograms for reweighting
  -r,--mockrw TEXT ...        Vector of reweights to use for mock data
  --log TEXT                  File to save log to. Warning: Will overwrite this file.
  --scale-by-width            Scale histgrams by 1/(bin width).
  --event-by-event            Do you want to weight event-by-event?
  --statonly                  Run a stats only surface instead of fitting systematics
  --force                     Force loading binary data even if hash is incorrect (Be Careful!)
  --no-xrootd                 Do not use XRootD, which is enabled by default
  --shapeonly Excludes: --rateonly
                              Run a shape only analysis
  --rateonly Excludes: --shapeonly
                              Run a rate only analysis

Subcommands:
  process                     PROcess the MC and systematics in root files into binary data for future rapid loading.
  surface                     Make a 2D surface scan of two physics parameters, profiling over all others.
  profile                     Make a 1D profiled chi2 for each physics and nuisence parameter.
  plot                        Make plots of CV, or injected point with error bars and covariance.
  fc                          Run Feldman-Cousins for this injected signal
  protest                     Testing ground for rapid quick tests.