Analysis Organisation
The examples illustrating the various use cases cover relatively simple phenomenological analyses. The number of observables, parameters, and statistical constraints is rather small. Typical analyses carried out using EOS require a high degree of organisation. To this end EOS provides the means to store one or more analysis within an external file, a so-called analysis file. This is beneficial in particular when the stored analyses share common elements.
The Analysis Description Format
Every EOS analysis file is a YAML file that describe the individual steps of one or more Bayesina analysis. At the top level, the format includes the following YAML keys:
priors(mandatory) — The list of priors within the analysis.
likelihoods(mandatory) — The list of likelihoods within the analysis..
posteriors(mandatory) — The list of posteriors within the analysis.
predictions(optional) — The list of theory predictions within the analysis.
observables(optional) — The list of custom observables defined for the scope of the analysis.
The following example illustrates the analysis file format at the hand of a real-world example.
Example examples/b-to-u-l-nu.yaml
likelihoods:
- name: TH-pi
constraints:
- 'B->pi::form-factors[f_+,f_0,f_T]@LMvD:2021A;form-factors=BCL2008-4'
- 'B->pi::f_++f_0+f_T@FNAL+MILC:2015C;form-factors=BCL2008-4'
- 'B->pi::f_++f_0@RBC+UKQCD:2015A;form-factors=BCL2008-4'
- name: EXP-pi
constraints:
- 'B^0->pi^-l^+nu::BR@HFLAV:2019A;form-factors=BCL2008-4'
priors:
- name: CKM
parameters:
- { 'parameter': 'CKM::abs(V_ub)', 'min': 3.0e-3, 'max': 4.0e-3, 'type': 'uniform' }
- name: FF-pi
parameters:
- { 'parameter': 'B->pi::f_+(0)@BCL2008' , 'min': 0.21 , 'max': 0.32 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_+^1@BCL2008' , 'min': -2.96 , 'max': -0.60 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_+^2@BCL2008' , 'min': -3.98 , 'max': 4.38 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_+^3@BCL2008' , 'min': -18.30 , 'max': 9.27 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^1@BCL2008' , 'min': -0.10 , 'max': 1.35 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^2@BCL2008' , 'min': -2.08 , 'max': 4.65 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^3@BCL2008' , 'min': -4.73 , 'max': 9.07 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^4@BCL2008' , 'min': -60.00 , 'max': 38.00 , 'type': 'uniform' }
- { 'parameter': 'B->pi::f_T(0)@BCL2008' , 'min': 0.18 , 'max': 0.32 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_T^1@BCL2008' , 'min': -3.91 , 'max': -0.33 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_T^2@BCL2008' , 'min': -4.32 , 'max': 2.00 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_T^3@BCL2008' , 'min': -7.39 , 'max': 10.60 , 'type': 'uniform' }
posteriors:
- name: CKM-pi
global_options:
l: e
model: CKM
prior:
- CKM
- FF-pi
likelihood:
- TH-pi
- EXP-pi
predictions:
- name: leptonic-BR-CKM
global_options:
model: CKM
observables:
- name: B_u->lnu::BR;l=e
- name: B_u->lnu::BR;l=mu
- name: B_u->lnu::BR;l=tau
- name: pi-dBR-CKM
global_options:
l: e
q: d
model: CKM
form-factors: BCL2008
observables:
- name: B->pilnu::dBR/dq2
kinematics: { q2: 0.05 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 1.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 2.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 3.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 3.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 4.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 4.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 5.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 5.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 6.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 6.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 7.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 7.25 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 7.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 7.75 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 8.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 8.25 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 8.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 8.75 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 9.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 9.25 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 9.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 9.75 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 10.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 10.25 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 10.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 10.75 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 11.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 11.25 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 11.5 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 11.75 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 12.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 13.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 14.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 15.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 16.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 17.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 18.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 19.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 20.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 21.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 22.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 23.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 24.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 25.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 26.0 }
- name: B->pilnu::dBR/dq2
kinematics: { q2: 27.0 }
Priors
The priors key contains a list of named priors. Each prior has one mandatory key:
name(mandatory) — The unique name of this prior.
parameters(mandatory) — The ordered list of parameters described by this prior.
For a univariate prior, parameters contains only a single prior description, which is a key/value map describing the prior.
For an uncorrelated multivariate prior, parameters contains more than one prior description.
The format for a prior description is the same as used in the Analysis constructor.
For example, the following code create two named priors CKM (univariate) and FF-pi (multivariate but uncorrelated).
priors:
- name: CKM
parameters:
- { 'parameter': 'CKM::abs(V_ub)', 'min': 3.0e-3, 'max': 4.0e-3, 'type': 'uniform' }
- name: FF-pi
parameters:
- { 'parameter': 'B->pi::f_+(0)@BCL2008' , 'min': 0.21 , 'max': 0.32 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_+^1@BCL2008' , 'min': -2.96 , 'max': -0.60 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_+^2@BCL2008' , 'min': -3.98 , 'max': 4.38 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_+^3@BCL2008' , 'min': -18.30 , 'max': 9.27 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^1@BCL2008' , 'min': -0.10 , 'max': 1.35 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^2@BCL2008' , 'min': -2.08 , 'max': 4.65 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^3@BCL2008' , 'min': -4.73 , 'max': 9.07 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_0^4@BCL2008' , 'min': -60.00 , 'max': 38.00 , 'type': 'uniform' }
- { 'parameter': 'B->pi::f_T(0)@BCL2008' , 'min': 0.18 , 'max': 0.32 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_T^1@BCL2008' , 'min': -3.91 , 'max': -0.33 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_T^2@BCL2008' , 'min': -4.32 , 'max': 2.00 , 'type': 'uniform' }
- { 'parameter': 'B->pi::b_T^3@BCL2008' , 'min': -7.39 , 'max': 10.60 , 'type': 'uniform' }
For a correlated multivariate prior, parameters contains a single element consisting of a key/value pair.
The mandatorys key is constraint and the value is the qualified name of an EOS constraint.
The following example illustrates the organisation of a correlated multivariate prior.
priors:
- name: FF-rho
parameters:
- { 'constraint': 'B->rho::FormFactors[parametric,LCSR]@BSZ:2015A' }
Likelihoods
The likelihoods key contains a list of named likelihoods. Each likelihood has two mandatory keys:
name(mandatory) — The unique name of this likelihood.
constraints(mandatory) — The ordered list of EOS constraint names that comprise this likelihood.
The following example illustrates the organisation of a likelihood.
- name: EXP-pi
constraints:
- 'B^0->pi^-l^+nu::BR@HFLAV:2019A;form-factors=BCL2008-4'
Posteriors
The posteriors key contains a list of named posteriors. Each posterior contains two mandator and various optional keys:
name(mandatory) — The unique name of this posterior.
prior(mandatory) — The ordered list of named priors that are used as part of this posterior.
likelihood(mandatory) — The ordered list of named likelihoods that are used as part of this posterior.
global_options(optional) — A key/value map providing global options, i.e., options that apply to all observables used within this posterior.
fixed_parameters(optional) — A key/value map providing values for parameters that deviate from the default values.
The following example illustrates the organisation of a posterior.
posteriors:
- name: CKM-pi
global_options:
l: e
model: CKM
prior:
- CKM
- FF-pi
likelihood:
- TH-pi
- EXP-pi
Observables
New observables can be defined and used in the analysis description by following the syntax described in the corresponding section.
For example, the following code defines the ratio of two \(B \to \pi\) form-factors as a new observable.
observables:
'B->pi::f_+(q2)/f_0(q2)':
latex: '$\frac{f_+}{f_0}$'
unit: '1'
options: {}
expression:
'<<B->pi::f_+(q2)>> / <<B->pi::f_0(q2)>>'