Examples

Covariance matrix report

The following is an example of how to produce a report detailing the covariance matrices. In this case, the 3 point prescription is shown, for a global data at NLO.

You need to provide the central theory under the default_theory flag, corresponding to \((\mu_F, \mu_R) = (0,0)\), which for NLO is theory 163.

You need to provide the required point prescription using the flag in this section, e.g. point_prescription: "3 point" in the case below.

dataspecs associates a chosen label (speclabel) with each of the theory choices. This details what scale variation the theory corresponds to.

Here the cuts and PDF are taken from the central NLO scale-varied fit.

You must also list all the datasets you wish to include, along with any relevant c-factors.

Warning

In order to ensure backwards compatibility now that the structure of data in runcards has been updated and experiments is deprecated, you must also include metadata_group: nnpdf31_process in the runcards, so that the scale variation prescriptions are done by process rather than by experiment. See Backwards compatibility for more details.

 1meta:
 2  author: Andrea Barontini
 3  keywords: [theory uncertainties, 3-point]
 4  title: NLO 3-point variations for 5 process types - DIS CC, DIS NC, DY, Top, Jets
 5
 6default_theory:
 7  - theoryid: 163
 8
 9theoryid: 163
10  point_prescription: '3 point'
11
12
13theoryids:
14  from_: scale_variation_theories
15
16dataspecs:
17  - theoryid: 163
18   speclabel: $(\xi_F,\xi_R)=(1,1)$
19  - theoryid: 180
20   speclabel: $(\xi_F,\xi_R)=(2,2)$
21  - theoryid: 173
22   speclabel: $(\xi_F,\xi_R)=(0.5,0.5)$
23
24normalize_to: 1
25
26fit: 190315_ern_nlo_central_163_global
27use_cuts: "fromfit"
28
29pdf:
30  from_: fit
31
32dataset_inputs:
33  - dataset: NMCPD
34  - dataset: NMC
35  - dataset: SLACP
36  - dataset: SLACD
37  - dataset: BCDMSP
38  - dataset: BCDMSD
39  - dataset: CHORUSNU
40  - dataset: CHORUSNB
41  - dataset: NTVNUDMN
42  - dataset: NTVNBDMN
43  - dataset: HERACOMBNCEM
44  - dataset: HERACOMBNCEP460
45  - dataset: HERACOMBNCEP575
46  - dataset: HERACOMBNCEP820
47  - dataset: HERACOMBNCEP920
48  - dataset: HERACOMBCCEM
49  - dataset: HERACOMBCCEP
50  - dataset: HERAF2CHARM
51  - dataset: CDFZRAP
52  - dataset: D0ZRAP
53  - dataset: D0WEASY
54  - dataset: D0WMASY
55  - dataset: ATLASWZRAP36PB
56  - dataset: ATLASZHIGHMASS49FB
57  - dataset: ATLASLOMASSDY11EXT
58  - dataset: ATLASWZRAP11
59  - dataset: ATLAS1JET11
60  - dataset: ATLASZPT8TEVMDIST
61  - dataset: ATLASZPT8TEVYDIST
62  - dataset: ATLASTTBARTOT
63  - dataset: ATLASTOPDIFF8TEVTRAPNORM
64  - dataset: CMSWEASY840PB
65  - dataset: CMSWMASY47FB
66  - dataset: CMSDY2D11
67  - dataset: CMSWMU8TEV
68  - {dataset: CMSZDIFF12, cfac: [NRM]}
69  - dataset: CMSJETS11
70  - dataset: CMSTTBARTOT
71  - dataset: CMSTOPDIFF8TEVTTRAPNORM
72  - dataset: LHCBZ940PB
73  - dataset: LHCBZEE2FB
74  - {dataset: LHCBWZMU7TEV, cfac: [NRM]}
75  - {dataset: LHCBWZMU8TEV, cfac: [NRM]}
76
77
78template: template_matrix_plots.md
79
80dataset_report:
81  meta: Null
82  template_text: |
83     ## Scale variations as a function of the kinematics for {@dataset_name@}
84     {@plot_fancy_dataspecs@}
85
86actions_:
87  - report(main=true)

The corresponding template file is template_matrix_plots.md, shown below. This will produce a comprehensive set of plots and tables describing the covariance matrices.

 1Covariance matrices
 2-------------------
 3{@with default_theory@}
 4   {@plot_normexpcovmat_heatmap@}
 5   {@plot_normthcovmat_heatmap_custom@}
 6{@endwith@}
 7
 8Correlation matrices
 9--------------------
10{@with default_theory@}
11   {@plot_expcorrmat_heatmap@}
12   {@plot_thcorrmat_heatmap_custom@}
13   {@plot_expplusthcorrmat_heatmap_custom@}
14{@endwith@}
15
16Diagonal elements of covariance matrices
17----------------------------------------
18{@with default_theory@}
19   {@plot_diag_cov_comparison@}
20{@endwith@}

Validation report

Here is an example of a runcard for a report validating the theory covariance matrix against the NNLO-NLO shift. In this case the 5bar point prescription is chosen, and only a single Drell-Yan dataset is considered.

