= [ PAGE BEING BUILT ] = NUISANCE can be used to compare or tune generator models. Some possible usage examples are given in the links below. - [wiki:UsageFlatTrees Comparing two generator models using general flat trees] - [wiki:UsageNuisComp Comparing a generator prediction to NUISANCE datasets] - [wiki:UsageNuisMin Tuning a generator model to NUISANCE datasets] - [wiki:UsagePlotLimits Plotting parameter variations] - [wiki:UsageNuisSyst Evaluating systematic uncertainty bands] = Usage Examples = This wiki outlines some potential usages for NUISANCE. If you haven't yet build the framework, do so [https://nuisance.hepforge.org/nuisanceinstallation.html here]. == The card file == NUISANCE requires the user providing an input card file which species: * The data sample(s) to compare to * The generators and their file locations * Any additional parameters that a sample might take (optional) * A normalisation factor to apply uniformly to the MC (optional) When the generator provides a reweighting interface, systematic parameters to reweight or fit can be provided. To do this we need: * Name of the systematic parameter in the reweighting engine * Current value of the parameter * Minimum value of the parameter (optional) * Maximum value of the parameter (optional) * Starting value of the parameter (optional) * Whether we `FIX` or `FREE` the parameter All NUISANCE executables run based on the card file, except for when producing generator flat trees. = Comparisons = = Tuning = Use the `nuismin` executable for tuning. The default fitter is `ROOT`'s `MIGRAD` algorithm with hard limits. The executable accepts `-f` to change this behaviour. The accepted arguments are specified in `src/Routines/MinimizerRoutines.cxx` and NUISANCE accepts all the currently implemented minimisations in ROOT::Minimizer. {{{ #!div class="code" fAllowedRoutines = ("Migrad,Simplex,Combined," "Brute,Fumili,ConjugateFR," "ConjugatePR,BFGS,BFGS2," "SteepDesc,GSLSimAn,FixAtLim,FixAtLimBreak" "Chi2Scan1D,Chi2Scan2D,Contours,ErrorBands"); }}} Separating options with commas runs them in order, e.g. `-f Simplex,Combined` will first run a `Simplex` minimisation and then propagate those results to a `Combined` minimisation. = Fake data studies with `nuismin` = `nuismin` supports fake-data studies for validation purposes. The user can set the data as the MC and see if the minimiser routine is able to reach the known parameter value. Its aim is to study fitting biases and general troubleshooting of parameter responses. It can also be useful for choosing the used fitting routines (e.g. Simplex, GSL, Migrad). Supply `-d MC` to the argument list to use the generator MC as fake-data. You can also specify reweight parameters for the fake-data in the card file by adding {{{ fake_parameter PARAM_NAME PARAM_VALUE }}} to the card file to reweight the generator to some variation and set that to the data. The data will now be some parameter variation of the MC, and (hopefully) the fit routine will converge on this parameter. You can also specify `-d FILE_LOCATION.root` to set the fake-data to a MC histogram that has been previously produced through NUISANCE. {{{ #!div class="note" The output of a fit result to `ANL_CC1ppip_XSec_1DEnu_nu` will produce some output file `MyOutput.root`, containing a histogram `ANL_CC1ppip_XSec_1DEnu_nu_MC`. Feeding `nuismin` `-d MyOutput.root` in addition to a card file specifying {{{ sample ANL_CC1ppip_XSec_1DEnu_nu MY_GENERATOR:GENERATOR_FILE_LOCATION.root` }}} will find the `_MC` histogram in `MyOutput.root` and set it to the data in the new `nuismin` program. }}} = Making a flat-tree from the generators =