Changes between Version 12 and Version 13 of CardFileExamples

Timestamp:

Jun 13, 2017, 1:40:47 PM (7 years ago)

Author:

Patrick Stowell

Comment:

--

CardFileExamples

@@ -407 +407 @@
 
 === 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  CovarThrow  ROOT:myfitresult.root;fitresults;cov  GAUSPULL
+}}}
 
 === Config Structure ===