= Card File Examples =

{{{
#!div class="important" 
'''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.

[[PageOutline(1-3,Wiki content,inline,numbered)]]

== 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.

{{{
#!div class="important" 
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.

{{{
#!div class="important" 
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.

{{{
#!div class="important" 
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" />
}}}



== 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.

{{{
#!div class="important" 
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  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.


{{{
#!div class="important" 
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  FIX
}}}

**Example 2** : Fixed NuWro RW 'kNuwro_Ma_CCQE' to -1 sigma
{{{
nuwro_parameter kNuwro_Ma_CCQE  -1.0  FIX
}}}

**Example 3** : Shift both 'MaCCQE' and 'MaCCRES' in NEUT by 1 sigma
{{{
neut_parameter MaCCQE  -1.0  FIX
neut_parameter MaCCRES +1.0  FIX
}}}

**Example 4** : Change MiniBooNE sample normalisation (alternative to using sample NORMVALUE option)
{{{
norm_parameter MiniBooNE_CCQE_XSec_1DQ2_nu_norm  0.9  FIX
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.


{{{
#!div class="important" 
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 ===
{{{
covar ID   TYPE:INPUT   STATE
}}}


{{{
covar  ID   DIAL:NAME;CENTRAL;WIDTH   STATE
}}}


{{{
covar  ID   ROOT:FILEPATH;DIAL_HIST;COVARIANCE_HIST   STATE
}}}


=== Config Structure ===

{{{
config   NAME   VALUE
}}}


=== Comments Structure ===
{{{
# Insert my comments here

# These are my config options
config  VERBOSITY  4
}}}