The flag orthonormalisation corresponds to the method used to orthonormalise the basis vectors of the theory covariance matrix. There are three choices:

  1. QR decomposition (choose this by default), with the flag qr

  2. Singular value decomposition, with the flag svd

  3. An in-built Gram-Schmidt orthonormalisation, with the flag gs.

_datasets_list_nlo is a list of all the experiments to be included at NLO. Defining them as a list here avoids the need to repeat the same block of text many times later on for each theory.

The remainder of the runcard is divided into two namespaces, shiftconfig and theoryconfig. The former deals with the information concerning the NNLO-NLO shift vector, and the latter with the information needed to construct the theory covariance matrix.

In shiftconfig we provide an NLO and an NNLO dataspec, so that the shift can be calculated as the difference between the two. Here we list just the experiments we wish to consider, e.g. Drell-Yan experiments in this case. Because the experiments and cuts are matched between theoryconfig and shiftconfig this means that overall only these experiments will be used, even though we can pass the whole _experiments_list_nlo list to theoryconfig.

In theoryconfig we again provide the relevant theories, in the correct order. For each dataspec we can give the _experiments_list_nlo.

 1meta:
 2  title: Theory shift validation test, 5bar point, single-dataset, QR
 3  author: Andrea Barontini
 4  keywords: [example]
 5
 6# This is a single dataset comparison. For a full comparison extend
 7# the datasets accordingly.
 8
 9metadata_group: nnpdf31_process #!IMPORTANT! Do not remove
10
11orthonormalisation: qr # Choice of orthonormalisation scheme
12                    # for finding th covmat basis. Default is qr.
13theoryid: 163
14
15fit: 190315_ern_nlo_central_163_global
16
17use_cuts: fromfit
18
19pdf:
20  from_: fit
21
22_datasets_list_nlo: &datasets_list_nlo
23  - dataset: D0WMASY
24
25shiftconfig:     # For calculating NNLO-NLO shift
26
27use_cuts: fromfit
28fit: 190315_ern_nlo_central_163_global
29
30theoryid: 163
31
32dataspecs:
33    - theoryid: 163
34      pdf:
35        from_: fit
36      speclabel: "NLO"
37      dataset_inputs:
38               - dataset: D0WMASY
39    - theoryid: 166
40      pdf:
41        from_: fit
42      speclabel: "NNLO"
43      dataset_inputs:
44           - { dataset: D0WMASY, cfac: [QCD] }
45
46theoryconfig:  # For generating theory covariance matrix
47
48theoryid: 163
49
50theoryids:
51   from_: scale_variation_theories
52
53point_prescription: '5bar point'
54
55use_cuts: fromfit
56fit: 190315_ern_nlo_central_163_global
57
58pdf:
59  from_: fit
60
61dataspecs:
62        - theoryid: 163
63          speclabel: $(\xi_F,\xi_R)=(1,1)$
64          dataset_inputs: *datasets_list_nlo
65        - theoryid: 180
66          speclabel: $(\xi_F,\xi_R)=(2,2)$
67          dataset_inputs: *datasets_list_nlo
68        - theoryid: 173
69          speclabel: $(\xi_F,\xi_R)=(0.5,0.5)$
70          dataset_inputs: *datasets_list_nlo
71        - theoryid: 175
72          speclabel: $(\xi_F,\xi_R)=(2,0.5)$
73          dataset_inputs: *datasets_list_nlo
74        - theoryid: 178
75          speclabel: $(\xi_F,\xi_R)=(0.5,2)$
76          dataset_inputs: *datasets_list_nlo
77
78template: template_test.md
79
80dataset_report:
81  meta: Null
82  template_text: |
83     ## Testing 5barpt NLO global covariance matrix against NNLO-NLO shift
84actions_:
85  - report(main=true, mathjax=True)

The corresponding file template_test.md is shown below. This will produce a range of outputs analysing the theory covariance matrix’s performance in capturing the NNLO-NLO shift.

 1% Theory shift validation test: 5 pt
 2
 3Non-zero eigenvalues
 4--------------------
 5
 6{@theory_covmat_eigenvalues@}
 7
 8Efficiency
 9----------
10
11{@efficiency@}
12
13Angle between NNLO-NLO shift vector and its component in the theory subspace
14-----------------------------------------------------------------------------------
15
16{@theta@}
17
18Ratio of projectors to eigenvalues
19----------------------------------
20
21{@projector_eigenvalue_ratio@}
22
23Condition number of projected matrix
24------------------------------------
25
26{@projected_condition_num@}
27
28Theory $\chi^2$
29---------------
30
31{@validation_theory_chi2@}
32
33Comparison of NNLO-NLO shift with theory errors from prescription
34-----------------------------------------------------------------
35
36{@shift_diag_cov_comparison@}
37
38Eigenvector plots
39-----------------
40
41{@eigenvector_plot@}
42
43$\delta_{miss}$ plot
44--------------------
45
46{@deltamiss_plot@}