==============================================================================================
Programme: Gfitter -- A Generic Fitting Framework for HEP Data Analysis
Home page: http://cern.ch/Gfitter
==============================================================================================

This file describes the syntax of the Gfitter XML steering card via an educated example
containing all possible options:

<JobConfiguration JobName="DataGEW">

  ============= Driving settings =======================================================

  Here you can add any flag you would like to use in your package
  they are retrieved in the code via:
     const TString& myWord  = gStore()->GetVariable( "Flags::MyWord" )->GetStringValue();
     Double_t       myFloat = gStore()->GetVariable( "Flags::MyFloat" )->GetFloatValue();

  <Flags
    MyFlag     = "MyWord"         // a string example
    MyFloat    = "10.1"           // a floating point number example

    // Concrete example for flags:
    logMH      = "10000"          // use logarithmic MH scale
    />
  
  <Fitter
    FitterType = "Minuit"         // which Fitter to use? ATM only "Minuit" implemented
    UseImprove = "F"              // flag to switch on Minuit IMPROVE  
    UseMinos   = "T"              // flag to switch on Minuit IMMINOS  
    NoWarnings = "T"              // flag to switch off the MINUIT warning
    PrintLevel = "-1"             // the PrintLevel of Minuit (-1=none, 0=some, 1=all garbage)
    />

  <PreFitter
    PreFitterType = "Genetic"     // which PreFitter to use? results are input to Fitter. ATM only "Genetic" implemented
    PopulationSize = "100"        //   
    ConvSteps      = "20"         //
    ConvCrit       = "0.0001"     //
    ScSteps        = "10"         //
    ScRate         = "5"          //
    ScFactor       = "0.95"       //
    />
  

  <Files                          // used for output files     
    GraphicsOut  = "GEW.root"     // the root files  
    ResultFormat = "Latex:HTML"   // format of the result output files: Latex and/or HTML (at present)
    />
  
  <Actions
    Scan1D   = "F:MH:Nbins=50"    // specification of 1D scanning action, syntax: "A:B:...", with:
                                  //    A = "F"/"T" action true or false
                                  //    B = "MyPar" parameter to be scanned (can add more: "B:C:...")
    Scan2D   = "F:MH:mt:Nbins=50" //       // specification of 2D scanning action, syntax: "A:B:C", with:
                                  //    A = "F"/"T" action true or false
                                  //    B = "MyPar1" first parameter to scan (abscissa)
                                  //    C = "MyPar2" second parameter to scan (ordinate)
    Evaluate    = "T"             // "F"/"T" a single global fit
    EvaluateToy = "T"             // "F"/"T" a single global fit, followed by a toy test to determine the p-value
    />

  <Data>
   
    ============= Input parameters =======================================================

    We distinguish three types of input parameters:
    
       1) Parameters that are observables predicted by a theory (example: GEW::MW)
          (characteristics: parameter not free in fit, but added to chi2 function)
    
       2) Parameters that are observables not predicted by a theory (example: p_top)
          (characteristics: parameter is freely varying in fit, and added to chi2 function)
    
       3) Parameters that are theory (or model) input (example: lambda_MSbar)
          (characteristics: parameter is free in fit, not present in chi2 function)
    

    NOTE: Gfitter distinguishes 2 types of errors: "Gaussian" errors and "Ranges",
          where the latter error signifies a constant likelihood, ie, a freely varying 
          parameter in the fit

    ---- default parameter setting:

    <Parameter 
      Name      = "MyPar"              // name of parameter
      Alias     = "MyPar_Experiment"   // alias of parameter (optional - default: same as Name)
                                          (the alias is used when defining correlations)
      Value     = "1.5 +- 0.2"         // central value and symmstric error         
      FitLimits = "[0:10]"             // fit limits if parameter is varying in fit (optional, 
                                          if nothing is given, the parameter is unlimited)
      Active    = "T"                  // enters fit
      />

    For the interpretation of the "Value" field, one has the following 6 options:
       C0: [x1:x2]                          // the paremter varies freely in the given range 
       C1: x +- dx_gauss                    // symmetric errors
       C2: x +- dx_gauss +- dx_range        // assymetric errors
       C3: x + dxp_gauss -  dxm_gauss
       C4: x + dxp_gauss -  dxm_gauss +- dx_range
       C5: x +- dx_gauss +  dxp_range -  dxm_range
       C6: x + dxp_gauss -  dxm_gauss +  dxp_range - dxm_range
    
    
    ---- Using a parameter estimator curve that can be translated into a chi-squared
         as input:

    <Parameter                         // example for a Parameter entering via a curve
      Name      = "MyPar"              // the name 
      File      = "test.root"          // the root file with the curve
      Reference = "directory/likeli"   // the root input object (only TH1 implemented)
      ChiSq     = "-2*log(likeli)"     // the formula to translate the content of "Reference"
                                       // into a delta_chi2 
      Active    = "T"                  // use in fit
      />

    ---- Allowing a parameter to be rescaled by another parameter (useful, eg, in case 
         of correlated systematic errors)

    The following setting describes the treatment of systematic correlations between 
    parameters, and the possibility of rescaling them. 
    
    Example: the measurement of a parameter "MyObservable" may have systematic uncertainties 
             due to the limited knowledge of other parameters "alpha" and "beta", which 
              can also be measured, and for which the experimental information evolves 
             overtime. One can use the systematic errors given for these sources in the 
             first time (at the publication of the measurement "MyObservable" to rescale 
             the measurement according to the updated systematic sources.

    In the example below, the systematic error for "MyObservable" due to alpha (the 
    RefValue given in the parameter fields of alpha) is +- 10. If Value == RefValue (for
    both central values and errors), nothing will change, and the total error of 
    "MyObservable" is Sqrt(2^2 + 10^2 + 5^2) (positive) and Sqrt(2^2 + 10^2 + 2^2) (negative).
    In the case of alpha, a new measurement of that paramter allowed to reduce the error 
    by two, and also changed the central value. This will lead to a reduction of the 
    systematic error of "MyObservable" due to alpha to +- 5, and will also shift its
    central value by +1*10 (the original dependence of MyObservable on alpha).
    
    As shown in the example below, any number of such dependencies can be added to a
    parameter, and asymmetric errors can be used anywhere. Also (see beta), the correlation
    between a measurement and a systematic source can be negative. 

    <Parameter 
		Name      = "MyObservable" 
		Value     = "10 +- 2  +- 10(alpha) +5 -2(-beta)"  // here, the value of "MyObservable" 
                                                        // depends on the syst sources alpha, beta
		Active    = "T" 
      />

    <Parameter 
		Name      = "alpha" 
		Value     = "1 +- 0.5"
		RefValue  = "0 +- 1"
		Active    = "T" 
      />

    <Parameter 
		Name      = "beta" 
		Value     = "0 +0.5 -0.3"
		RefValue  = "0 +- 1"
		Active    = "T" 
      />

  ============= parameter correlations =================================================

  Correlation matrices can be defined between any parameters, but at present ONLY parameters
  with SYMMETRIC errors can have correlations. Several correlation matrices can be defined,
  if correlations are packed between ensembles of independent parameters.

  <Correlations
      Active       = "T" 
      ParAliases   = "MyObs1_CDF:MyObs1_D0   
      Coefficients = "  1    : -0.18 
                                1    "
    />

  <Correlations
      Active       = "T" 
      ParAliases   = "... " // add more parameters
      Coefficients = "... " // add more correlations
    />

</JobConfiguration>
