= NUISCOMP =

The NUISANCE comparison application can be used to generate MC predictions that can be directly compared with published scatter data by automatically selecting the correct event topologies from a provided event sample and binning them to match the data.

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

== Running NUISCOMP == 

{{{
#!div class="important" 
'''Author:''' Patrick Stowell

'''Date:''' June 2017

'''Versions:''' `NUISANCE v2r0`, `GENIE 2.12.6`
}}}

The following example details how to run NUISANCE and produce MiniBooNE pion production comparisons to a generator of choice. Each generator requires very slightly different ways to handle NUISANCE, therefore multiple versions of this tutorial have been provided. Please use the following links to choose what generator you would like to use.

- [wiki:HowToUseNUISCOMP-GENIE I want to use GENIE]
- [wiki:HowToUseNUISCOMP-NuWro I want to use NuWro]
- [wiki:HowToUseNUISCOMP-NEUT I want to use NEUT]


= Useful NUISCOMP Commands =
There are also additional card file arguments and run time arguments that can be used with nuiscomp to help with debugging or performing slightly different comparisons. 

== Specifying fake data ==
It is possible to read in the output of a previous NUISANCE comparison run, and use it to create a fake data. 

For example, say we wanted to see if one model had the uncertainties of similar magnitude to the data, how similar is it to another model.

This can be achieved by using the '-d' command line flag in nuiscomp.

First we would need to generate a model using nuiscomp, for this example we will use NEUT to generate out predictions.
{{{
$ nuiscomp -c neut_samples.card -o neut_samples.root
}}}
Producing the following output


Then we can run our second set of comparisons, using this neut output file to create fake data
{{{
$ nuiscomp -c genie_samples.card -o genie_samples.root -d neut_samples.root
}}}



Notice that the data has now been shifted to match the original NEUT prediction we made. For comparisons the only real purpose of using this feature is to get a naive idea of how well a dataset may be able to discriminate two different models.

Its real strength is clearer when using the same fake data option also present in the nuismin application, as this allows a user approximate how bias a tuning may be if the model being fitted is an incorrect description of nature.


== Overriding config options ==
A list of default configuration options requested in the code are given in the file 'parameters/config.xml'. When NUISANCE runs this file is automatically loaded in that start.

It is also possible however, to override any of these defaults at runtime by giving them to nuiscomp. 

=== Card file override ===
One way to achieve this is to include them in your card file before all of your samples, like in the following examples setting the VERBOSITY level.

** Example 1 ** : Card verbosity change in simple card format
{{{
# config  NAME  VALUE
config VERBOSITY 4
sample MiniBooNE_CCQE_XSec_1DQ2_nu GENIE:myfiles.root
}}}

** Example 2 ** : Card verbosity change in xml card format
{{{
<!-- <config NAME='VALUE' /> -->
<config VERBOSITY='4' />

<sample name='MiniBooNE_CCQE_XSec_1DQ2_nu' input='GENIE:myfiles.root' />
}}}


=== Command line override ===
Another alternative is to override parameters on the command line using the '-q' argument.
{{{
$ nuiscomp  -q NAME=VALUE  ...
}}}

** Example 3 ** : Runtime verbosity change
{{{
$ nuiscomp -c samples.card -o samples.root -q VERBOSITY=1
}}}


== Restricting the number of events ==
The "-n" flag is included as a quick way to override the configuration value 'MAXEVENTS'.

When set to anything other than -1 this parameter will restrict the maximum number of events read from each MC file, reducing the time taken to run, but enhancing statistical uncertainty.

** Example 1 ** : Limit the number of events to 5000
{{{
$ nuiscomp -c samples.card -o samples.root -n 5000
}}}
** Example 2 ** : Limit the number of events to 1E6
{{{
$ nuiscomp -c samples.card -o samples.root -n 1000000
}}}
** Example 3 ** : Limit the number of events to 1E6
{{{
$ nuiscomp -c samples.card -o samples.root -q MAXEVENTS=1000000
}}}
** Example 4 ** : Run with the default limit given in 'parameters/config.xml'
{{{
$ nuiscomp -c samples.card -o samples.root
}}}
** Example 5 ** : Run with no event limit
{{{
$ nuiscomp -c samples.card -o samples.root -n -1
}}}
** Example 6 ** : Run with no event limit
{{{
$ nuiscomp -c samples.card -o samples.root -q MAXEVENTS=-1
}}}

{{{
#!div class="important"
'''WARNING:'''
Restricting the number of events doesn't work for event samples that have had to be 'spliced' together by NUISANCE.

For example to make NEUT comparisons to MiniBooNE_CCQELike_XSec_1DQ2_antinu data, both a numb and numu event file need to be passed in so that NUISANCE can add them together to make the prediction. If MAXEVENTS was not set to '-1' for this sample, the results will be incorrect as the relative proportions of events will be incorrectly sampled!
}}}

== Increasing or decreasing Verbosity ==
The +/-e and +/-v flags are reserved to increase or decrease the NUISANCE verbosity quickly at runtime.

** Example 1 ** : Increase verbosity by one level 
{{{
$ nuiscomp -c samples.card -o samples.root +v
}}}
** Example 2 ** : Decrease verbosity by one level 
{{{
$ nuiscomp -c samples.card -o samples.root -v
}}}
** Example 3 ** : Increase verbosity by two levels 
{{{
$ nuiscomp -c samples.card -o samples.root +v +v
}}}
** Example 4 ** : Decrease error verbosity by one level 
{{{
$ nuiscomp -c samples.card -o samples.root -e
}}}
** Example 5 ** : Increase error verbosity by two levels 
{{{
$ nuiscomp -c samples.card -o samples.root +e +e
}}}