Skip to content

Minimizing PROfit: XML configuration v2.0

Jump to bottom
Mark Ross-Lonergan edited this page Sep 29, 2025 · 1 revision

Getting started with PROfit: PROconfig the configuration XML

NOTE: This page assumes you are using the, recommended, version v2.0+ and above.

Everything that is user definable about the selection/spectra/systematics/binning and physics model is configurable at run time with a single configuration XML. All PROfit executables take the argument -x myconfig.xml or --xml myconfig.xml. Here we will describe the basic sections of a configuration xml

The Mode, Detector, Channel and binning (aka the Bookeeping Section)

<mode name="nu" />
<detector name="SBND" pot="6.6e20"/>
<detector name="ICARUS" pot="13.2e20"/>

   <channel name="numu" >
      <bins unit = "RecoE" edges="0.0 0.4 0.5 0.6 0.7 0.8 0.9 1.0 1.5 2.0 2.5 3" />
      <bins unit = "True L/E" min="0" max="3" nbins="250" plot="false"/>
      <bins unit = "True E [GeV]" min="0" max="3" nbins="20"/>
      <subchannel name="cc" plotname="#nu_{#mu} CC" color="#99CCFF"/>
      <subchannel name="nc" plotname="#nu_{#mu} NC" color="#3D9432"/>
  </channel>
  
  <channel name="nue" >
      <bins unit = "RecoE" edges="0.0 0.4 0.5 0.6 0.7 0.8 0.9 1.0 1.5 2.0 2.5 3" />
      <bins unit = "True L/E" min="0" max="3" nbins="250" plot="false"/>
      <bins unit = "True E [GeV]" min="0" max="3" nbins="20"/>
      <subchannel name="intrinsic" plotname="#nu_{e} CC" color="#33CC33"/>
  </channel>

The above code configures a single mode (nu), two detectors (SBND and ICARUS), each with two channels (numu and nue). All channels (and the subchannels that make them up) are duplicated exactly for each detector and mode.

In reality there is no difference between modes and detectors other than human interpretation. Channels correspond to physical observable spectra in a variable with a specified binning (given by <bins>). We can have any number of variables, although the fitting takes place in one of them (currently the default first variable). The classic example is two variables: a reconstructed neutrino energy for reco variable and L/E for true variable for an oscillation fit, but it could be anything. Binning in variables vary between different channels.

Each channel is made up of any number of subchannels which consist of truth level breakdowns of the prediction, broken down because we want to either (a) Have our model act differently on each subchannel, such as numu's and nue's oscillating differently (b) Apply systematic differently to subchannels. The subchannels are a truth level definition and are not physical, we can't say if an even in data is from a particular subchannel, just the parent channel. When we want to do fits we collapse the subchannels, adding their events into a single channel spectra. By construction each subchannel in a given channel must have the same binning as each other in order to collapse correctly.

In this example we have subchannels such as NC and CC events as well as a cosmic background category.

The mode, detector, channel and subchannel tags must not contains underscores (_) be unique when concatenated together into a single spectra identifier using underscores mode_detector_channel_subchannel. This unique identifier is used later to tell PROfit exactly which Monte Carlo events to fill into each spectra.

At this stage we have not defined what the variable is, or how to fill it from MC, this is just a bookeeping step to define exactly the binning and spectra we want to fill. Filling it is defined later when we get to the MCfile portion.

The model_rule section (aka defining the physics model)

This section is incomplete but allows for the definition of all physics "rules" that should be applied to any given subchannel defined above. Similar to the channel and subchannel above, this section spells out the bookeeping of the model, but the physics itself is described elsewhere (currently in the PROmodel.h class itself.) . You need to choose one, and only one, of the models in PROmode.h (so far just these three)

<model tag="numudis">
    <rule index="0" name="No Osc"/>
    <rule index="1" name="Numu Dis"/>
    <parameter variable_index = "1" name="L/E"/>
</model>


<model tag="nueapp">
    <rule index="0" name="No Osc"/>
    <rule index="1" name="Nue App"/>
    <parameter variable_index = "1" name="L/E"/>
</model>

<model tag="3+1">
    <rule index="0" name="No Osc"/>
    <rule index="1" name="Numu Dis"/>
    <rule index="2" name="Nue App"/>
    <rule index="3" name="Nue Dis"/>
    <parameter variable_index = "1" name="L/E"/>
</model>

The above tells us that in the model "3+1" we will have three possible rules, identified by the index's 0,1,2 and correspond to No Osc, NuMU appearance and NuApp. Mode index 0 should always correspond to no-effect and subchannels will default to this if none other are given. All models only have 1 parameter they depend on (outside of the fitting parameters). This is defined by which says that internally "L/E" maps to variable number 1 we load in.

The MCfile section (aka where does our Monte Carlo go?)

This is the most important, but complex XML element. It explains what, where and why in regards the defined subchannels of the analysis. Here is a example snapshot of two MCFiles.

<MCFile treename="events/selectedNu" filename="my_fake_numufile.root" scale = "1.0" pot="6.6e20"> 
    <friend treename="events/multisimTree" />
    <friend treename="events/multisigmaTree" />
     <branch
         associated_subchannel = "nu_SBND_numu_cc"
         model_rule            = "1"
         additional_weight     = "0.9*CC*(truePDG == 14 || truePDG == -14)*(recoE>0)"
         >
         <variable>recoE</variable>
         <variable>trueL/(trueE*1000.0)</variable>
         <variable>trueE</variable>
     </branch>
