Changes between Version 15 and Version 16 of CardFileExamples

Timestamp:

Jun 13, 2017, 2:04:45 PM (7 years ago)

Author:

Patrick Stowell

Comment:

--

CardFileExamples

@@ -234 +234 @@
 
 
+
+=== 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 ==
 
@@ -460 +570 @@
 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:myfitresult.root;fitresults;cov  GAUSPULL
+covar  CovarPull  ROOT:myfitresult.root;fitresults;cov  GAUSPULL
 }}}