Card File Examples
Author: Patrick Stowell
Date: June 2017
Versions: NUISANCE v2r0, GENIE 2.12.6
The NUISANCE applications require card files to be written that list different comparison specifications you would like to run with.
We call an entry in the card file a 'structure' and there are a number of these structures available to the user when writing card files. These are listed below, with their required and optional arguments. Some structures are valid only for certain routines or apps, so where appropriate these have been labelled.
NUISANCE Versions >v2r0 contain support for the card file to be specified in xml format, also opening up additional options to be passed in the structures. To look at examples for the older 'simple card' format that can be saved as a text file, please see the 'Simple Card Structures' section.
Wiki content
XML Card Structures
XML Structure
When writing XML card files you also need to wrap eveything in a '<nuisance>' root element.
<nuisance> ... </nuisance>
If you don't do this, the ROOT XML parser will fail and NUISANCE will think your card file is empty. For example the following card file is valid
<nuisance> <parameter type="genie_parameter" name="MaCCQE" nominal="1.0" state="FIX" /> <sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="GENIE:/path/to/neut/file.root" /> </nuisance>
but the following card file is NOT valid as it is missing the root element
<parameter type="genie_parameter" name="MaCCQE" nominal="1.0" state="FIX" /> <sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="GENIE:/path/to/neut/file.root" />
Sample Structure
Data comparison samples are specified by including the 'sample structure, listing the name of the sample and the input. These structures are read by nuiscomp, nuismin, and nuissyst
<sample name="NAME" input="TYPE:/path/to/FILE" option="[OPTION]" norm="[NORMVALUE]" />
- NAME : Name string of the sample of interest specified in src/FCN/SampleList.cxx.
- TYPE : Generator Input Type string telling NUISANCE what the file type is (e.g. GENIE)
- OPTION : (Optional Argument) Specifying extra sample options that change the way the sample behaves at run time (e.g. SHAPE). If none given, this is left as DEFAULT.
- NORMVALUE : (Optional Argument) Starting sample normalisation value used to shift total MC normalisation. If none given this is left at the value 1.0.
In the XML format, if you don't want to provide optional arguments, these can just be left out completely from the xml entry.
Multiple sample structures can be given in the NUISANCE card file to include many data comparisons at once.
Since the specifications in the xml structure are given as separate entries it is also not necessary to give them in this exact order, as long as all non-optional arguments are given somewhere within the xml entry.
NOTE: Reading in Generators requires that Generator to be built and have NUISANCE built against it. E.g. to read GENIE files, you need to have a working install of GENIE and NUISANCE built against that version.
Example 1 : MiniBooNE CCQE comparison using a GENIE file
<sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="GENIE:/path/to/my/geniefile.root" />
Example 2 : MiniBooNE CCQE comparison using a NuWro? file
<sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="NEUT:/path/to/my/nuwrofile.root" />
Example 3 : MiniBooNE CC1pi comparison using a NEUT file
<sample name="MiniBooNE_CC1pi_XSec_1DTpi_nu" input="NEUT:/path/to/my/neutfile.root" />
Example 4 : MiniBooNE CC1pi comparison using a GiBUU file and the SHAPE option
<sample name="MiniBooNE_CC1pi_XSec_1DTpi_nu" input="GiBUU:/path/to/my/gibuufile.root" option="SHAPE" />
Example 5 : MINERvA CCQE comparison using a NEUT file and shifting the MC normalisation by 1.0 / 0.9.
<sample name="MINERvA_CCQE_XSec_1DQ2_nu" input="NEUT:/path/to/my/neutfile.root" option="DEFAULT" norm="0.9" />
Example 6 : MiniBooNE CCQE comparison using a NuWro?, shifting the MC by 0.9 / 1.0 but also adding a normalisation penalty to the likelihood (option=NORM)
<sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="NEUT:/path/to/my/neutfile.root" option="NORM" norm="0.9" />
Example 7 : Include both MiniBooNE CCQE and CC1pip data
<sample name="MiniBooNE_CC1pi_XSec_1DTpi_nu" input="NEUT:/path/to/my/neutfile.root" /> <sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="NEUT:/path/to/my/neutfile.root" />
Fixed Parameter Structure
Fixed parameters can be specified by using any of the 'parameter' type structures. You must specify the type of parameter first, before listing the name, starting value, and state. These structures are read by nuiscomp, nuismin, and nuissyst
<parameter type="TYPE_parameter" name="NAME" nominal="VALUE" state="STATE" />
- TYPE : Type of RW parameter, (e.g. genie_parameter, neut_parameter, norm_parameter)
- NAME : Name of RW parameter, can be any string given in the RW engine. In GENIE this list is given in $GENIE/src/ReWeight/GSyst.h.
For normalisation parameters the name of the dial corresponds to SAMPLENAME_norm. (e.g. 'MiniBooNE_CCQELike_XSec_1DQ2_nu_norm')
- VALUE : Starting value for the dial. In general for RW engine parameters this is given in terms of 1-sigma variations away from the nominal, so that VALUE=0.0 is the nominal generator value. For everything else, like normalisation parameters, this value is in units of the true value.
- STATE : State of the dial. This should always be left as FIX as this is the only support option for the time being.
Multiple parameter structures can be listed in the nuisance card file to make comparisons with many model parameters changed at once.
Since the specifications in the xml structure are given as separate entries it is also not necessary to give them in this exact order, as long as all non-optional arguments are given somewhere within the xml entry.
NOTE: Running with RW parameters changed in Generators requires that specific Generator to be built and have NUISANCE built against it. E.g. to using GENIE RW, you need to have a working install of GENIE+GENIE-RW and NUISANCE built against that version.
Example 1 : Fixed GENIE RW 'MaCCQE' to +1 sigma
<parameter type="genie_parameter" name="MaCCQE" nominal="+1.0" state="FIX" />
Example 2 : Fixed NuWro? RW 'kNuwro_Ma_CCQE' to -1 sigma
<parameter type="nuwro_parameter" name="kNuwro_Ma_CCQE" nominal="-1.0" state="FIX"/>
Example 3 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma
<parameter type="neut_parameter" name="MaCCQE" nominal="-1.0" state="FIX" /> <parameter type="neut_parameter" name="MaCCRES" nominal="+1.0" state="FIX" />
Example 4 : Change MiniBooNE sample normalisation (alternative to using sample NORMVALUE option)
<parameter type="norm_parameter" name="MiniBooNE_CCQE_XSec_1DQ2_nu_norm" nominal="0.9" state="FIX" /> <sample name="MiniBooNE_CCQE_XSec_1DQ2_nu" input="NEUT:/path/to/neutinput.root" />
Free Parameter Structure
Free parameters can be specified by using any of the 'parameter' type structures. You must specify the type of parameter first, before listing the name, starting value, lower and upper limits, step size and state. This is an extension of the fixed parameter case to include extra information needed by routines that vary parameters. These structures are read by nuismin, and nuissyst. It is possible to use these structures also in nuiscomp, but the dial limits and step sizes will be ignored, fixing the parameter at the chosen value instead.
<parameter type="TYPE_parameter" name="NAME" nominal="VALUE" low="LOW" high="HIGH" step="STEP" state="STATE" />
- TYPE : Type of RW parameter, (e.g. genie_parameter, neut_parameter, norm_parameter)
- NAME : Name of RW parameter, can be any string given in the RW engine. In GENIE this list is given in $GENIE/src/ReWeight/GSyst.h.
For normalisation parameters the name of the dial corresponds to SAMPLENAME_norm. (e.g. 'MiniBooNE_CCQELike_XSec_1DQ2_nu_norm')
- VALUE : Starting value for the dial. In general for RW engine parameters this is given in terms of 1-sigma variations away from the nominal, so that VALUE=0.0 is the nominal generator value. For everything else, like normalisation parameters, this value is in units of the true value.
- LOW : Lower limit of the dial in the same units as VALUE
- HIGH : Upper limit of the dial in the same units as VALUE
- STEP : Starting step size of the dial in the same units as VALUE. This is the stepsize passed to the minimizer, as well as the step size used in various functions that randomly scan the parameter space.
- STATE : State of the dial. This can be left as FREE or FIX. If FREE this tells NUISANCE that we will allow the dial to be varied. If FIX then NUISANCE will make sure it is left at VALUE for the entire time. FIX is a useful option if you decide you would like to stop a single parameter being floated but would like to keep its limit definitions in case you would like to vary it at a later point.
Multiple parameter structures can be listed in the nuisance card file to make comparisons with many model parameters changed at once.
Since the specifications in the xml structure are given as separate entries it is also not necessary to give them in this exact order, as long as all non-optional arguments are given somewhere within the xml entry.
NOTE: Running with RW parameters changed in Generators requires that specific Generator to be built and have NUISANCE built against it. E.g. to using GENIE RW, you need to have a working install of GENIE+GENIE-RW and NUISANCE built against that version.
Example 1 : Free GENIE RW 'MaCCQE' to starting at 0.0 and between -1.0 and 1.0 sigma
<parameter type="genie_parameter" name="MaCCQE" nominal="0.0" low="-1.0" high="1.0" step="0.5" state="FREE" />
Example 2 : Free NuWro? RW 'kNuwro_Ma_CCQE'
<parameter type="nuwro_parameter" name="kNuwro_Ma_CCQE" nominal="0.0" low="-1.0" high="1.0" step="0.5" state="FREE" />
Example 3 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma. Vary MaCCQE.
<parameter type="neut_parameter" name="MaCCQE" nominal="-1.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <parameter type="neut_parameter" name="MaCCRES" nominal="+1.0" state="FIX" />
Example 4 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma. Vary MaCCQE.
<parameter type="neut_parameter" name="MaCCQE" nominal="-1.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <parameter type="neut_parameter" name="MaCCRES" nominal="+1.0" low="-3.0" high="3.0" step="1.0" state="FIX" />
Example 5 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma. Vary both.
<parameter type="neut_parameter" name="MaCCQE" nominal="-1.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <parameter type="neut_parameter" name="MaCCRES" nominal="+1.0" low="-3.0" high="3.0" step="1.0" state="FREE" />
Example 6 : Vary MiniBooNE sample normalisation between user chosen limits (alternative to using sample NORMVALUE option)
norm_parameter MiniBooNE_CCQE_XSec_1DQ2_nu_norm 0.9 0.8 1.1 0.05 FREE sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/neutinput.root
Example 7 : Example 5 with a shifted order
<parameter state="FREE" type="neut_parameter" name="MaCCQE" nominal="-1.0" low="-3.0" high="3.0" step="1.0" /> <parameter nominal="+1.0" low="-3.0" type="neut_parameter" high="3.0" step="1.0" state="FIX" name="MaCCRES" />
Covariance Structure
Covariance objects are used by NUISANCE to assign likelihood penalty terms to parameters as well as define appropriate parameter throws when studying systematic uncertainties. They can be specified in the card file by providing the 'covar' structure, plus an ID, input definition, and state.
<covar name="ID" input="TYPE:INPUT" type="STATE" />
- ID : Unique ID specified by the user so they can keep track of this covariance class in the output file. Saved objects from this covariance will be labeled 'ID_label' (e.g. ID_central).
- TYPE : Covariance type. There are multiple ways to define a covariance, with some examples of these types below.
- INPUT : Input definition, this depends a lot on what the TYPE is defined as. Some examples are below.
- STATE : State of this covariance, used to tell NUISANCE whether it should use it to apply a likelihood penalty (e.g. GAUSPULL), use it to throw parameters (e.g. GAUSTHROW), or both.
Single uncorrelated dial covariances
To tell NUISANCE to make a covariance for a single dial, you can specifiy the covariance type as 'DIAL'
<covar name="ID" input="DIAL:NAME;CENTRAL;WIDTH" type="STATE" />
- NAME : Name of the RW dial. This dial should have also already been setup using one of the 'parameter' structures shown above.
- CENTRAL : Central value for this dial used in the covariance. For example when you want to include the result from a previous fit, this should be set to the best fit value from that fit.
- WIDTH : Error on the parameter about the central value. Used as the Gaussian width when generating parameter throws. For example when you want to include the result from a previous fit, this should be set to the best fit error from that fit.
Example 1 : Covariance used to throw MaCCQE uncorrelated in nuissyst using MaCCQE=0.0+-1.0
<parameter type="genie_parameter" name="MaCCQE" nominal="0.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <covar name="MaThrow" input="DIAL:MaCCQE;0.0;1.0" type="GAUSTHROW" />
Example 2 : Covariance used to apply an additional MaCCQE pull in nuismin using MaCCQE=0.0+-1.0
<parameter type="genie_parameter" name="MaCCQE" nominal="0.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <covar name="MaTPull" input="DIAL:MaCCQE;0.0;1.0" type="GAUSPULL" />
Correlated dial covariances
To tell NUISANCE to make a covariance for multiple parameters that have some correlations between the, you can specifiy the covariance type as 'ROOT' and provide a ROOT input file containing the covariaince
<covar name="ID" input="ROOT:FILEPATH;DIAL_HIST;COVARIANCE_HIST" type="STATE" />
- FILEPATH : Path to a ROOT file containing the covariance information
- DIAL_HIST : Name of a TH1D inside FILEPATH. This TH1D should be created such that each bin corresponds to a different dial, with the bin contents set to the best fit value for that dial, and the bin label set to the dial name. A good example of such a histogram is given in the standard output of nuismin called 'fit_dials'.
- COVARIANCE_HIST : Name of a TH2D inside FILEPATH. This TH2D should be created such that each bin in x and y corresponds to a different dial, with the bin contents set to the covariance between each dial according to the bins x and y position, and the bin labels set to the corresponding dial names. A good example of such a histogram is given in the standard output of nuismin called 'fit_dials_free'.
The following examples assume you have a root histogram called myfitresult.root, containing a TH1D called 'fitresults' with the dial central values in it, and a TH2D covariance histogram called 'cov', and that both these histograms describe the central values and covariance for the 'MaCCQE' and 'MaCCRES' dials.
Example 1 : Covariance ROOT file used to throw MaCCQE and MaCCRES using nuissyst
<parameter type="genie_parameter" name="MaCCQE" nominal="0.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <parameter type="genie_parameter" name="MaCCRES" nominal="0.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <covar name="CovarThrow" input="ROOT:/path/to/myfitresult.root;fitresults;cov" type="GAUSTHROW" />
Example 1 : Covariance ROOT file used to apply a pull to MaCCQE and MaCCRES using nuismin, where fitresult.root is in the current directory
<parameter type="genie_parameter" name="MaCCQE" nominal="0.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <parameter type="genie_parameter" name="MaCCRES" nominal="0.0" low="-3.0" high="3.0" step="1.0" state="FREE" /> <covar name="CoverPull" input="ROOT:myfitresult.root;fitresults;cov" type="GAUSPULL" />
Config Structure
Configuration options can be given at runtime by including them in the card file using the 'config' structure.
<config NAME="VALUE" />
- NAME : Name of configuration parameter
- VALUE : Value of configuration parameter
Including a configuration option will override the defaults given in 'parameters/config.xml'. Multiple configuration options can be overridden at once by listing them on separate lines in the card file.
Example 1 : Change the verbosity level
<config VERBOSITY="1" />
Example 2 : Change the verbosity level and set the maximum number of events to run over
<config VERBOSITY="2" /> <config MAXEVENTS"25000" />
Comments Structure
Comments can be inserted into the simple card format by using the '#' symbol at the start of a line.
<!-- Insert my comments here -->
Example 1:
<!-- These are my config options --> <config VERBOSITY="4" />
Example 2:
<!-- I Like making comments --> config VERBOSITY 4 <!-- I like it a lot. I can make multiple line comments. I can also comment out other structures to 'turn them off' --> <!-- sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/neut/file.root --:>
Simple Card Structures
Sample Structure
Data comparison samples are specified by including the 'sample structure, listing the name of the sample and the input. These structures are read by nuiscomp, nuismin, and nuissyst
sample NAME TYPE:/path/to/FILE [OPTION] [NORMVALUE]
- NAME : Name string of the sample of interest specified in src/FCN/SampleList.cxx.
- TYPE : Generator Input Type string telling NUISANCE what the file type is (e.g. GENIE)
- OPTION : (Option Argument) Specifying extra sample options that change the way the sample behaves at run time (e.g. SHAPE). If none given, this is left as DEFAULT.
- NORMVALUE : Starting sample normalisation value used to shift total MC normalisation. If none given this is left at the value 1.0.
Multiple sample structures can be given in the NUISANCE card file to include many data comparisons at once.
NOTE: Reading in Generators requires that Generator to be built and have NUISANCE built against it. E.g. to read GENIE files, you need to have a working install of GENIE and NUISANCE built against that version.
Example 1 : MiniBooNE CCQE comparison using a GENIE file
sample MiniBooNE_CCQE_XSec_1DQ2_nu GENIE:/path/to/my/geniefile.root
Example 2 : MiniBooNE CCQE comparison using a NuWro? file
sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/my/nuwrofile.root
Example 3 : MiniBooNE CC1pi comparison using a NEUT file
sample MiniBooNE_CC1pi_XSec_1DTpi_nu NEUT:/path/to/my/neutfile.root
Example 4 : MiniBooNE CC1pi comparison using a GiBUU file and the SHAPE option
sample MiniBooNE_CC1pi_XSec_1DTpi_nu GiBUU:/path/to/my/gibuufile.root SHAPE
Example 5 : MINERvA CCQE comparison using a NEUT file and shifting the MC normalisation by 1.0 / 0.9.
sample MINERvA_CCQE_XSec_1DQ2_nu NEUT:/path/to/my/neutfile.root DEFAULT 0.9
Example 6 : MiniBooNE CCQE comparison using a NuWro?, shifting the MC by 0.9 / 1.0 but also adding a normalisation penalty to the likelihood (option=NORM)
sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/my/neutfile.root NORM 0.9
Example 7 : Include both MiniBooNE CCQE and CC1pip data
sample MiniBooNE_CC1pi_XSec_1DTpi_nu NEUT:/path/to/my/neutfile.root sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/my/neutfile.root
Fixed Parameter Structure
Fixed parameters can be specified by using any of the 'parameter' type structures. You must specify the type of parameter first, before listing the name, starting value, and state. These structures are read by nuiscomp, nuismin, and nuissyst
TYPE_parameter NAME VALUE
- TYPE : Type of RW parameter, (e.g. genie_parameter, neut_parameter, norm_parameter)
- NAME : Name of RW parameter, can be any string given in the RW engine. In GENIE this list is given in $GENIE/src/ReWeight/GSyst.h.
For normalisation parameters the name of the dial corresponds to SAMPLENAME_norm. (e.g. 'MiniBooNE_CCQELike_XSec_1DQ2_nu_norm')
- VALUE : Starting value for the dial. In general for RW engine parameters this is given in terms of 1-sigma variations away from the nominal, so that VALUE=0.0 is the nominal generator value. For everything else, like normalisation parameters, this value is in units of the true value.
Multiple parameter structures can be listed in the nuisance card file to make comparisons with many model parameters changed at once.
NOTE: Running with RW parameters changed in Generators requires that specific Generator to be built and have NUISANCE built against it. E.g. to using GENIE RW, you need to have a working install of GENIE+GENIE-RW and NUISANCE built against that version.
Example 1 : Fixed GENIE RW 'MaCCQE' to +1 sigma
genie_parameter MaCCQE +1.0
Example 2 : Fixed NuWro? RW 'kNuwro_Ma_CCQE' to -1 sigma
nuwro_parameter kNuwro_Ma_CCQE -1.0
Example 3 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma
neut_parameter MaCCQE -1.0 neut_parameter MaCCRES +1.0
Example 4 : Change MiniBooNE sample normalisation (alternative to using sample NORMVALUE option)
norm_parameter MiniBooNE_CCQE_XSec_1DQ2_nu_norm 0.9 sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/neutinput.root
Free Parameter Structure
Free parameters can be specified by using any of the 'parameter' type structures. You must specify the type of parameter first, before listing the name, starting value, lower and upper limits, step size and state. This is an extension of the fixed parameter case to include extra information needed by routines that vary parameters. These structures are read by nuismin, and nuissyst. It is possible to use these structures also in nuiscomp, but the dial limits and step sizes will be ignored, fixing the parameter at the chosen value instead.
TYPE_parameter NAME VALUE LOW HIGH STEP STATE
- TYPE : Type of RW parameter, (e.g. genie_parameter, neut_parameter, norm_parameter)
- NAME : Name of RW parameter, can be any string given in the RW engine. In GENIE this list is given in $GENIE/src/ReWeight/GSyst.h.
For normalisation parameters the name of the dial corresponds to SAMPLENAME_norm. (e.g. 'MiniBooNE_CCQELike_XSec_1DQ2_nu_norm')
- VALUE : Starting value for the dial. In general for RW engine parameters this is given in terms of 1-sigma variations away from the nominal, so that VALUE=0.0 is the nominal generator value. For everything else, like normalisation parameters, this value is in units of the true value.
- LOW : Lower limit of the dial in the same units as VALUE
- HIGH : Upper limit of the dial in the same units as VALUE
- STEP : Starting step size of the dial in the same units as VALUE. This is the stepsize passed to the minimizer, as well as the step size used in various functions that randomly scan the parameter space.
- STATE : State of the dial. This can be left as FREE or FIX. If FREE this tells NUISANCE that we will allow the dial to be varied. If FIX then NUISANCE will make sure it is left at VALUE for the entire time. FIX is a useful option if you decide you would like to stop a single parameter being floated but would like to keep its limit definitions in case you would like to vary it at a later point.
Multiple parameter structures can be listed in the nuisance card file to make comparisons with many model parameters changed at once.
NOTE: Running with RW parameters changed in Generators requires that specific Generator to be built and have NUISANCE built against it. E.g. to using GENIE RW, you need to have a working install of GENIE+GENIE-RW and NUISANCE built against that version.
Example 1 : Free GENIE RW 'MaCCQE' to starting at 0.0 and between -1.0 and 1.0 sigma
genie_parameter MaCCQE 0.0 -1.0 1.0 0.5 FREE
Example 2 : Free NuWro? RW 'kNuwro_Ma_CCQE'
nuwro_parameter kNuwro_Ma_CCQE 0.0 -1.0 1.0 0.5 FREE
Example 3 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma. Vary MaCCQE.
neut_parameter MaCCQE -1.0 -3.0 3.0 1.0 FREE neut_parameter MaCCRES +1.0 FIX
Example 4 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma. Vary MaCCQE.
neut_parameter MaCCQE -1.0 -3.0 3.0 1.0 FREE neut_parameter MaCCRES +1.0 -3.0 3.0 1.0 FIX
Example 5 : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma. Vary both.
neut_parameter MaCCQE -1.0 -3.0 3.0 1.0 FREE neut_parameter MaCCRES +1.0 -3.0 3.0 1.0 FREE
Example 6 : Vary MiniBooNE sample normalisation between user chosen limits (alternative to using sample NORMVALUE option)
norm_parameter MiniBooNE_CCQE_XSec_1DQ2_nu_norm 0.9 0.8 1.1 0.05 FREE sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/neutinput.root
Covariance Structure
Covariance objects are used by NUISANCE to assign likelihood penalty terms to parameters as well as define appropriate parameter throws when studying systematic uncertainties. They can be specified in the card file by providing the 'covar' structure, plus an ID, input definition, and state.
covar ID TYPE:INPUT STATE
- ID : Unique ID specified by the user so they can keep track of this covariance class in the output file. Saved objects from this covariance will be labeled 'ID_label' (e.g. ID_central).
- TYPE : Covariance type. There are multiple ways to define a covariance, with some examples of these types below.
- INPUT : Input definition, this depends a lot on what the TYPE is defined as. Some examples are below.
- STATE : State of this covariance, used to tell NUISANCE whether it should use it to apply a likelihood penalty (e.g. GAUSPULL), use it to throw parameters (e.g. GAUSTHROW), or both.
Single uncorrelated dial covariances
To tell NUISANCE to make a covariance for a single dial, you can specifiy the covariance type as 'DIAL'
covar ID DIAL:NAME;CENTRAL;WIDTH STATE
- NAME : Name of the RW dial. This dial should have also already been setup using one of the 'parameter' structures shown above.
- CENTRAL : Central value for this dial used in the covariance. For example when you want to include the result from a previous fit, this should be set to the best fit value from that fit.
- WIDTH : Error on the parameter about the central value. Used as the Gaussian width when generating parameter throws. For example when you want to include the result from a previous fit, this should be set to the best fit error from that fit.
Example 1 : Covariance used to throw MaCCQE uncorrelated in nuissyst using MaCCQE=0.0+-1.0
genie_parameter MaCCQE 0.0 -3.0 3.0 1.0 FREE covar MaThrow DIAL:MaCCQE;0.0;1.0 GAUSTHROW
Example 2 : Covariance used to apply an additional MaCCQE pull in nuismin using MaCCQE=0.0+-1.0
genie_parameter MaCCQE 0.0 -3.0 3.0 1.0 FREE covar MaTPull DIAL:MaCCQE;0.0;1.0 GAUSPULL
Correlated dial covariances
To tell NUISANCE to make a covariance for multiple parameters that have some correlations between the, you can specifiy the covariance type as 'ROOT' and provide a ROOT input file containing the covariaince
covar ID ROOT:FILEPATH;DIAL_HIST;COVARIANCE_HIST STATE
- FILEPATH : Path to a ROOT file containing the covariance information
- DIAL_HIST : Name of a TH1D inside FILEPATH. This TH1D should be created such that each bin corresponds to a different dial, with the bin contents set to the best fit value for that dial, and the bin label set to the dial name. A good example of such a histogram is given in the standard output of nuismin called 'fit_dials'.
- COVARIANCE_HIST : Name of a TH2D inside FILEPATH. This TH2D should be created such that each bin in x and y corresponds to a different dial, with the bin contents set to the covariance between each dial according to the bins x and y position, and the bin labels set to the corresponding dial names. A good example of such a histogram is given in the standard output of nuismin called 'fit_dials_free'.
The following examples assume you have a root histogram called myfitresult.root, containing a TH1D called 'fitresults' with the dial central values in it, and a TH2D covariance histogram called 'cov', and that both these histograms describe the central values and covariance for the 'MaCCQE' and 'MaCCRES' dials.
Example 1 : Covariance ROOT file used to throw MaCCQE and MaCCRES using nuissyst
genie_parameter MaCCQE 0.0 -3.0 3.0 1.0 FREE genie_parameter MaCCRES 0.0 -3.0 3.0 1.0 FREE covar CovarThrow ROOT:/path/to/myfitresult.root;fitresults;cov GAUSTHROW
Example 1 : Covariance ROOT file used to apply a pull to MaCCQE and MaCCRES using nuismin, where fitresult.root is in the current directory
genie_parameter MaCCQE 0.0 -3.0 3.0 1.0 FREE genie_parameter MaCCRES 0.0 -3.0 3.0 1.0 FREE covar CovarPull ROOT:myfitresult.root;fitresults;cov GAUSPULL
Config Structure
Configuration options can be given at runtime by including them in the card file using the 'config' structure.
config NAME VALUE
- NAME : Name of configuration parameter
- VALUE : Value of configuration parameter
Including a configuration option will override the defaults given in 'parameters/config.xml'. Multiple configuration options can be overridden at once by listing them on separate lines in the card file.
Example 1 : Change the verbosity level
config VERBOSITY 1
Example 2 : Change the verbosity level and set the maximum number of events to run over
config VERBOSITY 2 config MAXEVENTS 25000
Comments Structure
Comments can be inserted into the simple card format by using the '#' symbol at the start of a line.
# Insert my comments here
Example 1:
# These are my config options config VERBOSITY 4
Example 2:
# I Like making comments config VERBOSITY 4 # I like it a lot. I can also comment out other structures to 'turn them off' # sample MiniBooNE_CCQE_XSec_1DQ2_nu NEUT:/path/to/neut/file.root