</MCFile>

The first few attributes give the filename (aka full path to the file) and the treename to load. Now we often have many trees in a file, so the friend element allows for friending any umber of TTrees from the same or multiple files.

The most important aspect is the branch tag with the following attributes

  • associated_subchannel : This is the subchannel to fill with this file (in mode_detector_channel_subchannel unique tag defined above)
  • model_rule : What rule to apply? Use the index defined in model above. defaults to 0, i.e no rule.
  • incl_systematics : Whether this branch should look for systematic variations. This is true by default.
  • additional_weight : Can be a cut (defined as any TTreeFormula) or scaling to apply event by event. eg 0.5*pot/sin(1+x) if pot and x were branches in the TTree or Friended TTree.
  • variable : Whatever variable you want to fill into each variable, as defined by the binning in above. If you have three variables defined in the top of the XML you need three variables here. They can be ANYTHING that a TTreeFormula or Draw command can take as input.

The variation section (aka defining systematics!)

Any systematics that are in the allowlist are applied to all MCfiles. You must tell PROfit how to handle each systematic. Currently the options are "covariance," "spline," "mcstat," "norm," and "flat."

In "covariance" mode a covariance matrix will be created using the universes provided for that systematic in the MCFile. This mode assumes the response for that systematic is linear, i.e., a 2 sigma shift would have twice the effect as a 1 sigma shift. In "spline" mode a cubic spline is created using the weights in the MCFile. "Spline" systematics can represent non-linear effects, but at the moment we do not account for correlations between "spline" systematics. "Spline" systematics will also have worse performance than "covariance" systematics, and so one should prefer "covariance" systematics unless there is a reason to expect a non-linear effect.

"Norm" and "flat" are similar except "norm" will create a spline systematic which affects the normalization, while "flat" will create a diagonal covariance matrix where all the diagonal elements have the same value (i.e., an uncorrelated normalization uncertainty). Note that the spline-like "norm" systs will be correlated across bins, while the covariance-like "flat" is explicitly diagonal and hence uncorrelated across bins. These systematics can be specified to only affect certain subchannels. In the examples below we specify the name as nu_ICARUS_numu_n which will match any subchannel with this string in the name. In the channels specified above, this would affect only the ICARUS, numu channel, nc subchannel. The flat uncertainty below on the other hand will match the SBND numu channel, nc subchannel in addition to the ICARUS numu channel, nc subchannel.

Finally, the mcstat type systematic below is a special systematic type which will create a diagonal covariance matrix with the unscaled MC statistical uncertainty along the diagonal. "Unscaled" in this case means that the pot scaling, MCFile scale attribute, and additional_weight scaling are not included when calculating the MC statistical uncertainty. If additional_weight is 0 though, that event will not be counted in the MC stats. This allows for implementing selection cuts using additional_weight.

<variation_list>
    <allowlist type="mcstat" plotname="MC Stat"></allowlist>
    <allowlist type="covariance" tag="flux">expskin_Flux</allowlist>  
    <allowlist type="spline" plotname="ZExpA1" tag="xsec, ZExp" binning="truth">GENIEReWeight_SBN_v1_multisigma_ZExpA1CCQE</allowlist>
    <allowlist type="spline" plotname="ZExpA2" tag="xsec, ZExp" binning="other1">GENIEReWeight_SBN_v1_multisigma_ZExpA2CCQE</allowlist>
    <allowlist type="spline" plotname="ZExpA3" tag="xsec, ZExp" binning="truth">GENIEReWeight_SBN_v1_multisigma_ZExpA3CCQE</allowlist>
    <allowlist type="spline" plotname="ZExpA4" tag="xsec, ZExp" knobvals="-1 1 -2 2 -3 3">GENIEReWeight_SBN_v1_multisigma_ZExpA4CCQE</allowlist>
    <allowlist type="norm" binning="reco" plotname="FluxNorm">nu_ICARUS_numu_n:0.02</allowlist>
    <allowlist type="flat" plotname="flat 1%">_numu_n:0.01</allowlist>
</variation_list>

There are several attributes in the allowlist elements above:

  • type : Specifies the systematic type. Options are mcstat, flat, norm, covariance, spline
  • plotname : Specifies a name other than the name in between the <allowlist> tags to use for plots. This name is also supported when specifying systematics by name from the commandline (e.g., using --syst-list or --exclude-systs).
  • tag : A comma separated list of tags for this systematic. When calling --syst-list or --exclude-systs from the command line you can specify a tag instead of an individual systematic, and all systematics in the xml with that tag will be used/excluded.
  • binning : The binning to use for "spline" and "norm" type systematics. ("Covariance", "mcstat", and "flat" are always in the reco binning for whatever variable you are plotting in.) The options are "reco", "truth", and "otherX" where X is some number. The "reco" option will create a spline for each reco bin, the "truth" option will create a spline for each true bin, and the "otherX" option will create a spline for each bin of the Xth other variable.
  • knobvals : For spline systematics we prefer to read the knob value for each weight from the input file. If the file does not contain the correct branch for reading the knob values, we will assume -3, -2, -1, 0, 1, 2, 3 as the order of the weights since this is the default when using CAFAna to make Trees. To override this default, or the override the values in the input file, you can specify the knob values using this attribute in a space separated list. Note that the length of the knob value list should be the same as the number of weights in the input file.

Clone this wiki locally