v1.1

You are reading the documentation for EOS v1.1, which is not necessarily the latest release. Go to the documentation for the latest release.

Python API

Basic Classes

EOS provides its basic functionality via the main eos module.

class eos.Constraint

Represents a named experimental or theoretical constraint known to EOS.

A constraint bundles one or more observables with the log-likelihood blocks that constrain them. New objects are created using the make static method. See also the complete list of constraints.

blocks((Constraint)arg1) → object: Returns an iterator over the log-likelihood blocks that make up the constraint.

static make((QualifiedName)name, (Options)options) → Constraint

Makes a new Constraint object from the internal database of constraints.

Parameters:

name (eos.QualifiedName) –
The name of the constraint. See the complete list of constraints.
options (eos.Options) – The set of options passed to the observables entering the constraint.

Returns:

The new constraint object.

Return type:

eos.Constraint

name((Constraint)self) → QualifiedName

Returns the name of the constraint.

Return type:: eos.QualifiedName

observables((Constraint)arg1) → object: Returns an iterator over the observables entering the constraint.

class eos.ConstraintEntry

Describes a single constraint known to EOS and acts as its factory.

A constraint entry records a constraint’s name, type, the observables it constrains, and the references it originates from. Entries are obtained by iterating or indexing eos.Constraints, and can create the corresponding eos.Constraint (via make) or an equivalent eos.LogPrior (via make_prior).

static deserialize((QualifiedName)name, (str)yaml) → ConstraintEntry

Creates a new ConstraintEntry by deserializing its YAML representation.

Parameters:

name (eos.QualifiedName) – The name of the constraint.
yaml (str) – The YAML representation of the constraint entry.

Returns:

The new constraint entry object.

Return type:

eos.ConstraintEntry

make((ConstraintEntry)self, (QualifiedName)name, (Options)options) → Constraint

Makes a new Constraint object from this entry.

Parameters:

name (eos.QualifiedName) – The name of the constraint.
options (eos.Options) – The set of options passed to the observables entering the constraint.

Returns:

The new constraint object.

Return type:

eos.Constraint

make_prior((ConstraintEntry)self, (_Parameters)parameters, (Options)options) → LogPrior

Makes a new LogPrior object from this entry.

Parameters:

parameters (eos.Parameters) – The set of parameters to which the prior is bound.
options (eos.Options) – The set of options passed to the observables entering the constraint.

Returns:

The new log(prior) object.

Return type:

eos.LogPrior

name((ConstraintEntry)self) → QualifiedName

Returns the name of the constraint.

Return type:: eos.QualifiedName

observables((ConstraintEntry)arg1) → object: Returns an iterator over the names of the observables entering the constraint.

references((ConstraintEntry)arg1) → object: Returns an iterator over the names of the references from which the constraint originates.

serialize((ConstraintEntry)self) → str

Returns the YAML representation of the constraint entry as a string.

Return type:: str

type((ConstraintEntry)self) → str

Returns the type description of the constraint, e.g. Gaussian or MultivariateGaussian.

Return type:: str

class eos.Constraints(prefix=None, name=None, suffix=None)

Represents the complete list of constraints known to EOS.

Objects of this class are visualized as tables in Jupyter notebooks for easy overview. Filters can be applied through keyword arguments to the initialization.

Parameters:

prefix (str) – Only show constraints whose qualified names contain the provided prefix in their prefix part.
name (str) – Only show constraints whose qualified names contain the provided name in their name part.
suffix (str) – Only show constraints whose qualified names contain the provided suffix in their suffix part.

See also the complete list of constraints in this documentation.

insert((_Constraints)self, (QualifiedName)name, (str)entry) → ConstraintEntry

Inserts a new constraint into EOS at run time by parsing its YAML representation.

Parameters:

name (eos.QualifiedName) – The name of the new constraint.
entry (str) – The YAML representation of the constraint entry.

Returns:

The newly inserted constraint entry.

Return type:

eos.ConstraintEntry

class eos.Kinematics

Represents the set of kinematic variables relevant to an observable.

Initialize a new set of kinematic variables. The inital set of variables and their initial set of values can be provided through keyword arguments, e.g. using

k = eos.Kinematics(q2=0.4, k2=0.0)                      # default keyword arguments
k = eos.Kinematics({'q2': 0.4, 'cos(theta_l)': -1.0})   # use a dictionary if variable names are not
                                                        # valid python identifiers

declare((Kinematics)self, (str)name, (float)value) → KinematicVariable

Declares a new kinematic variable.

Parameters:

name (str) – The name of the new kinematic variable.
value (float) – The initial value for the new kinematic variable.

class eos.KinematicVariable

Represents a single kinematic variable within a Kinematics object.

Users cannot directly create new objects of this class. They are obtained from a Kinematics object by name, by iteration, or as the result of Kinematics.declare.

An object of this class is a handle to the variable rather than a copy of its value: set changes the value seen by the owning Kinematics object and by everything bound to it.

evaluate((KinematicVariable)self) → float

Returns the current value of this kinematic variable.

Return type:: float

name((KinematicVariable)self) → str

Returns the name of this kinematic variable.

Return type:: str

set((KinematicVariable)self, (float)value) → None

Sets the value of this kinematic variable.

Parameters:: value (float) – The new value of the kinematic variable.

class eos.LogLikelihood

Represents the log(likelihood) of a Bayesian analysis undertaken with the Analysis class.

add((LogLikelihood)self, (Constraint)constraint) → None

Adds a constraint from the internal database to the likelihood.

param constraint:

The constraint to add.

type constraint:

eos.Constraint

add( (LogLikelihood)self, (LogLikelihoodBlock)block) -> None :

Adds a single log-likelihood block to the likelihood.

param block:

The log-likelihood block to add.

type block:

eos.LogLikelihoodBlock

evaluate((LogLikelihood)self) → float

Evaluates the log(likelihood) for the current parameter point.

Return type:: float

observable_cache((LogLikelihood)self) → ObservableCache

Returns the observable cache shared by the likelihood’s blocks.

Return type:: eos.ObservableCache

class eos.LogLikelihoodBlock

Represents a single block (term) of a LogLikelihood.

A block encapsulates the likelihood contribution of one or more observables, such as a (multivariate) Gaussian constraint or a user-provided external likelihood. New blocks are created using the static factory methods, e.g. External and Unbinned1D, and added to a likelihood via LogLikelihood.add.

static External((ObservableCache)cache, (object)factory) → LogLikelihoodBlock

Create a new external log-likelihood block.

Parameters:

cache (eos.ObservableCache) – The observable cache used by the total log-likelihood.
factory (collections.abc.Callable) – The factory method used to initialize the external log-likelihood block.

Returns:

The new block.

Return type:

eos.LogLikelihoodBlock

static Unbinned1D(cache, pdf_name, kinematics, options, resolution, observations)

Create a new unbinned log-likelihood block with a resolution function.

The named SignalPDF is evaluated on the supplied grid and convolved with the resolution function via a discrete Fourier transform, yielding the resolution-smeared PDF sampled on the grid. The log-likelihood is then the sum over the observed events of the logarithm of the smeared PDF, evaluated at each observation by linear interpolation from the surrounding grid points.

Parameters:

cache (eos.ObservableCache) – The observable cache used by the total log-likelihood.
pdf_name (eos.QualifiedName) – The name of the SignalPDF to evaluate at each grid point.
kinematics (list of eos.Kinematics) – One Kinematics object per grid point.
options (eos.Options) – Options forwarded to the SignalPDF constructor.
resolution (list of float) – Discretised resolution function on the same grid, in natural (centred) order, i.e. the zero offset (the peak of a symmetric kernel) sits at the centre of the array. The kernel is converted to the wrap-around order expected by the underlying circular convolution via numpy.fft.ifftshift() before the block is constructed.
observations (list of eos.Kinematics) – The observed events, expressed as kinematic variables.

Returns:

The new block.

Return type:

eos.LogLikelihoodBlock

Note

The convolution underlying the unbinned likelihood is circular. The grid must therefore be padded with a sufficiently large region in which both the PDF and the resolution function are negligible, so that no appreciable density wraps across the boundary.

evaluate((LogLikelihoodBlock)self) → float

Evaluate the log-likelihood block at the current parameter point.

Return type:: float

number_of_observations((LogLikelihoodBlock)self) → int

Retrieve the number of observations in this block.

Return type:: int

class eos.LogPrior

Represents a Bayesian prior on the log scale.

New LogPrior objects can only be created using the capitalized static methods: LogPrior.Uniform(), LogPrior.Flat(), LogPrior.Gaussian(), LogPrior.CurtailedGauss(), LogPrior.Poisson(), LogPrior.Scale(), and LogPrior.Transform().

static CurtailedGauss((_Parameters)parameters, (str)name, (float)min, (float)max, (float)lower, (float)central, (float)upper) → LogPrior

Returns a new (curtailed) Gaussian prior as a LogPrior.

The prior’s support is provided by the pair of min and max parameters, with the approximate 68% probability interval [lower, upper] and the mode provided by the parameter central.

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
name (str) – The name of the parameter for which the LogPrior is defined.
min (float) – The minimum value that the parameter is allowed to take.
max (float) – The maximum value that the parameter is allowed to take.
lower (float) – The lower boundary of the 68% probability interval.
central (float) – The mode and median of the prior.
upper (float) – The upper boundary of the 68% probability interval.

static External((_Parameters)parameters, (object)factory) → LogPrior

Returns a new external prior as a LogPrior.

The prior’s behaviour is provided by a user-supplied Python object created by the factory callable. The factory is invoked with a single Parameters argument and must return an object that exposes:

a callable evaluate() returning the logarithm of the prior’s probability density;

a callable sample() that sets the varied parameters from their generator values;

a callable compute_cdf() that sets the varied parameters’ generator values from their current values;

an iterable varied_parameters of the names of the parameters varied by this prior; and

a boolean informative attribute.

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
factory (collections.abc.Callable) – The factory callable used to initialize the external prior.

static Flat((_Parameters)parameters, (str)name, (float)min, (float)max) → LogPrior: Alias for LogPrior.Uniform().

static Gaussian((_Parameters)parameters, (QualifiedName)name, (float)mu, (float)sigma) → LogPrior

Returns a new Gaussian prior as a LogPrior.

The priors support is infinite. The mode is provided by the parameter mu and the standard deviation by the parameter sigma.

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
name (str) – The name of the parameter for which the LogPrior is defined.
mu (float) – The mode of the prior.
sigma (float) – The standard deviation of the prior, which must be strictly positive.

static Poisson((_Parameters)parameters, (str)name, (float)k) → LogPrior

Returns a new Poisson prior as a LogPrior.

The priors support is infinite. The mode is provided by the parameter k.

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
name (str) – The name of the parameter for which the LogPrior is defined.
k (float) – The mode of the prior, which must be strictly positive.

static Scale((_Parameters)parameters, (str)name, (float)min, (float)max, (float)mu_0, (float)scale) → LogPrior

Returns a new Scale prior as a LogPrior.

The prior’s support is provided by the pair of min and max parameters, which should coincide with [mu_0 / scale, mu_0 * scale]. The PDF is chosen such that a renormalization scale is varied in this range and with central value mu_0 such that \(\ln x / \mu_0\) is uniformly distributed in the interval \([-\ln \lambda, +\ln \lambda]\).

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
name (str) – The name of the parameter for which the LogPrior is defined.
min (float) – The minimum value that the parameter is allowed to take.
max (float) – The maximum value that the parameter is allowed to take.
mu_0 (float) – The central value of the parameter, which must be strictly positive.
scale (float) – The scale factor, which must be strictly positive.

static Transform((_Parameters)parameters, (object)name, (object)shift, (object)transform, (object)min, (object)max) → LogPrior

Returns a new transformed uniform prior from original uniform priors as a LogPrior.

The prior’s support is infinite.

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
name (str) – The name of the parameters for which the LogPrior is defined.
shift (collections.abc.Sequence of float) – The shift vector to the original set of parameters
transform (numpy.ndarray) – The matrix that transforms the original set of parameters
min (collections.abc.Sequence of float) – The vector of minimum values that the parameters are allowed to take.
max (collections.abc.Sequence of float) – The vector of maximum values that the parameters are allowed to take.

static Uniform((_Parameters)parameters, (str)name, (float)min, (float)max) → LogPrior

Returns a new uniform prior as a LogPrior.

The prior’s support is provided by the range parameter.

Parameters:

parameters (eos.Parameters) – The parameters to which this LogPrior is bound.
name (str) – The name of the parameter for which the LogPrior is defined.
min (float) – The minimum value that the parameter is allowed to take.
max (float) – The maximum value that the parameter is allowed to take.

compute_cdf((LogPrior)self) → None: Returns the cumulative probabilities \(p\) assigned to each parameter via its Parameter.evaluate_generator() method.

evaluate((LogPrior)self) → float

Returns the logarithm of the prior’s probability density at the current parameter values.

Return type:: float

sample((LogPrior)self) → None: Sets its parameters’ values corresponding to the cumulative propability \(p\) assigned to each parameter via its Parameter.set_generator() method.

varied_parameters((LogPrior)arg1) → object: Returns an iterator over the Parameter objects varied by this prior.

class eos.LogPosterior

Represents a Bayesian posterior on the log scale.

add((LogPosterior)self, (LogPrior)prior, (bool)nuisance) → bool

Adds a new prior object to the posterior.

Parameters:

prior (eos.LogPrior) – The prior to add to the posterior.
nuisance (bool) – Whether the prior’s parameters shall be treated as nuisance parameters.

Returns:

Whether the prior was added successfully.

Return type:

bool

evaluate((LogPosterior)self) → float

Returns the posterior probability density.

Return type:: float

log_likelihood((LogPosterior)self) → LogLikelihood

Returns the likelihood object used as part of the posterior.

Return type:: eos.LogLikelihood

log_priors((LogPosterior)arg1) → object: Returns a range of LogPrior objects used as part of the posterior.

class eos.Model

Represents a physics model, providing access to the CKM matrix elements, quark masses in various renormalization schemes, the strong coupling, and Wilson coefficients.

New objects are created using the make static method.

alpha_s((Model)self, (float)mu) → float

Returns the strong coupling \(\alpha_s(\mu)\) at the renormalization scale mu.

Parameters:: mu (float) – The renormalization scale in GeV.
Return type:: float

ckm_cb((Model)self) → complex

Returns the CKM matrix element \(V_{cb}\).

Return type:: complex

ckm_cd((Model)self) → complex

Returns the CKM matrix element \(V_{cd}\).

Return type:: complex

ckm_cs((Model)self) → complex

Returns the CKM matrix element \(V_{cs}\).

Return type:: complex

ckm_tb((Model)self) → complex

Returns the CKM matrix element \(V_{tb}\).

Return type:: complex

ckm_td((Model)self) → complex

Returns the CKM matrix element \(V_{td}\).

Return type:: complex

ckm_ts((Model)self) → complex

Returns the CKM matrix element \(V_{ts}\).

Return type:: complex

ckm_ub((Model)self) → complex

Returns the CKM matrix element \(V_{ub}\).

Return type:: complex

ckm_ud((Model)self) → complex

Returns the CKM matrix element \(V_{ud}\).

Return type:: complex

ckm_us((Model)self) → complex

Returns the CKM matrix element \(V_{us}\).

Return type:: complex

m_b_kin((Model)self, (float)mu_kin) → float

Returns the bottom-quark kinetic mass \(m_b^{\text{kin}}(\mu_{\text{kin}})\) in GeV.

Parameters:: mu_kin (float) – The kinetic cutoff scale in GeV.
Return type:: float

m_b_msbar((Model)self, (float)mu) → float

Returns the bottom-quark \(\overline{\text{MS}}\) mass \(\overline{m}_b(\mu)\) in GeV.

Parameters:: mu (float) – The renormalization scale in GeV.
Return type:: float

m_b_pole((Model)self, (int)loop_order) → float

Returns the bottom-quark pole mass in GeV.

param loop_order:

The loop order of the conversion from the \(\overline{\text{MS}}\) mass. Defaults to 3.

type loop_order:

int

rtype:

float

m_b_pole( (Model)self) -> float :

Returns the bottom-quark pole mass in GeV at the default loop order.

rtype:

float

m_c_kin((Model)self, (float)mu_kin) → float

Returns the charm-quark kinetic mass \(m_c^{\text{kin}}(\mu_{\text{kin}})\) in GeV.

Parameters:: mu_kin (float) – The kinetic cutoff scale in GeV.
Return type:: float

m_c_msbar((Model)self, (float)mu) → float

Returns the charm-quark \(\overline{\text{MS}}\) mass \(\overline{m}_c(\mu)\) in GeV.

Parameters:: mu (float) – The renormalization scale in GeV.
Return type:: float

m_c_pole((Model)self) → float

Returns the charm-quark pole mass in GeV.

Return type:: float

m_s_msbar((Model)self, (float)mu) → float

Returns the strange-quark \(\overline{\text{MS}}\) mass \(\overline{m}_s(\mu)\) in GeV.

Parameters:: mu (float) – The renormalization scale in GeV.
Return type:: float

m_t_msbar((Model)self, (float)mu) → float

Returns the top-quark \(\overline{\text{MS}}\) mass \(\overline{m}_t(\mu)\) in GeV.

Parameters:: mu (float) – The renormalization scale in GeV.
Return type:: float

m_t_pole((Model)self) → float

Returns the top-quark pole mass in GeV.

Return type:: float

m_ud_msbar((Model)self, (float)mu) → float

Returns the averaged up-/down-quark \(\overline{\text{MS}}\) mass \(\overline{m}_{ud}(\mu)\) in GeV.

Parameters:: mu (float) – The renormalization scale in GeV.
Return type:: float

static make((str)name, (_Parameters)parameters, (Options)options) → Model

Makes a new Model object.

Parameters:

name (str) – The name of the model, e.g. SM or WET.
parameters (eos.Parameters) – The set of parameters to which the model is bound.
options (eos.Options) – The set of options relevant to the model.

Returns:

The new model object.

Return type:

eos.Model

wilson_coefficients_b_to_s((Model)self, (float)mu, (object)lepton_flavor, (bool)cp_conjugate) → BToSWilsonCoefficients

Returns the Wilson coefficients of the \(b \to s\) effective Hamiltonian.

Parameters:

mu (float) – The renormalization scale in GeV.
lepton_flavor (str) – The lepton flavor, one of e, mu, or tau.
cp_conjugate (bool) – Whether to return the CP-conjugated Wilson coefficients. Defaults to False.

class eos.Observable

Represents an observable or pseudo observable known to EOS.

New observable objects are created using the make static method. See also the complete list of observables.

evaluate((Observable)self) → float

Evaluates the observable for the present values of its bound set of parameters and set of kinematic variables.

Returns:: The value of the observable.
Return type:: float

kinematics((Observable)self) → Kinematics

Returns the set of kinematic variables bound to this observable.

Return type:: eos.Kinematics

static make((QualifiedName)name, (_Parameters)parameters, (Kinematics)kinematics, (Options)options) → Observable

Makes a new Observable object.

Parameters:

name (eos.QualifiedName) –
The name of the observable. See the complete list of observables.
parameters (eos.Parameters) – The set of parameters to which this observable is bound.
kinematics (eos.Kinematics) – The set of kinematic variables to which this observable is bound.
options (eos.Options) – The set of options relevant to this observable.

Returns:

The new observable object.

Return type:

eos.Observable

name((Observable)self) → QualifiedName

Returns the name of the observable.

Return type:: eos.QualifiedName

options((Observable)self) → Options

Returns the set of options used when creating the observable.

Return type:: eos.Options

parameters((Observable)self) → eos.Parameters

Returns the set of parameters bound to this observable.

Return type:: eos.Parameters

class eos.ObservableEntry

Describes a single observable known to EOS.

An observable entry records an observable’s name, its LaTeX representation, its unit, and the kinematic variables and options it accepts. Entries are obtained by iterating or indexing eos.Observables.

kinematic_variables((ObservableEntry)arg1) → object: Returns an iterator over the names of the kinematic variables accepted by the observable.

latex((ObservableEntry)self) → str

Returns the LaTeX representation of the observable.

Return type:: str

name((ObservableEntry)self) → QualifiedName

Returns the name of the observable.

Return type:: eos.QualifiedName

options((ObservableEntry)arg1) → object: Returns an iterator over the options accepted by the observable.

unit((ObservableEntry)self) → Unit

Returns the unit of the observable.

Return type:: eos.Unit

class eos.ObservableId

Represents an opaque handle to an observable within an ObservableCache.

Users cannot directly create new objects of this class. New handles are obtained from ObservableCache.add.

value((ObservableId)self) → int

Returns the underlying numeric value of the handle.

Return type:: int

class eos.Observables(prefix=None, name=None, suffix=None, showall=False)

Represents the complete list of observables known to EOS.

Objects of this class are visualized as tables in Jupyter notebooks for easy overview. Filters can be applied through keyword arguments to the initialization.

Parameters:

prefix (str) – Only show observables whose qualified names contain the provided prefix in their prefix part.
name (str) – Only show observables whose qualified names contain the provided name in their name part.
suffix (str) – Only show observables whose qualified names contain the provided suffix in their suffix part.

See also the complete list of observables in this documentation.

insert((_Observables)self, (QualifiedName)name, (str)latex, (Unit)unit, (Options)options, (str)expression) → None

Insert a new observable to EOS by parsing the input string.

Parameters:

name (eos.QualifiedName) – The name of the new observable.
latex (str) – The latex representation of the new observable.
unit (eos.Unit) – The unit of the new observable.
options (eos.Options) – The set of options relevant to this new observable. These options apply to all the observables in the expression.
expression (str) – The expression to be parsed.

sections((_Observables)arg1) → object: Returns an iterator over the sections into which the known observables are grouped.

class eos.Options

Represents the set of options provided to an observable.

Options are pairs of (key, value) pairs. The list of valid keys and their respective valid options are specific to each observable. The initialization accepts keyword arguments, e.g.:

o = eos.Options(model='WET')                   # default keyword arguments
o = eos.Options({'form-factors': 'BSZ2015'})   # use a dictionary if option keys are not
                                               # valid python identifiers

declare((Options)self, (qnpOptionKey)key, (qnpOptionValue)value) → None

Declares an option as a (key, value) pair.

Parameters:

key (str) – The name of the option.
value (str) – The value assigned to the option.

class eos.Parameter

Represents a single real-valued scalar parameter in EOS.

Users cannot directly create new objects of this class. However, new named sets of parameters can be created, via the eos.Parameters class, from which the parameter of interest can be extracted, inspected, and altered.

central((Parameter)self) → float

Returns the default central value of the parameter.

Return type:: float

evaluate((Parameter)self) → float

Return the current value of a parameter.

Return type:: float

evaluate_generator((Parameter)self) → float

Return the current generator value of a parameter.

Return type:: float

latex((Parameter)self) → str

Returns the LaTeX representation of the parameter.

Return type:: str

max((Parameter)self) → float

Returns the maximum value that the parameter is allowed to take.

Return type:: float

min((Parameter)self) → float

Returns the minimum value that the parameter is allowed to take.

Return type:: float

name((Parameter)self) → str

Returns the name of the parameter.

Return type:: str

set((Parameter)self, (float)value) → None

Set the value of a parameter.

Parameters:: value (float) – The value to set the parameter to.

set_generator((Parameter)self, (float)value) → None

Set the generator value of a parameter.

Parameters:: value (float) – The value to set the parameter’s generator to.

set_max((Parameter)self, (float)value) → None

Set the maximum value that the parameter is allowed to take.

Parameters:: value (float) – The maximum value to set.

set_min((Parameter)self, (float)value) → None

Set the minimum value that the parameter is allowed to take.

Parameters:: value (float) – The minimum value to set.

unit((Parameter)self) → Unit

Returns the unit of the parameter.

Return type:: eos.Unit

class eos.Parameters(*args, **kwargs)

Represents the set of parameters known to EOS.

Objects of this class are visualized as tables in Jupyter notebooks for easy overview. Filters can be applied through keyword arguments to the initialization. An independent instance of the default parameters is obtained by each call to the constructor.

Parameters:

prefix (str) – Only show parameters whose qualified names contain the provided prefix in their prefix part.
name (str) – Only show parameters whose qualified names contain the provided name in their name part.
suffix (str) – Only show parameters whose qualified names contain the provided suffix in their suffix part.

static Defaults() → eos.Parameters

Returns an independent instance of the default set of parameters known to EOS.

Return type:: eos.Parameters

static FromWCxf(w)

Imports Wilson coefficients into an eos.Parameters object from a wilson.Wilson object.

Parameters:: w (wilson.Wilson) – WET Wilson coefficients in the EOS basis.

by_id((_Parameters)self, (int)id) → Parameter

Returns the parameter with the given internal id.

Parameters:: id (int) – The internal id of the parameter.
Return type:: eos.Parameter

static declare((QualifiedName)name, (str)latex, (Unit)unit, (float)value, (float)min, (float)max) → int

Declare a new parameter as part of the default parameter set.

Parameters:

name (eos.QualifiedName) – The name of the parameter to declare.
latex (str) – The LaTeX representation for the parameter.
unit (eos.Unit) – The unit in which the parameter is expressed.
value (float) – The initial value for the parameter.
min (float) – The minimum value that the parameter can attain.
max (float) – The maximum value that the parameter can attain.

declare_and_insert((_Parameters)self, (QualifiedName)name, (str)latex, (Unit)unit, (float)value, (float)min, (float)max) → Parameter

Declare a new parameter as part of the default parameter set and insert it into this parameter set.

Parameters:

name (eos.QualifiedName) – The name of the parameter to declare.
latex (str) – The LaTeX representation for the parameter.
unit (eos.Unit) – The unit in which the parameter is expressed.
value (float) – The initial value for the parameter.
min (float) – The minimum value that the parameter can attain.
max (float) – The maximum value that the parameter can attain.

Returns:

The newly inserted parameter.

Return type:

eos.Parameter

dump(file, **kwargs)

Dumps an eos.Parameters object to a YAML file.

Parameters:

file (str) – Name of the file to which the parameters shall be written.
names (collections.abc.Collection of str, optional) – Names of the parameters that shall be converted.

property generation

The current generation of this set of parameters.

The generation changes whenever any of the parameters is written to. It is invariant under reading any of the parameters.

The value is an opaque _ParametersGeneration object. Two values compare equal if and only if no parameter has been written to in between.

has((_Parameters)self, (QualifiedName)name) → bool

Returns whether a parameter of the given name is part of this set.

Parameters:: name (eos.QualifiedName) – The name of the parameter to look up.
Return type:: bool

override_from_file((_Parameters)self, (str)file) → None

Overrides parameter values from a YAML file.

Parameters:: file (str) – The path to the YAML file with the parameter values.

static redirect((QualifiedName)name, (int)id) → None

Redirect a parameter name to a different parameter id in the default set of parameters.

The internal mapping of the parameter name will be redirected to the new id. If the the parameter’s previous id is not already aliased, it will become inaccessible. This is useful for example to alias a parameter name to a different parameter object.

Parameters:

name (eos.QualifiedName) – The name of the parameter to be redirected.
id (int) – The id of the parameter to which the name shall be redirected.

sections((_Parameters)arg1) → object: Returns an iterator over the sections into which the known parameters are grouped.

set((_Parameters)self, (QualifiedName)name, (float)value) → None

Set the value of a parameter.

Parameters:

name (str) – The name of the parameter to set.
value (float) – The value to set the parameter to.

to_yaml(names=None)

Converts an eos.Parameters object to a YAML representation.

Parameters:: names (collections.abc.Collection of str, optional) – Names of the parameters that shall be converted.

class eos.QualifiedName

Represent a qualified (i.e. complete and syntactically correct) name.

EOS uses qualified names when naming any observable or constraint. The composition is approximately:

PREFIX::NAME@SUFFIX;OPTIONS

full((QualifiedName)self) → str: Returns the full name, i.e., the concatenation of all parts.

name_part((QualifiedName)self) → qnpName: Returns the name part of the name, i.e., the part following the ‘::’ and preceding any optional ‘@’.

options_part((QualifiedName)self) → Options: Returns the optional options part of the name, i.e., the part following the optional ‘;’.

prefix_part((QualifiedName)self) → qnpPrefix: Returns the prefix part of the name, i.e., the part preceding the ‘::’.

suffix_part((QualifiedName)self) → qnpSuffix: Returns the optional suffix part of the name, i.e., the part following the optional ‘@’.

class eos.qnpName

Represents the name part of a QualifiedName, i.e. the part following the ‘::’ and preceding any optional ‘@’.

Objects of this class are returned by QualifiedName.name_part and can be created from a str.

class eos.qnpOptionKey

Represents the key of a single option within the options part of a QualifiedName, i.e. the part of an option preceding the ‘=’.

Objects of this class occur when iterating QualifiedName.options_part and can be created from a str.

class eos.qnpOptionValue

Represents the value of a single option within the options part of a QualifiedName, i.e. the part of an option following the ‘=’.

Objects of this class occur when iterating QualifiedName.options_part and can be created from a str.

class eos.qnpPrefix

Represents the prefix part of a QualifiedName, i.e. the part preceding the ‘::’.

Objects of this class are returned by QualifiedName.prefix_part and can be created from a str.

class eos.qnpSuffix

Represents the suffix part of a QualifiedName, i.e. the part following the optional ‘@’.

Objects of this class are returned by QualifiedName.suffix_part and can be created from a str.

class eos.Reference

Represents a single bibliographic reference known to EOS.

A reference records the bibliographic details (authors, title, e-print, INSPIRE identifier, and URL) of a publication underlying part of EOS, be it an experimental constraint or a theoretical work such as the implementation of an observable, a form factor parametrization, or a theory prediction. References are obtained by iterating or indexing eos.References.

authors((Reference)self) → str

Returns the authors of the reference.

Return type:: str

eprint_archive((Reference)self) → str

Returns the e-print archive of the reference, e.g. arXiv.

Return type:: str

eprint_id((Reference)self) → str

Returns the e-print identifier of the reference, e.g. the arXiv number.

Return type:: str

inspire_id((Reference)self) → str: Returns the INSPIRE identifier of the reference. :rtype: str

name((Reference)self) → ReferenceName: Returns the name (handle) of the reference.

title((Reference)self) → str

Returns the title of the reference.

Return type:: str

url((Reference)self) → str

Returns the URL of the reference.

Return type:: str

class eos.ReferenceName

Represents the name of a reference in the EOS bibliography.

A reference name is composed of a name part, a year part, and an index part, as in BSZ:2015A. Objects of this class can be created from a str and are used to look up a Reference in References.

index_part((ReferenceName)self) → rnpIndex: Returns the index part of the reference name, i.e., the letters following the year part.

name_part((ReferenceName)self) → rnpName: Returns the name part of the reference name, i.e., the part preceding the ‘:’.

year_part((ReferenceName)self) → rnpYear: Returns the year part of the reference name, i.e., the four digits following the ‘:’.

class eos.rnpIndex

Represents the index part of a ReferenceName, i.e. the letters following the year part.

Objects of this class are returned by ReferenceName.index_part and can be created from a str.

class eos.rnpName

Represents the name part of a ReferenceName, i.e. the part preceding the ‘:’.

Objects of this class are returned by ReferenceName.name_part and can be created from a str.

class eos.rnpYear

Represents the year part of a ReferenceName, i.e. the four digits following the ‘:’.

Objects of this class are returned by ReferenceName.year_part and can be created from a str.

class eos.References(year=None, index=None)

Represents the complete list of references known to EOS.

Objects of this class are visualized as tables in Jupyter notebooks for easy overview. Filters can be applied through keyword arguments to the initialization.

Parameters:

year (str) – Only show references whose names contain the provided year in their year part.
index (str) – Only show references whose names contain the provided index in their index part.

See also the complete list of references in this documentation.

class eos.SignalPDF

evaluate((_SignalPDF)self) → float

Evaluates the (unnormalized) PDF for the present values of the sets of parameters and kinematic variables that it is bound to.

Returns:: The value of the PDF.
Return type:: float

kinematics((_SignalPDF)self) → Kinematics

Returns the set of kinematic variables bound to this PDF.

Return type:: eos.Kinematics

log_pdf(x)

Adapter for use with external optimization software (e.g. pypmc) to aid when sampling from the log(PDF).

Parameters:: x (collections.abc.Iterable of float) – Phase space point, with the elements corresponding to the sorted list of variables in lexicographical order; inspect self.variables.

static make(name, parameters, kinematics, options)

Makes a new SignalPDF object.

Parameters:

name (eos.QualifiedName) – The name of the probability density function (PDF). See the complete list of PDFs.
parameters (eos.Parameters) – The set of parameters to which this PDF is bound.
kinematics (eos.Kinematics) – The set of kinematic variables to which this PDF is bound.
options (eos.Options) – The set of options relevant to this PDF.

Returns:

The new PDF object.

Return type:

eos.SignalPDF

name((_SignalPDF)self) → QualifiedName

Returns the name of the PDF.

Return type:: eos.QualifiedName

normalization((_SignalPDF)self) → float

Evaluates the normalization of the PDF.

To speed up sampling from the PDF, the evaluate returns values of an unnormalized function proportional to the actual PDF. To ensure that the integral over the PDF is normalized to 1, the values returned by evaluate need to be divided by the return value of this method.

Return type:: float

options((_SignalPDF)self) → Options

Returns the set of options used when creating the PDF.

Return type:: eos.Options

parameters((_SignalPDF)self) → eos.Parameters

Returns the set of parameters bound to this PDF.

Return type:: eos.Parameters

sample_mcmc(N, stride, pre_N, preruns, cov_scale=0.1, start_point=None, rng=None)

Return samples of the kinematic variables and the log(PDF).

Obtains random samples of the log(PDF) using an adaptive Markov Chain Monte Carlo with PyPMC. A prerun with adaptations is carried out first and its samples are discarded.

Parameters:

N – Number of samples that shall be returned
stride – Stride, i.e., the number by which the actual amount of samples shall be thinned to return N samples.
pre_N – Number of samples in each prerun.
preruns – Number of preruns.
cov_scale – Scale factor for the initial guess of the covariance matrix.
start_point (collections.abc.Sequence, optional) – Optional starting point for the chain
rng – Optional random number generator (must be compatible with the requirements of pypmc.sampler.markov_chain.MarkovChain)

Returns:

A tuple of the kinematic variables as array of size N and the log(PDF) as array of size N.

Note

This method requires the PyPMC python module, which can be installed from PyPI.

class eos.SignalPDFEntry

Describes a single signal PDF known to EOS.

A signal-PDF entry records the PDF’s name and a human-readable description. Entries are obtained by iterating or indexing eos.SignalPDFs.

denominator_kinematic_variables((SignalPDFEntry)arg1) → object: Returns an iterator over the names of the kinematic variables in the PDF’s denominator.

description((SignalPDFEntry)self) → str

Returns the human-readable description of the signal PDF.

Return type:: str

name((SignalPDFEntry)self) → QualifiedName

Returns the name of the signal PDF.

Return type:: eos.QualifiedName

numerator_kinematic_variables((SignalPDFEntry)arg1) → object: Returns an iterator over the names of the kinematic variables in the PDF’s numerator.

class eos.SignalPDFs(prefix=None, name=None, suffix=None, showall=False)

Represents the complete list of probability density functions (PDFs) known to EOS.

Objects of this class are visualized as tables in Jupyter notebooks for easy overview. Filters can be applied through keyword arguments to the initialization.

Parameters:

prefix (str) – Only show observables whose qualified names contain the provided prefix in their prefix part.
name (str) – Only show observables whose qualified names contain the provided name in their name part.
suffix (str) – Only show observables whose qualified names contain the provided suffix in their suffix part.

See also the complete list of signal PDFs in this documentation.

insert((_SignalPDFs)self, (QualifiedName)name, (str)description, (Options)options, (QualifiedName)numerator, (object)numerator_kinematic_variables, (QualifiedName)normalization, (object)normalization_kinematic_variables) → None

Insert a new signal PDF to EOS, built at run time from two existing observables.

Parameters:

name (eos.QualifiedName) – The name of the new signal PDF.
description (str) – A human-readable description of the new signal PDF.
options (eos.Options) – The set of options relevant to this new signal PDF. These options apply to both backing observables.
numerator (eos.QualifiedName) – The name of the observable that provides the unnormalized PDF.
numerator_kinematic_variables (list of str) – The kinematic variables of the unnormalized PDF; these are the PDF’s sampling variables.
normalization (eos.QualifiedName) – The name of the observable that provides the normalization.
normalization_kinematic_variables (list of str) – The kinematic variables of the normalization; for each sampling variable v this should contain the bounds v_min and v_max.

sections((_SignalPDFs)arg1) → object: Returns an iterator over the sections into which the known signal PDFs are grouped.

class eos.Unit

Represents the unit of the observables.

Thirteen possible entries are currently implemented in EOS:

Undefined
Unity
GeV
GeV2
GeV3
InverseGeV
InverseGeV2
InverseGeV4
Second
InverseSecond
InversePicoSecond
GeVSecond
Femtometer2

static Femtometer2() → Unit

Returns the unit \(\textrm{fm}^2\).

Return type:: eos.Unit

static GeV() → Unit

Returns the unit \(\textrm{GeV}\).

Return type:: eos.Unit

static GeV2() → Unit

Returns the unit \(\textrm{GeV}^2\).

Return type:: eos.Unit

static GeV3() → Unit

Returns the unit \(\textrm{GeV}^3\).

Return type:: eos.Unit

static GeVSecond() → Unit

Returns the unit \(\textrm{GeV}\,\textrm{s}\).

Return type:: eos.Unit

static InverseGeV() → Unit

Returns the unit \(\textrm{GeV}^{-1}\).

Return type:: eos.Unit

static InverseGeV2() → Unit

Returns the unit \(\textrm{GeV}^{-2}\).

Return type:: eos.Unit

static InverseGeV4() → Unit

Returns the unit \(\textrm{GeV}^{-4}\).

Return type:: eos.Unit

static InversePicoSecond() → Unit

Returns the unit \(\textrm{ps}^{-1}\).

Return type:: eos.Unit

static InverseSecond() → Unit

Returns the unit \(\textrm{s}^{-1}\).

Return type:: eos.Unit

static Second() → Unit

Returns the unit \(\textrm{s}\).

Return type:: eos.Unit

static Undefined() → Unit

Returns the undefined unit, which is used wherever no unit has been assigned. It is printed as undefined.

Return type:: eos.Unit

static Unity() → Unit

Returns the unit of a dimensionless quantity, which is printed as 1.

Return type:: eos.Unit

latex((Unit)self) → str: Returns the LaTeX representation of the unit.

Common Classes

EOS provides common classes for use in statistical analyses via the main eos module.

class eos.Analysis(priors, likelihood, external_likelihood=None, global_options=None, manual_constraints=None, fixed_parameters=None, parameters=None)

Represents a statistical analysis.

Describes a Bayesian analysis in terms of a set of parameters, a log(likelihood), and a set containing one or more log(prior)s.

Parameters:

global_options (dict, optional) – The options as (key, value) pairs that shall be forwarded to all theory predictions.
priors (collections.abc.Sequence) – The priors for this analysis as a list of prior descriptions. See below for what consitutes a valid prior description.
likelihood (collections.abc.Sequence) –
The likelihood as a list of individual constraints from the internal data base of experimental and theoretical constraints; cf. the complete list of constraints.
external_likelihood (collections.abc.Sequence of eos.LogLikelihoodBlock.) – The external likelihood blocks as a list or iterable of objects returned by eos.LogLikelihoodBlock.External().
manual_constraints (dict, optional) – Additional manually-specified constraints that shall be added to the log(likelihood).
fixed_parameters (dict, optional) – Values of parameters that are set when the analysis is defined.
parameters (eos.Parameters or None, optional) – The optional set of parameters that shall be used for this analysis. Defaults to None which means that a new instance of eos.Parameters is created.

Each prior description is a dictionary with the following mandatory elements:

type (str) – The type specification of the prior. Must be one of uniform, flat, or gaussian.
parameter (str) – The name of the parameter for which the prior shall apply.
min (float) – The lower boundary of the prior’s support.
max (float) – The upper boundary of the prior’s support.

A uniform or flat prior does not require any further description. A gaussian prior requires in addition providing the following two elements:

central (float) – The median value of the parameter.
sigma (float, or list, tuple of float) – The width of the 68% probability interval. If a list or tuple of two numbers is provided, the prior will by a asymmetric but continuous. The two values are then taken to be the distance to the lower and upper end of the 68% probability interval.

clone()

Return an independent copy of this analysis.

The clone is constructed from the same arguments as the original, so it has its own parameter set and can be modified without affecting this instance.

Returns:: A new analysis equivalent to this one.
Return type:: eos.Analysis

goodness_of_fit()

Summarize the quality of the fit at the current parameter point.

Returns:: A goodness-of-fit summary (e.g. test statistic, degrees of freedom, and p-value) evaluated at the analysis’ current parameter values.
Return type:: eos.GoodnessOfFit

log_likelihood(p, *args)

Adapter for use with external sampling software (e.g. dynesty) to aid when sampling from the log(likelihood).

Parameters:

p (collections.abc.Iterable) – Parameter point, with the elements in the same order as in eos.Analysis.varied_parameters.
args (optional) – Dummy parameter (ignored)

log_pdf(u, *args)

Adapter for use with external optimization software (e.g. pypmc) to aid when optimizing the log(posterior).

Parameters:

u (collections.abc.Iterable) – Parameter point in u space, with the elements in the same order as in eos.Analysis.varied_parameters.
args (optional) – Dummy parameter (ignored)

negative_log_pdf(u, *args)

Adapter for use with external optimization software (e.g. scipy.optimize.minimize) to aid when optimizing the log(posterior).

Parameters:

u (collections.abc.Iterable) – Parameter point in u space, with the elements in the same order as in eos.Analysis.varied_parameters.
args (optional) – Dummy parameter (ignored)

optimize(start_point=None, rng=None, **kwargs)

Optimize the log(posterior) and returns a best-fit-point summary. Optimization is performed using the scipy SLSQP method by default since the varied parameters are usually bounded. However, other bounded algorithms (such as Nelder-Mead, L-BFGS-B, TNC, SLSQP, Powell or trust-constr) sometimes perform better. The most significant performance improvement is usually achieved by selecting an appropriate initial point, for example, one taken from importance samples.

Parameters:

start_point (collections.abc.Iterable, optional) – Parameter point from which to start the optimization, with the elements in the same order as in eos.Analysis.varied_parameters. If set to “random”, optimization starts at the random point in the space of the priors. If not specified, optimization starts at the current parameter point.
rng – Optional random number generator
**kwargs – Are passed to scipy.optimize.minimize

parameters: The set of parameters used for this analysis.

reset_parameters()

Reset this analysis’ parameters to their EOS default values.

Each parameter of the analysis is set back to the default value of the corresponding EOS parameter, discarding any modifications made since the analysis was created.

sample(N=1000, stride=5, pre_N=150, preruns=3, cov_scale=0.1, observables=None, start_point=None, rng=None, return_uspace=False)

Return samples of the parameters, log(weights), and optionally posterior-predictive samples for a sequence of observables.

Obtains random samples of the log(posterior) using an adaptive Markov Chain Monte Carlo with PyPMC. A prerun with adaptations is carried out first and its samples are discarded.

Parameters:

N – Number of samples that shall be returned
stride – Stride, i.e., the number by which the actual amount of samples shall be thinned to return N samples.
pre_N – Number of samples in each prerun.
preruns – Number of preruns.
cov_scale – Scale factor for the initial guess of the covariance matrix.
observables (collections.abc.Sequence, optional) – Observables for which posterior-predictive samples shall be obtained.
start_point (collections.abc.Sequence, optional) – Optional starting point for the chain
rng – Optional random number generator (must be compatible with the requirements of pypmc.sampler.markov_chain.MarkovChain)

Returns:

A tuple of the parameters as array of size N, the logarithmic weights as array of size N, and optionally the posterior-predictive samples of the observables as array of size N x len(observables).

Note

This method requiries the PyPMC python module, which can be installed from PyPI.

sample_nested(bound='multi', nlive=250, dlogz=1.0, maxiter=None, miniter=0, min_ess=0, print_progress=True, print_function=None, seed=10, sample='auto')

Return samples of the parameters.

Obtains random samples of log(likelihood) using dynamic nested sampling with dynesty.

Parameters:

bound (str, optional) – The option for bounding the target distribution. For valid values, see the dynesty documentation. Defaults to ‘multi’.
nlive (int, optional) – The number of live points.
dlogz (float, optional) – The relative tolerance for the remaining evidence. Defaults to 1.0.
maxiter (int, optional) – The maximum number of iterations. Iterations may stop earlier if the termination condition is reached.
miniter (int, optional) – The minimum number of iterations. Defaults to 0. Samples will be added until miniter is reached, even if the termination condition is reached earlier.
min_ess (int, optional) – The minimum effective sample size (ESS). Defaults to 0. Samples will be added until the estimated ESS reaches min_ess, even if the termination condition is reached earlier. If 0, dynesty’s default ESS target is used.
print_progress (bool, optional) – Whether to print progress messages during sampling. Defaults to True.
print_function (collections.abc.Callable, optional) – The function used to print progress messages. Defaults to using a dynesty-based function.
seed (None or int or collections.abc.Sequence of int or numpy.random.SeedSequence, optional) – The seed used to initialize the Mersenne Twister pseudo-random number generator.
sample (str, optional) – The method used for sampling within the likelihood constraints. For valid values, see dynesty documentation. Defaults to ‘auto’.

Note

This method requires the dynesty python module, which can be installed from PyPI.

sample_pmc(log_proposal, step_N=1000, steps=10, final_N=5000, rng=None, return_final_only=True, final_perplexity_threshold=1.0, weight_threshold=1e-10, pmc_iterations=1, pmc_rel_tol=1e-10, pmc_abs_tol=1e-05, pmc_lookback=1)

Return samples of the parameters and log(weights), and a mixture density adapted to the posterior.

Obtains random samples of the log(posterior) using adaptive importance sampling following the Population Monte Carlo approach with PyPMC.

Parameters:

log_proposal (pypmc.density.mixture.MixtureDensity) – Initial gaussian mixture density that shall be adapted to the posterior density.
step_N (int) – Number of samples that shall be drawn in each adaptation step.
steps (int) – Number of adaptation steps.
final_N (int) – Number of samples that shall be drawn after all adaptation steps.
rng – Optional random number generator (must be compatible with the requirements of pypmc.sampler.importance_sampler.ImportanceSampler)
return_final_only – If set to True, only returns the samples and weights of the final sampling step, after all adaptations have finished.
final_perplexity_threshold – Adaptations are stopped if the perplexity of the last adaptation step is above this threshold value.
weight_threshold – Mixture components with a weight smaller than this threshold are pruned.
pmc_iterations – (advanced) Maximum number of update of the PMC, changing this value may make the update unstable.
pmc_rel_tol – (advanced) Relative tolerance of the PMC. If two consecutive values of the current density log-likelihood are relatively smaller than this value, the convergence is declared.
pmc_abs_tol – (advanced) Absolute tolerance of the PMC. If two consecutive values of the current density log-likelihood are smaller than this value, the convergence is declared.
pmc_lookback – (advanced) Use reweighted samples from the previous update steps when adjusting the mixture density. The parameter determines the number of update steps to “look back”. The default value of 1 disables this feature, a value of 0 means that all previous steps are used.

Returns:

A tuple of the parameters as array of length N = step_N * steps + final_N, the (linear) weights as array of length N, the posterior values as array of length N, and the final proposal function as pypmc.density.mixture.MixtureDensity.

This method should be called after obtaining approximate samples of the log(posterior) by other means, e.g., by using eos.Analysis.sample(). A possible (incomplete) example could look as follows:

from pypmc.mix_adapt.r_value import make_r_gaussmix
chains = []
for i in range(10):
    # run Markov Chains for your problem
    chain, _ = analysis.sample(...)
    chains.append(chain)

# please consult the pypmc documentation for details on the call below
proposal_density = make_r_gaussmix(chains, K_g=3, critical_r=1.1)

# adapt the proposal to the posterior and obtain high-quality samples
analysis.sample_pmc(proposal_density, ...)

Note

This method requires the PyPMC python module, which can be installed from PyPI.

sample_prior(N=1000, rng=None)

Return prior samples of the parameters.

Obtains random samples of the parameters based on their prior distributions. The code uses inverse transform sampling.

Parameters:

N (int) – Number of samples that shall be returned
rng – Optional random number generator

Returns:

An iterable of the parameter samples of size N.

varied_parameters: list: The parameters varied by this analysis, as a list of eos.Parameter objects.

class eos.AnalysisFile(analysis_file)

Represents a collection of statistical analyses and their building blocks.

Parameters:: analysis_file (str) – The path to the file to be parsed.

analysis(_posterior, base_directory='./')

Create an eos.Analysis object for the named posterior.

Parameters:: base_directory (str) – The base directory against which declared constraints’ relative filenames (see the ‘constraints’ top-level section) are resolved. Defaults to the current working directory.

dump(): Dumps the contents of the analysis file in YAML format.

property likelihoods: Returns a list of all likelihoods recorded in the analysis file.

property masks: Returns a list of all masks recorded in the analysis file.

observable(_posterior, observable_name, analysis_parameters): Creates an eos.Observable for the named posterior with the given parameter set.

observables(_posterior, _prediction, parameters): Creates a list of eos.Observable objects for the named set of posterior and predictions.

property posteriors: Returns a list of all posteriors recorded in the analysis file.

property predictions: Returns a list of all predictions recorded in the analysis file.

property priors: Returns a list of all priors recorded in the analysis file.

validate(deep: bool = True, base_directory: str = './')

Validates the analysis file semantically and, by default, deeply.

The deep phase instantiates every posterior and every prediction set, which catches errors that the semantic phase cannot see: invalid options, malformed manual-constraint bodies, inconsistent prior ranges, and unreadable pyhf workspaces. It is enabled by default.

Parameters:

deep (bool) – If True, additionally instantiate all posteriors and prediction sets. Defaults to True.
base_directory (str) – The base directory against which declared constraints’ relative filenames are resolved during the deep phase. Defaults to the current working directory.

Returns:

The diagnostics found, most-structural first.

Return type:

list[eos.diagnostic.Diagnostic]

class eos.BestFitPoint(analysis, point)

Represents the best-fit point of a Bayesian analysis undertaken with the Analysis class.

Typically obtained as the return value of Analysis.optimize(). It bundles the analysis with the parameter point that maximizes its log-posterior and renders as a parameter/value table in IPython.

Parameters:

analysis (eos.Analysis) – The analysis whose best-fit point is represented.
point (collections.abc.Iterable of float) – The values of the varied parameters at the best-fit point, in the same order as eos.Analysis.varied_parameters.

Variables:

analysis – The analysis whose best-fit point is represented.
point – The values of the varied parameters at the best-fit point.

class eos.GoodnessOfFit

Represents the goodness of fit characteristics of the log(posterior).

total_chi_square((GoodnessOfFit)self) → float

Returns the total \(\chi^2\) value of the log(likelihood). Only (multivariate) gaussian likelihoods are considered for this result.

Return type:: float

total_degrees_of_freedom((GoodnessOfFit)self) → int

Returns the total number of degrees of freedom in the log(posterior).

Return type:: int

class eos.ObservableCache

Provides a cache for the efficient evaluation of observables.

add((ObservableCache)self, (Observable)observable) → ObservableId

Add an existing observable to the cache.

Parameters:: observable (eos.Observable) – The observable to add to the cache.
Returns:: An internal handle to the cached observable. The observable’s value can be retrieved using cache[handle].
Return type:: eos.ObservableId

parameters((ObservableCache)self) → eos.Parameters

Retrieve the set of parameters bound to this cache.

Return type:: eos.Parameters

update((ObservableCache)self) → None: Update the cache for the current parameter point.

class eos.PyhfLogLikelihood(cache, workspace, parameter_map=None)

Wraps a HistFactory likelihood, specified as a pyhf workspace, for use within EOS.

On construction, the pyhf model’s modifiers (its parameters) are mapped onto EOS observables or parameters: each pyhf parameter is associated with the EOS observable or parameter named by parameter_map, defaulting to a parameter pyhf::<name> that is declared if it does not yet exist. The corresponding observables are registered with the supplied observable cache, so that evaluate() can compute the main term of the pyhf log-likelihood from the current EOS parameter values. The constraint terms of the pyhf likelihood are not evaluated here; they are instead exposed as EOS priors via priors().

Using this class requires the optional pyhf module.

Parameters:

cache (eos.ObservableCache) – The EOS observable cache to which the observables backing the pyhf parameters are added.
workspace (pyhf.workspace.Workspace | str) – A pyhf workspace, or the path to a JSON file specifying one.
parameter_map (dict | None) – An optional mapping from pyhf parameter names to EOS observables or parameters. Each value is either the qualified name of an EOS observable/parameter, or a dictionary with a name key and optional kinematics and options keys. Parameters not listed default to an EOS parameter named pyhf::<name>.

Raises:

RuntimeError – If the pyhf module is not installed.
ValueError – If workspace is neither a pyhf workspace nor a path to a valid JSON file, or if a parameter_map value is neither a string nor a dictionary.

evaluate()

Evaluate the main term of the pyhf log-likelihood at the current parameter values.

The pyhf parameters are read from their associated EOS observables/parameters, and the main (non-constraint) term of the HistFactory log-likelihood is returned. Constraint terms are handled separately within EOS via the priors returned by priors().

Returns:: The value of the main log-likelihood term.
Return type:: float

static factory(cache, workspace, parameter_map=None)

Construct a PyhfLogLikelihood.

Convenience factory with the same signature as the constructor; see the class documentation for a description of the arguments.

Returns:: The constructed likelihood.
Return type:: PyhfLogLikelihood

priors()

Return the EOS prior descriptions corresponding to the pyhf constraint terms.

Each modifier (parameter) of the pyhf model is translated into an EOS prior description: unconstrained parameters yield a uniform prior over their suggested bounds, while parameters with a normal or Poisson constraint yield Gaussian or Poisson priors, respectively. Parameters mapped to an EOS observable (a dictionary entry in parameter_map) are skipped, since they are not free parameters.

Returns:: A list of prior descriptions, each a dictionary with a parameter name, a type, and the type-specific keys (e.g. min/max, central/sigma, or k).
Return type:: list[dict]

Common Tasks

In addition to the basic classes, EOS provides functions to carry out often-repeated tasks, such as finding the mode of a posterior, sampling from a posterior, and similar. Tasks require a description of the statistical analysis (see eos.Analysis) by means of an analysis file. For a documentation of its format, see eos.AnalysisFile.

Tasks store their results in a hierarchy for directories below a user-provided base directory. This ensures that tasks can readily use results produced by another task.

eos.create_constraint(analysis_file: str, posterior: str, constraint_name: str, base_directory: str = './', source: str = 'samples', parameters: list = None, tests: list = None, goodness_of_fit_threshold: float = 0.03, strict: bool = True)

Creates a MultivariateGaussian(Covariance) constraint from previously computed samples of a named posterior.

The fit is the closed-form weighted maximum-likelihood estimate: the weighted sample mean and weighted sample covariance of the selected columns. One or more named goodness-of-fit tests are then run on the fit; see tests and strict below for how a failing test is handled.

The input files are expected in EOS_BASE_DIRECTORY/data/POSTERIOR/SOURCE. The output file will be stored in EOS_BASE_DIRECTORY/constraints/CONSTRAINT_NAME/constraint.yaml.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior PDF from which to draw the samples.
constraint_name (str) – The qualified name under which the constraint is registered; also used verbatim as the output subdirectory name.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
source (str, optional) – The name of the data file inside the posterior’s data directory to fit. Defaults to ‘samples’ (the posterior’s own importance samples). A value starting with ‘pred-’ selects the posterior-predictive importance samples of that name, previously written by the predict-observables task.
parameters (list of str, optional) – The list of column names to constrain, matched against the loaded data’s lookup table (bare parameter names for source=’samples’; composite observable identifiers for a ‘pred-’ source). If None, every column of the loaded data is used.
tests (list of str, optional) – The names of the goodness-of-fit tests that must be run before the constraint is accepted. Defaults to [‘KS-test’]. Each name must be a key of goodness_of_fit_tests; call one of those functions directly (e.g. eos.ks_test) on your own reloaded samples to diagnose why a test failed.
goodness_of_fit_threshold (float or dict[str, float], optional) – The p-value threshold below which a test counts as failed. Either a single float applied to every test in tests, or a dict mapping each test name in tests to its own threshold.
strict (bool, optional) – If True (the default), a failed test logs an error and aborts the task – no constraint file is written. If False, a failed test only logs a warning, and the constraint is written regardless.

eos.create_mask(analysis_file: str, posterior: str, mask_name: str, base_directory: str = './')

Creates a sample mask for a named posterior from a mask description in the analysis file.

The named mask’s description is a logical combination (and or or) of observables and/or other masks. Each observable contributes the subset of samples for which it evaluates positive, and nested masks are created recursively. The combined mask is stored as an eos.data.SampleMask in EOS_BASE_DIRECTORY/data/POSTERIOR/mask-MASK_NAME, and is also returned as a boolean array.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior and mask, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior whose samples are masked.
mask_name (str) – The name of the mask to create, as defined in the analysis file.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

Returns:

The combined boolean mask, with one entry per posterior sample.

Return type:

numpy.ndarray

eos.draw_figure(analysis_file: str, figure_name: str, base_directory: str = './', format: str | list[str] = 'pdf')

Draws figures from the analysis file.

The output files will be stored in EOS_BASE_DIRECTORY/figures/. If more than one format is requested, the figure is drawn once and stored once per format, since drawing the same figure repeatedly would stack its elements on top of each other.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
figure_name (str) – The name of the figure to draw.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
format (str or list of str, optional) – The file extension of the figure files. Can also be a list of file extensions.

eos.find_clusters(posterior: str, base_directory: str = './', threshold: float = 2.0, K_g: int = 1, analysis_file: str = None)

Finds clusters among posterior MCMC samples, grouped by Gelman-Rubin R value, and creates a Gaussian mixture density.

Finding clusters and creating a Gaussian mixture density is a necessary intermediate step before using the sample-pmc subcommand. The input files are expected in EOS_BASE_DIRECTORY/data/POSTERIOR/mcmc-*. All MCMC input files present will be used in the clustering. The output files will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/clusters.

Parameters:

posterior (str) – The name of the posterior.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
threshold (float, optional) – The R value threshold, which must be larger than 1.0. If two sample subsets have an R value larger than this threshold, they will be treated as two distinct clusters. Defaults to 2.0.
K_g (int, optional) – The number of mixture components per cluster, which must be at least 1. Default to 1.

eos.find_mode(analysis_file: str, posterior: str, base_directory: str = './', optimizations: int = 3, start_point: list = None, chain: int = None, importance_samples: bool = None, seed: int = None, label: str = 'default', mask_name: str = None)

Finds the mode of the named posterior using scipy SLSQP method by default.

The optimization process can be initialized either with a random point, a provided parameter point, or by extracting the point with the largest posterior from among previously obtained MCMC or importance samples. The latter possibility usually gives the better performence. The optimization can also be iterated to increase the accuracy of the result.

The output file will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/mode-LABEL.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior PDF from which to draw the samples.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
optimizations (int, optional) – The number of calls to the optimization algorithm.
start_point (numpy.ndarray, optional) – If provided, the optimization will start at this point.
chain (int, optional) – If provided, the optimization will start at the point with the largest posterior of previously computed MCMC samples. The samples are expected to be stored in the mcmc-XXXX subdirectories of the base_directory, where ‘XXXX’ is the provided int.
importance_samples (bool, optional) – If set to True, the optimization will start at the point with the largest posterior of previously computed importance samples.
seed (int, optional) – If provided, the optimization will start from a random point and the random number generator will be seeded with this value.

eos.list_figures(analysis_file: str)

Lists all figures that can be created from the analysis file.

Parameters:: analysis_file (str or eos.AnalysisFile) – The name of the analysis file, or an object of class eos.AnalysisFile.

eos.list_step_dependencies(analysis_file: str, id: str)

Lists all steps required to be completed before the given step can be executed.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that shall be inspected`.
id (str) – The id of the step to inspect.

eos.list_steps(analysis_file: str)

Lists the steps in the analysis file.

Parameters:: analysis_file (str or eos.AnalysisFile) – The name of the analysis file that shall be inspected`.

eos.mixture_product(posterior: str, posteriors: list, base_directory: str = './', analysis_file: str = None)

Compute the cartesian product of the densities listed in posteriors. Note that this product is not commutative.

The input densities are read from EOS_BASE_DIRECTORY/data/POSTERIOR_i/pmc, where POSTERIOR_i is listed in posteriors. The output density will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/product.

Parameters:

posterior (str) – The name of the posterior.
posteriors (collections.abc.Iterable of str) – The list of names of the posteriors whose mixture densities will be concatenated.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

eos.predict_observables(analysis_file: str, posterior: str, prediction: str, base_directory: str = './', begin: int = 0, end: int = None, mask_name: str = None)

Predicts a set of observables based on previously obtained importance samples.

The input files are expected in EOS_BASE_DIRECTORY/data/POSTERIOR/samples. The output files will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/pred-PREDICTION.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior.
prediction (str) – The name of the set of observables to predict.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
begin (int) – The index of the first sample to use for the predictions. Defaults to 0.
end – The index beyond the last sample to use for the predictions. Defaults to None.
mask_name (str, optional) – The label of the mask to apply to the observables. Defaults to None.

eos.report(analysis_file: str, template_file: str, base_directory: str = './', generate_pdf: bool = True)

Generates a report from an analysis file and a Jinja2 template file.

The processed file will be stored in the same directory as the template file, with the the extension ‘.jinja’ or ‘.jinja2’ stripped from the file name. If generate_pdf is set to True, the intermediate file will be converted to PDF using Pandoc and XeLaTeX. This requires a working installation of both programs.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that shall be used for the report.
template_file (str) – The name of the Jinja2 template file that shall be used for the report.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
generate_pdf (bool, optional) – The flag that enables the conversion of the intermediate file to PDF. Defaults to True.

eos.run(analysis_file: str, id: str, base_directory: str = './', dry_run: bool = False)

Runs one out of a list of predefined steps recorded in the analysis file.

Each step corresponds to a call to one or more of the common tasks, e.g.,

sample-mcmc
find-cluster
sample-pmc
predict-observables

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
id (str) – The id of the step to run.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
dry_run (bool, optional) – The flag that disables execution and instead prints the full information on the tasks that would be run to standard output. Defaults to False.

eos.sample_mcmc(analysis_file: str, posterior: str, chain: int, base_directory: str = './', pre_N: int = 150, preruns: int = 3, N: int = 1000, stride: int = 5, cov_scale: float = 0.1, start_point: list = None)

Samples from a named posterior PDF using Markov Chain Monte Carlo (MCMC) methods.

The output file will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/mcmc-CHAIN.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior PDF from which to draw the samples.
chain (int) – The index assigned to the Markov chain, which must be non-negative. This value is used to seed the RNG for a reproducible analysis.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
pre_N (int, optional) – The number of samples to be used for an adaptation in each prerun steps. These samples will be discarded.
preruns (int, optional) – The number of prerun steps, which are used to adapt the MCMC proposal to the posterior.
N (int, optional) – The number of samples to be stored in the output file. Defaults to 1000.
stride (int, optional) – The ratio of samples drawn over samples stored. For every S samples, S - 1 will be discarded. Defaults to 5.
cov_scale (float, optional) – Scale factor for the initial guess of the covariance matrix.
start_point (collections.abc.Sequence, optional) – Optional starting point for the chain

eos.sample_nested(analysis_file: str, posterior: str, base_directory: str = './', bound: str = 'multi', nlive: int = 250, dlogz: float = 1.0, maxiter: int = None, miniter: int = 0, min_ess: int = 0, seed: int = 10, sample: str = 'auto')

Samples from a likelihood associated with a named posterior using dynamic nested sampling.

The output will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/nested. In addition, an ImportanceSamples object is exported to EOS_BASE_DIRECTORY/data/POSTERIOR/samples.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
bound (str, optional) – The option for bounding the target distribution. For valid values, see the dynesty documentation. Defaults to ‘multi’.
nlive (int, optional) – The number of live points.
dlogz (float, optional) – The relative tolerance for the remaining evidence. Defaults to 1.0.
maxiter (int, optional) – The maximum number of iterations. Iterations may stop earlier if the termination condition is reached.
miniter (int, optional) – The minimum number of iterations. If not provided, the sampler will run until the termination condition is reached. Defaults to 0.
min_ess (int, optional) – The minimum effective sample size (ESS). Samples will be added until the estimated ESS reaches min_ess, even if the termination condition is reached earlier. If 0 (default), dynesty’s default ESS target is used.
seed (int, optional) – The seed used to initialize the Mersenne Twister pseudo-random number generator.
sample (str, optional) – The method used for sampling within the likelihood constraints. For valid values, see dynesty documentation. Defaults to ‘auto’.

eos.sample_pmc(analysis_file: str, posterior: str, base_directory: str = './', step_N: int = 500, steps: int = 10, final_N: int = 5000, perplexity_threshold: float = 1.0, weight_threshold: float = 1e-10, sigma_test_stat: list = None, initial_proposal: str = 'clusters', pmc_iterations: int = 1, pmc_rel_tol: float = 1e-10, pmc_abs_tol: float = 1e-05, pmc_lookback: int = 1)

Samples from a named posterior using the Population Monte Carlo (PMC) methods.

The results of the find-cluster command are expected in EOS_BASE_DIRECTORY/data/POSTERIOR/clusters. The output will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/pmc. In addition, an ImportanceSamples object is exported to EOS_BASE_DIRECTORY/data/POSTERIOR/samples.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named posterior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
step_N (int, optional) – The number of samples to be used in each adaptation step, which must be positive. These samples will be discarded. Defaults to 500.
steps (int, optional) – The number of adaptation steps, which must be positive, and which are used to adapt the PMC proposal to the posterior. Defaults to 10.
final_N (int, optional) – The number of samples to be stored in the output file, which must be positive. Defaults to 5000,
perplexity_threshold (float, optional) – The threshold for the perplexity in the last step after which further adaptation steps are to be skipped. Must be larger than 0.0 and at most 1.0. Defaults to 1.0.
weight_threshold (float, optional) – Mixture components with a weight smaller than this threshold are pruned. Must be larger than 0.0 and at most 1.0.
sigma_test_stat (list or collections.abc.Iterable) – If provided, the inverse CDF of -2*log(PDF) will be evaluated, using the provided values as the respective significance.
initial_proposal (str, optional) –
Specify where the initial proposal should be taken from:
- clusters: use the proposal obtained using find-clusters (default)
- product: use the proposal obtained from mixture_product
- pmc: continue sampling from the previous sample-pmc results.
pmc_iterations (int, optional) – Maximum number of update of the PMC, which must be positive. This is an advanced option; changing this value may make the update unstable.
pmc_rel_tol (float, optional) – Relative tolerance of the PMC, which must be positive. This is an advanced option. If two consecutive values of the current density log-likelihood are relatively smaller than this value, the convergence is declared.
pmc_abs_tol (float, optional) – Absolute tolerance of the PMC, which must be positive. This is an advanced option. If two consecutive values of the current density log-likelihood are smaller than this value, the convergence is declared.
pmc_lookback (int, optional) – Use reweighted samples from the previous update steps when adjusting the mixture density. The parameter determines the number of update steps to “look back”, and must be non-negative. The default value of 1 disables this feature, a value of 0 means that all previous steps are used.

eos.sample_prior(analysis_file: str, posterior: str, base_directory: str = './', N: int = 1000, seed: int = 1701)

Samples from a named posterior PDF w/o likelihood information, an effective prior PDF.

The output file will be stored in EOS_BASE_DIRECTORY/data/POSTERIOR/samples.

Parameters:

analysis_file (str or eos.AnalysisFile) – The name of the analysis file that describes the named prior, or an object of class eos.AnalysisFile.
posterior (str) – The name of the posterior PDF (w/o any likelihood information) from which to draw the samples.
base_directory (str, optional) – The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.
N (int, optional) – The number of samples to be stored in the output file. Defaults to 1000.
seed (int, optional) – The seed used to initialize the Mersenne Twister pseudo-random number generator.

eos.validate(analysis_file: str, deep: bool = True)

Validates the analysis file structurally and semantically, then by default checks that all posteriors and prediction sets can be created. The deep phase inserts declarations into the process-wide EOS registries; once it has run, those registries are contaminated for the remainder of the process. Use deep=False for idempotent, side-effect-free validation.

Parameters:

analysis_file (str) – The name of the analysis file to validate.
deep (bool) – If True, additionally check that all posteriors and prediction sets can be created. Defaults to True.

Accessing Data

EOS provides access to save and load the various (intermediate) results of analyses via the eos.data module.

class eos.data.ImportanceSamples(path)

Represents a set of weighted importance samples stored on disk.

Bundles samples in parameter space with their importance weights and, optionally, the values of the posterior density at each sample. Instances are created either by reading an existing data set from disk (passing its path to the constructor) or by writing a new data set with create().

Variables:

type – The type identifier of the data object, always 'ImportanceSamples'.
varied_parameters – The descriptions (name, min, max) of the varied parameters.
lookup_table – A mapping from each parameter name to its column index in samples.
weights – The importance weights on a linear scale as a 1D array of shape (N, ).
posterior_values – The posterior density values at each sample as a 1D array of shape (N, ), or None if not stored.

static create(path, parameters, samples, weights, posterior_values=None)

Write a new ImportanceSamples object to disk.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
parameters (collections.abc.Sequence of eos.Parameter) – Parameter descriptions as a 1D array of shape (P, ).
samples (numpy.ndarray) – Samples as a 2D array of shape (N, P).
weights (numpy.ndarray, optional) – Weights on a linear scale as a 1D array of shape (N, ).

samples: ndarray: The samples in parameter space as a 2D array of shape (N, P).

class eos.data.MarkovChain(path)

Represents the parameter samples of a single Markov chain stored on disk.

A Markov chain bundles samples drawn in parameter space together with their counterparts in the unit-hypercube u space and, optionally, importance weights. Instances are created either by reading an existing chain from disk (passing its path to the constructor) or by writing a new chain with create().

Variables:

type – The type identifier of the data object, always 'MarkovChain'.
varied_parameters – The descriptions (name, min, max) of the varied parameters.
lookup_table – A mapping from each parameter name to its column index in samples.
usamples – The samples in unit-hypercube u space as a 2D array of shape (N, P).
weights – The importance weights on a linear scale as a 1D array of shape (N, ), or None if the chain is unweighted.

static create(path, parameters, samples, usamples, weights=None)

Write a new MarkovChain object to disk.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
parameters (collections.abc.Sequence of eos.Parameter) – Parameter descriptions as a 1D array of shape (N, ).
samples (numpy.ndarray) – Samples in parameter space as a 2D array of shape (N, P).
usamples (numpy.ndarray) – Samples in u space as a 2D array of shape (N, P).
weights (numpy.ndarray, optional) – Weights on a linear scale as a 1D array of shape (N, ).

samples: ndarray: The samples in parameter space as a 2D array of shape (N, P).

class eos.data.MixtureDensity(path)

Represents a mixture density (e.g. a PMC proposal or a fit to a posterior) stored on disk.

Stores the components and weights of a mixture of (Gaussian) densities together with the descriptions of the varied parameters and, optionally, precomputed test statistics. Instances are created either by reading an existing density from disk (passing its path to the constructor) or by writing a new density with create(). Use density() to obtain the corresponding pypmc.density.mixture.MixtureDensity.

Variables:

type – The type identifier of the data object, always 'MixtureDensity'.
format_version – The on-disk format version the density was read from (1 for legacy files).
components – The descriptions of the mixture components.
weights – The component weights of the mixture.
lookup_table – A mapping from each parameter name to its index in varied_parameters.
test_statistics – The precomputed test statistics, or None if not stored.

static cartesian_product(densities)

Construct the cartesian product of a list of mixture densities. The means and covariances of the components are copied and concatenated and the weights are multiplied. Note that this product is not commutative, the order of densities affects the order of parameters in the output density. Only Gaussian mixtures are supported.

Parameters:: densities (collections.abc.Sequence of pypmc.density.MixtureDensity) – List of mixture densities.

static create(path, density, parameters, sigma_test_stat=None, samples=None, weights=None)

Write a new MixtureDensity object to disk.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
density (pypmc.density.MixtureDensity) – Mixture density.
parameters (list or collections.abc.Iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (P, ).
sigma_test_stat (list or collections.abc.Iterable) – (optional) If provided, the inverse CDF of -2*log(PDF) will be evaluated, using the provided values as the respective significance.
samples (numpy.ndarray, optional) – Samples as a 2D array of shape (N, P). Needed to generate the test statistic.
weights (numpy.ndarray, optional) – Weights on a linear scale as a 2D array of shape (N, 1). Needed to generate the test statistic.

density()

Construct the corresponding PyPMC mixture density.

Returns:: A Gaussian mixture density built from the stored components and weights.
Return type:: pypmc.density.mixture.MixtureDensity
Raises:: ImportError – If the optional PyPMC module is not installed.

varied_parameters: list | None: The descriptions (name, min, max) of the varied parameters, or None for a legacy file that does not record them.

class eos.data.Mode(path)

Represents a (local) mode of a posterior density stored on disk.

Stores the location of the mode in parameter space together with goodness-of-fit information. Instances are created either by reading an existing mode from disk (passing its path to the constructor) or by writing a new mode with create() (low-level) or from_bfp_and_gof() (from an optimization result).

Variables:

type – The type identifier of the data object, always 'Mode'.
format_version – The on-disk format version the mode was read from (1 for legacy files).
varied_parameters – The descriptions (name, min, max) of the varied parameters.
mode – The location of the mode in parameter space.
pvalue – The global p-value at the mode.
local_pvalues – A mapping from each element’s name to its local p-value, derived from test_statistics.
global_chi2 – The global \(\chi^2\) value at the mode, or None if not stored.
dof – The number of degrees of freedom, or None if not stored.

static create(path, parameters, mode, pvalue, test_statistics, global_chi2, dof)

Write a new Mode object to disk.

This is the low-level serializer. To record a mode obtained from an optimization, prefer from_bfp_and_gof(), which derives the arguments below from the best-fit point and the goodness-of-fit object.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
parameters (list or collections.abc.Iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (N, ).
mode (numpy.ndarray) – The mode to be stored.
pvalue (float) – The global p-value of the mode.
test_statistics (list of dict) – The per-element test statistics, each a mapping with the keys name, local_pvalue and, optionally, type (default 'chi^2') and value.
global_chi2 (float) – The global chi2 value of the mode.
dof (float) – The degrees of freedom of the mode.

static from_bfp_and_gof(path, bfp, gof)

Write a new Mode object to disk from an optimization result.

Derives the varied parameters and the mode from the best-fit point bfp and the global and per-element test statistics (chi^2 values, degrees of freedom, and p-values) from the goodness-of-fit object gof, then delegates to create().

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
bfp (eos.BestFitPoint) – The best-fit point, as returned by eos.Analysis.optimize().
gof (eos.GoodnessOfFit) – The goodness-of-fit at the best-fit point.

test_statistics: list: The per-element test statistics at the mode (name, type, value, local p-value).

class eos.data.PMCSampler(path)

Represents the proposal density of a population Monte Carlo (PMC) sampler stored on disk.

Stores the Gaussian components and weights of the PMC proposal mixture together with the descriptions of the varied parameters. Instances are created either by reading an existing sampler from disk (passing its path to the constructor) or by writing a new sampler with create(). Use density() to obtain the corresponding pypmc.density.mixture.MixtureDensity. Reading requires the optional PyPMC module.

Variables:

type – The type identifier of the data object, always 'PMCSampler'.
lookup_table – A mapping from each parameter name to its index in varied_parameters.
components – The Gaussian components of the proposal mixture.
component_weights – The weights of the proposal mixture components.
test_statistics – The precomputed test statistics.

static create(path, parameters, proposal, sigma_test_stat=None, samples=None, weights=None)

Write a new PMCSampler object to disk.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
parameters (list or collections.abc.Iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (P, ).
sigma_test_stat (list or collections.abc.Iterable) – (optional) If provided, the inverse CDF of -2*log(PDF) will be evaluated, using the provided values as the respective significance.
samples (numpy.ndarray, optional) – Samples as a 2D array of shape (N, P). Needed to generate the test statistic.
weights (numpy.ndarray, optional) – Weights on a linear scale as a 1D array of shape (N, ). Needed to generate the test statistic.

density()

Construct the corresponding PyPMC mixture density.

Returns:: A Gaussian mixture density built from the stored proposal components and weights.
Return type:: pypmc.density.mixture.MixtureDensity
Raises:: ImportError – If the optional PyPMC module is not installed.

varied_parameters: list: The descriptions (name, min, max) of the varied parameters.

class eos.data.Prediction(path)

Represents weighted samples of theory predictions for one or more observables, stored on disk.

Bundles the predictive samples of a set of observables with their importance weights. Instances are created either by reading an existing data set from disk (passing its path to the constructor) or by writing a new data set with create().

Each column is either a genuine observable or a parameter clothed as an observable; the two are distinguished by the kind key of the corresponding entry in varied_parameters.

Variables:

type – The type identifier of the data object, always 'Prediction'.
format – The on-disk format version the prediction was read from (1 for legacy files).
lookup_table – A mapping from each column’s qualified name (including options and kinematics) to its column index in samples.
weights – The importance weights on a linear scale as a 1D array of shape (N, ).

static create(path, observables, samples, weights)

Write a new Prediction object to disk.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
observables (collections.abc.Sequence of eos.Observable) – Observables as a 1D array of shape (O, ).
samples (numpy.ndarray) – Samples as a 2D array of shape (N, O).
weights (numpy.ndarray) – Weights on a linear scale as a 1D array of shape (N, ).

samples: ndarray: The predictive samples as a 2D array of shape (N, O).

varied_parameters: list: The descriptions (name, kind, kinematics, options) of the predicted columns.

class eos.data.SampleMask(path)

Represents a boolean mask over a set of observables, stored on disk.

A mask selects a subset of samples (e.g. to remove unphysical points) and records the observables it applies to. Instances are created either by reading an existing mask from disk (passing its path to the constructor) or by writing a new mask with create().

Variables:

type – The type identifier of the data object, always 'SampleMask'.
observables – The observables to which the mask applies.
mask – The boolean mask as a 1D array.

static create(path, mask, observables)

Write a new SampleMask object to disk.

Parameters:

path (str) – Path to the storage location, which will be created as a directory.
mask (collections.abc.Sequence of bool) – Mask as a 1D boolean array
observables – Observables as a 1D array

Plotting Classes

The eos.figure submodule provides means to produce publication-quality figures.

A figure contains one or more plots, each of which is a set of axis that can be thought of as a ‘canvas’ to draw on. A plot further contains items for display, for example a constraint in the form of data points with error bars or an observable as a function of a kinematic variable in the form or a line graph.

Note

Import eos.figure before you do something like import matplotlib.pyplot as plt, because the eos.figure module modified the default plot style and the matplotlib backend. All options (except the backend) can be overwritten by updating matplotlib.rcParams[...]; see also the matplotlib documentation. Note that the default settings use LaTeX to create labels and math expressions, so for this to work latex needs to be available on your system.

EOS also provides a new plotting framework with a different interface, which will replace the existing framework as soon as it is feature complete. Within the new framework, Figures are created using the eos.figure.FigureFactory class, which returns an object of a class descended by eos.figure.Figure. The figure is responsible for creating and managing the matplotlib figure object. It also creates the plot or plots that are contained in the figure as objects of classes descended from eos.figure.plot.Plot. These objects manage the axes of the figure and the individual plot items that are contained in the plot. The actual contents are created using the eos.figure.item.ItemFactory class, which returns an object of a class descended from eos.figure.item.Item. The item is responsible for creating the actual plot item, such as the curve of an EOS observable, a scatter plot of parameters, a histogram or a kernel density estimate, to name some of the options.

A figure is rendered by its draw method, and the rendered figure is stored to one or more output files by its save method. A figure must only be drawn once; drawing it repeatedly stacks its elements on top of each other, which distorts the colors of elements with an opacity < 1.

Figure and Related Classes

class eos.figure.Figure(*, name: str = None)

Base class for figures to be drawn using matplotlib.

Note

The eos.figure.plot.Plot class is the base class for all plot items. It is not intended to be used directly. To create a a concrete plot, use the PlotFactory class.

abstractmethod draw(context: AnalysisFileContext = None)

Draw the figure.

Parameters:: context (AnalysisFileContext) – The analysis file context, which contains the paths to the data files and other relevant information.

save(output: str | list[str])

Save the figure to one or more output files.

The figure must have been drawn by a call to draw beforehand; saving an undrawn figure yields an empty figure. Drawing the same figure more than once stacks its elements on top of each other, which distorts the colors of elements with opacity < 1; draw once and pass all output files to a single call to this method instead.

Parameters:: output (str | list[str]) – The path(s) to the output file(s) where the figure is saved. The file format of each output file is determined by its file name extension.

class eos.figure.FigureFactory

Factory class to create figures from a dictionary description.

This class provides a convenient way to create figures from a dictionary description, which can be used to deserialize figures. The factory method from_dict() should be used to create a figure from a dictionary description. The description contains the arguments used for initializing objects of classes within the eos.figure module.

A figure can contain one or more individual plots. Each plot contains one or more plottable items, such as a data series from the evaluation of an observable or a kernel density estimate to visualize a set of statistical samples.

The factory method from_yaml() can be used to create a figure from a YAML description.

The list of available figure types is as follows:

figure type	Python class	description
`single`	`eos.figure.SingleFigure`	Produces a figure with a single plot.
`inset`	`eos.figure.InsetFigure`	Produces an inset figure with a main plot and a smaller inset plot.
`grid`	`eos.figure.GridFigure`	Produces a figure with a configurable number of plots, arranged in a grid.
`corner`	`eos.figure.CornerFigure`	Produces a corner figure, i.e., a figure with a triangular arrangement of 1D and 2D marginal PDFs.

static from_dict(**kwargs)

Factory method to create a plot from a dictionary

This method takes a dictionary description of a figure and uses matplotlib to render that figure conveniently and at a publication-grade level.

The description contains the arguments used for initializing objects of classes within the eos.figure module.

A figure can contain one or more individual plots. Each plot contains one or more plottable items, such as a data series from the evaluation of an observable or a kernel density estimate to visualize a set of statistical samples.

Parameters:: description (dict) – A figure description as required by any of the descendant classes of eos.figure.Figure.
Returns:: A descendant of the eos.figure.Figure class
Return type:: eos.figure.Figure

static from_yaml(yaml_data: str)

Factory method to create a figure from a YAML description.

This method takes a YAML description of a figure, turns it into a dict, and forwards it to the from_dict() method.

Parameters:: yaml_data (str) – A YAML description of the figure.
Returns:: A descendant of the eos.figure.Figure class
Return type:: eos.figure.Figure

class eos.figure.SingleFigure(*, name: str = None, plot: Plot, size: tuple[float, float]=(6.4, 4.8), watermark: Watermark = <factory>)

Produces a figure with a single plot.

Parameters:

plot (Plot) – The plot to be drawn in the figure. This can be any of the Plot descendants.
size (tuple[float, float]) – The size of the figure in inches. Defaults to (6.4, 4.8).
watermark (Watermark) – The optional specification where and how to draw the EOS watermark. For the default specification, see Watermark.

draw(context: AnalysisFileContext = None)

Draw the single-plot figure.

Prepares and draws the figure’s plot and adds the watermark. Use save to store the drawn figure to one or more output files.

Parameters:: context (AnalysisFileContext) – The analysis file context, which contains the paths to the data files and other relevant information.

classmethod from_dict(**kwargs)

Create a SingleFigure from its keyword description.

Recursively deserializes the nested plot description via PlotFactory and the optional watermark description.

Parameters:: kwargs – The figure description. Must contain a plot key.
Returns:: The instantiated figure.
Return type:: SingleFigure

class eos.figure.InsetFigure(*, name: str = None, plot: Plot, inset: Plot, size: tuple[float, float]=(6.4, 4.8), watermark: Watermark = <factory>)

Produces an inset figure with a main plot and a smaller inset plot.

Parameters:

plot (Plot) – The main plot to be drawn in the figure. This can be any of the Plot descendants.
inset (Inset) – The inset plot to be drawn in the figure. This should be an instance of Inset.
size (tuple[float, float]) – The size of the figure in inches. Defaults to (6.4, 4.8).
watermark (Watermark) – The optional specification where and how to draw the EOS watermark.

draw(context: AnalysisFileContext = None)

Draw the inset figure.

Use save to store the drawn figure to one or more output files.

Parameters:: context (AnalysisFileContext) – The analysis file context, which contains the paths to the data files and other relevant information.

classmethod from_dict(**kwargs)

Create an InsetFigure from its keyword description.

Recursively deserializes the nested plot and inset descriptions, as well as the optional watermark description.

Parameters:: kwargs – The figure description. Must contain plot and inset keys.
Returns:: The instantiated figure.
Return type:: InsetFigure

class eos.figure.GridFigure(*, name: str = None, plots: list[~eos.figure.plot.Plot], padding: tuple[float, float] = (0.2, 0.2), shape: tuple[int, int], size: tuple[float, float] | None = None, watermark: ~eos.figure.common.Watermark = <factory>, watermark_plot: int | tuple[int, int] | str | None = None, tight_layout: bool = True, shared_axes: str | None = None, height_ratios: list[float] | None = None, width_ratios: list[float] | None = None)

Produces a figure with a configurable number of plots, arranged in a grid.

The list of plots are assigned to the grid positions in row-major order, i.e. the first plot is assigned to the first row and first column, the second plot to the first row and second column, and so on.

Parameters:

padding (tuple[float, float]) – The tuple of horizontal and vertical padding between the plots in the grid, specified as a tuple of fractions of the average plot size. Defaults to (0.2, 0.2).
plots (list[Plot]) – The list of Plot objects to be drawn in the figure.
shape (tuple[int, int]) – The tuple specifying the shape of the figure’s grid, specifying the number of rows and columns in that order.
size (tuple[float, float]) – The size of the figure in inches. Defaults to (3.0 * ncol, 3.0 * nrow).
watermark_plot (int | tuple[int, int] | str | None) – The plot that carries the watermark, as a flattened (row-major) index, a 2D (row, col) address, or 'all' to stamp every plot that is not empty. An explicitly selected plot is stamped even if it is empty. Defaults to None (the bottom-right plot that is not empty).
tight_layout (bool) – If True (default), the grid spec is laid out with tight_layout. Set to False to keep an explicit padding, e.g. (0, 0) for abutting panels.
shared_axes (str | None) – Which axes the panels share, one of None, 'x', 'y', or 'both'. 'x' shares the x-axis per column (sharex='col'), 'y' shares the y-axis per row (sharey='row'), and 'both' shares both; a shared axis gives one common range per group and tick labels only on the outer edge. Defaults to None (independent axes).
height_ratios (list[float] | None) – The relative height of each row, e.g. [4, 1] for a 2-row grid whose second row is a quarter as tall as the first. Must have one entry per row. Defaults to None (equal heights).
width_ratios (list[float] | None) – The relative width of each column, analogous to height_ratios. Must have one entry per column. Defaults to None (equal widths).

draw(context: AnalysisFileContext = None)

Draw the grid figure.

Use save to store the drawn figure to one or more output files.

Parameters:: context (AnalysisFileContext) – The analysis file context, which contains the paths to the data files and other relevant information.

classmethod from_dict(**kwargs)

Create a GridFigure from its keyword description.

Recursively deserializes each entry of the plots list via PlotFactory, as well as the optional watermark description.

Parameters:: kwargs – The figure description. Must contain plots and shape keys.
Returns:: The instantiated figure.
Return type:: GridFigure

class eos.figure.CornerFigure(*, name: str = None, contents: list[~eos.figure.data.DataFile], variables: list[str] = None, kde: bool = False, watermark: ~eos.figure.common.Watermark = <factory>, watermark_plot: int | tuple[int, int] | str | None = None)

Produces a corner figure, i.e., a figure with a triangular arrangement of 1D and 2D marginal PDFs.

Distributions of the variables are shown on the diagonal, while correlations are plotted on the lower-left corner.

Parameters:

contents (list[DataFile]) – The list of DataFile objects to be used, each containing the path to the data file, its label, and optionally its color.
variables (list[str] | None) – The list of variable names to be shown. If not provided, all variables contained in the first data file are shown.
watermark (Watermark) – The optional specification where and how to draw the EOS watermark. For the default specification, see Watermark.
watermark_plot (int | tuple[int, int] | str | None) – The plot that carries the watermark, as a flattened (row-major) index, a 2D (row, col) address, or 'all' to stamp every plot that is not empty. An explicitly selected plot is stamped even if it is empty. Defaults to None (the plot in the bottom-left corner).

draw(context: AnalysisFileContext = None)

Draw the corner figure.

Use save to store the drawn figure to one or more output files.

Parameters:: context (AnalysisFileContext) – The analysis file context, which contains the paths to the data files and other relevant information.

classmethod from_dict(**kwargs)

Create a CornerFigure from its keyword description.

Recursively deserializes each entry of the contents list into a DataFile instance, as well as the optional watermark description.

Parameters:: kwargs – The figure description. Must contain a contents key.
Returns:: The instantiated figure.
Return type:: CornerFigure

prepare(context: AnalysisFileContext = None)

Prepare the corner figure for drawing.

Parameters:: context (AnalysisFileContext) – The analysis file context, which contains the paths to the data files and other relevant information.

save(output: str | list[str])

Save the corner figure to one or more output files.

This figure’s contents are drawn by an underlying GridFigure, to which saving is delegated.

Parameters:: output (str | list[str]) – The path(s) to the output file(s) where the figure is saved. The file format of each output file is determined by its file name extension.

class eos.figure.Inset(*, plot: Plot, position: tuple[float, float], size: tuple[float, float])

Represents the inset properties for an InsetFigure.

Parameters:

plot (Plot) – The inset plot to be drawn in the figure. This can be any of the Plot descendants.
position (tuple[float, float]) – The position of the bottom left corner of the inset plot in the figure, specified as a tuple of (x, y) coordinates in normalized figure coordinates (0 to 1).
size (tuple[float, float]) – The size of the inset plot, specified as a tuple of (width, height) in normalized figure coordinates (0 to 1).

draw(ax)

Draw the inset plot and indicate its zoom region on the parent axes.

Parameters:: ax (matplotlib.axes.Axes) – The parent matplotlib axes on which the inset’s zoom region is indicated.

classmethod from_dict(**kwargs)

Create an Inset from its keyword description.

Recursively deserializes the nested plot description via PlotFactory.

Parameters:: kwargs – The inset description. Must contain a plot key.
Returns:: The instantiated inset.
Return type:: Inset

prepare(context, ax)

Prepare the inset plot for drawing.

Creates the inset axes at the configured position and size within the parent axes and prepares the inset’s plot.

Parameters:

context (AnalysisFileContext | None) – The analysis file context forwarded to the inset’s plot.
ax (matplotlib.axes.Axes) – The parent matplotlib axes into which the inset axes are inserted.

Plot and Related Classes

class eos.figure.Plot

Base class for plots to be drawn into a figure.

Note

The eos.figure.Plot class is the base class for all plot items. It is not intended to be used directly. To create a a concrete plot, use the PlotFactory class.

abstractmethod draw(ax)

Draw the plot on the provided axes.

Subclasses override this method to render their items, axes, grid, and legend.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the plot is drawn.

draw_watermark(ax, watermark)

Draw the watermark on the provided axes.

Parameters:

ax (matplotlib.axes.Axes) – The matplotlib axes onto which the watermark is drawn.
watermark (eos.figure.common.Watermark) – The watermark to draw.

abstractmethod prepare(context: AnalysisFileContext = None)

Prepare the plot for drawing.

Subclasses override this method to prepare all of their items before drawing.

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve relative paths to data files. If None, a default context rooted at the current working directory is used.

class eos.figure.PlotFactory

Factory that creates Plot instances from their YAML or dictionary description.

The concrete plot class is selected from the optional type key using the registry, which maps each supported type string to its corresponding Plot subclass. If no type is given, the default '2D' plot is created.

The list of available plot types is as follows:

plot type	Python class	description
`2D`	`eos.figure.TwoDimensionalPlot`	Draws a 2D plot along a single set of axes.
`empty`	`eos.figure.EmptyPlot`	Draws an empty plot.

static from_dict(**kwargs)

Create a plot from its keyword description.

The optional type key selects the concrete Plot subclass from registry, defaulting to '2D'; the remaining keyword arguments are forwarded to that subclass. The item color cycle is reset before the plot is created.

Parameters:: kwargs – The plot description. May contain a type key identifying a registered plot type.
Returns:: The instantiated plot.
Return type:: Plot
Raises:: ValueError – If the type key names an unknown plot type.

static from_yaml(yaml_data: str)

Create a plot from a YAML description.

Parameters:: yaml_data (str) – A YAML string describing a single plot, optionally including its type key.
Returns:: The instantiated plot.
Return type:: Plot

registry = {'2D': <class 'eos.figure.plot.TwoDimensionalPlot'>, 'empty': <class 'eos.figure.plot.EmptyPlot'>}: Maps each supported type string to the Plot subclass that implements it.

class eos.figure.TwoDimensionalPlot(*, aspect: float | None = None, grid: ~eos.figure.plot.Grid = <factory>, items: list[~eos.figure.item.Item], legend: ~eos.figure.plot.Legend = None, title: str = None, xaxis: ~eos.figure.plot.XAxis = <factory>, yaxis: ~eos.figure.plot.YAxis = <factory>)

Draws a 2D plot along a single set of axes.

Parameters:

aspect (float | None) – The aspect ratio of the plot. If None, the aspect ratio defaults to matplotlib’s default.
grid (Grid) – The grid properties of the plot. For the default properties, see Grid.
items (list[Item]) – A list of items to be drawn in the plot.
legend (Legend) – The legend properties of the plot. For the default properties, see Legend.
title (str | None) – The title of the plot. Defaults to None, which means no title is displayed.
xaxis (XAxis) – The x axis properties of the plot. For the default properties, see XAxis.
yaxis (YAxis) – The y axis properties of the plot. For the default properties, see YAxis.

draw(ax)

Draw the plot and all of its items on the provided axes.

Sets the title, configures the grid, aspect ratio, and axes, draws each item, and collects the items’ legend entries into the legend.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the plot is drawn.

classmethod from_dict(**kwargs)

Create a TwoDimensionalPlot from its keyword description.

Recursively deserializes the nested grid, legend, xaxis, and yaxis descriptions, as well as each entry of items via ItemFactory.

Parameters:: kwargs – The plot description. Must contain an items key.
Returns:: The instantiated plot.
Return type:: TwoDimensionalPlot

prepare(context: AnalysisFileContext = None)

Prepare the plot by preparing each of its items.

Parameters:: context (AnalysisFileContext | None) – The analysis file context forwarded to each item’s prepare method. If None, a default context rooted at the current working directory is used.

class eos.figure.EmptyPlot

Draws an empty plot.

Can be used in a grid as empty space instead of a plot. It does not accept any parameters.

draw(ax)

Draw the empty plot by turning off the provided axes.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes to turn off.

prepare(context: AnalysisFileContext = None)

Prepare the empty plot for drawing.

This plot requires no preparation.

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency and unused.

class eos.figure.Grid(visible: bool = False, axis: str = 'both')

Represents the grid properties in a plot.

Parameters:

visible (bool) – Whether the grid is visible. Defaults to False.
axis (str) – The axis on which the grid is drawn. Can be ‘both’, ‘x’, or ‘y’. Defaults to ‘both’.

draw(ax)

Draw the grid on the provided axes if it is visible.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the grid is drawn.

class eos.figure.Legend(position: str = 'best')

Represents the legend properties in a plot.

Parameters:: position (str) – The position of the legend in the plot. Defaults to ‘best’, which automatically places the legend in the best location.

draw(ax, entries=None)

Draw the legend on the axes.

Parameters:

ax (matplotlib.axes.Axes) – The axes to draw the legend on.
entries (list[tuple[matplotlib.artist.Artist, str]] | None) – A list of tuples (handle, label) for the legend entries. If None, uses the entries from the items.

class eos.figure.XAxis(label: str = None, range: tuple[float, float]=None, ticks: XTicks = <factory>, unit: str = None, scale: str = 'linear')

Represents the x axis properties in a plot.

Parameters:

label (str) – The label for the x axis.
range (tuple[float, float] | None) – The range of the x axis as a tuple (min, max). Defaults to None, which means the range is determined empirically.
ticks (XTicks) – The x axis ticks properties. Defaults to an instance of XTicks.
unit (str | None) – The unit of the x axis, e.g., ‘GeV’. Defaults to None.
scale (str) – The scale of the x axis, e.g., ‘linear’ or ‘log’. Defaults to ‘linear’.

draw(ax)

Apply the x axis settings to the provided axes.

Sets the axis label (including the unit, if given), the axis range and scale, and draws the ticks.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes whose x axis is configured.

classmethod from_dict(**kwargs)

Create an XAxis from its keyword description.

Recursively deserializes the nested ticks description into an XTicks instance.

Parameters:: kwargs – The x axis description.
Returns:: The instantiated x axis.
Return type:: XAxis

class eos.figure.XTicks(minor: bool = True, position: str = 'bottom', visible: bool = True, format: str | None = None, scaling_factor: float | None = None, locations: list[float] | None = None)

Represents the x axis ticks properties in a plot.

Parameters:

minor (bool) – Whether to show minor ticks. Defaults to True.
position (str) – The position of the ticks. Can be ‘bottom’, ‘top’, or ‘both’. Defaults to ‘bottom’.
visible (bool) – Whether the ticks are visible. Defaults to True.
format (str | None) – A printf-style format string for the major tick labels, e.g. ‘%.2f’. Defaults to None (matplotlib’s default formatter).
scaling_factor (float | None) – A non-zero factor by which each major tick value is divided before being displayed, e.g. 1e-3 to label an axis in units of \(10^{-3}\). The (rescaled) value is rendered with format if given, or with '%g' otherwise. The magnitude removed in this way should be communicated through the axis label or unit. Intended for linear axes. Defaults to None (no rescaling).
locations (list[float] | None) – Explicit positions for the major ticks, e.g. [-2, 0, 2]. Overrides the automatic tick placement, which otherwise chooses a step (and so which values end up labelled) based on the axes’ rendered size rather than on the data range alone. Defaults to None (automatic placement).

draw(ax)

Apply the x axis tick settings to the provided axes.

Configures the visibility, position (bottom/top/both), and major/minor locators of the x axis ticks, accounting for linear and logarithmic scales.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes whose x axis ticks are configured.

class eos.figure.YAxis(label: str = None, range: tuple[float, float]=None, ticks: YTicks = <factory>, unit: str = None, scale: str = 'linear')

Represents the y axis properties in a plot.

Parameters:

label (str) – The label for the y axis.
range (tuple[float, float] | None) – The range of the y axis as a tuple (min, max). Defaults to None, which means the range is determined empirically.
ticks (YTicks) – The y axis ticks properties. Defaults to an instance of YTicks.
unit (str | None) – The unit of the y axis, e.g., ‘GeV’. Defaults to None.
scale (str) – The scale of the y axis, e.g., ‘linear’ or ‘log’. Defaults to ‘linear’.

draw(ax)

Apply the y axis settings to the provided axes.

Sets the axis label (including the unit, if given), the axis range and scale, and draws the ticks.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes whose y axis is configured.

classmethod from_dict(**kwargs)

Create a YAxis from its keyword description.

Recursively deserializes the nested ticks description into a YTicks instance.

Parameters:: kwargs – The y axis description.
Returns:: The instantiated y axis.
Return type:: YAxis

class eos.figure.YTicks(minor: bool = True, position: str = 'left', visible: bool = True, format: str | None = None, scaling_factor: float | None = None, locations: list[float] | None = None)

Represents the y axis ticks properties in a plot.

Parameters:

minor (bool) – Whether to show minor ticks. Defaults to True.
position (str) – The position of the ticks. Can be ‘left’, ‘right’, or ‘both’. Defaults to ‘left’.
visible (bool) – Whether the ticks are visible. Defaults to True.
format (str | None) – A printf-style format string for the major tick labels, e.g. ‘%.2f’. Defaults to None (matplotlib’s default formatter).
scaling_factor (float | None) – A non-zero factor by which each major tick value is divided before being displayed, e.g. 1e-3 to label an axis in units of \(10^{-3}\). The (rescaled) value is rendered with format if given, or with '%g' otherwise. The magnitude removed in this way should be communicated through the axis label or unit. Intended for linear axes. Defaults to None (no rescaling).
locations (list[float] | None) – Explicit positions for the major ticks, e.g. [-2, 0, 2]. Overrides the automatic tick placement, which otherwise chooses a step (and so which values end up labelled) based on the axes’ rendered size rather than on the data range alone. Defaults to None (automatic placement).

Item and Related Classes

class eos.figure.item.Item(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0)

Base class for items to be drawn in a figure.

Note

The eos.figure.item.Item class is the base class for all plot items. It is not intended to be used directly. To create a a concrete plot item, use the ItemFactory class.

abstractmethod draw(ax)

Draw the item on the provided axes.

Subclasses override this method to render the quantities cached by prepare().

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the item is drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

The default implementation returns an empty list, i.e. the item contributes no dedicated legend entry. Subclasses that require a custom legend handle override this

Returns:: A list of (handle, label) pairs to be added to the plot legend.
Return type:: list[tuple[matplotlib.artist.Artist, str]]

abstractmethod prepare(context: AnalysisFileContext = None)

Prepare the item for drawing.

Subclasses override this method to load any required data files and to evaluate and cache the quantities that draw() will render. It is called once before draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve relative paths to data files. If None, a default context rooted at the current working directory is used.

class eos.figure.item.ItemFactory

Factory that creates Item instances from their YAML or dictionary description.

The concrete item class is selected from the mandatory type key using the registry, which maps each supported type string (e.g. 'observable', 'kde1D', 'constraint') to its corresponding Item subclass.

The list of available item types is as follows:

item type	Python class	description
`observable`	`ObservableItem`	Plots an observables from the EOS library of builtin observables.
`expression`	`ExpressionItem`	Plots an arbitrary mathematical expression as a function of the x-axis variable.
`uncertainty`	`UncertaintyBandItem`	Plots the 68.27% (default) uncertainty band as a function of one kinematic variable or one parameter.
`uncertainty-binned`	`BinnedUncertaintyItem`	Plots one or more uncertainty band integrated over one kinematic variable.
`constraint`	`ConstraintItem`	Plots statistical constraints from the EOS library of experimental and theoretical likelihoods.
`constraint-residue`	`ConstraintResidueItem`	Plots the residues of a statistical constraints from the EOS library of experimental and theoretical likelihoods.
`constraint2D`	`TwoDimensionalConstraintItem`	Plots the 2D contours of two correlated observables from a single constraint.
`histogram1D`	`OneDimensionalHistogramItem`	Plots a one-dimensional histogram.
`histogram2D`	`TwoDimensionalHistogramItem`	Plots a two-dimensional histogram.
`kde1D`	`OneDimensionalKernelDensityEstimateItem`	Plotting a one-dimensional kernel density estimate (KDE).
`kde2D`	`TwoDimensionalKernelDensityEstimateItem`	Plots a two-dimensional kernel density estimate (KDE).
`contours2D`	`TwoDimensionalContoursItem`	Plots two-dimensional probability contours from a histogram of pre-existing samples.
`band`	`BandItem`	Plots a shaded band.
`vertical`	`VerticalLineItem`	Plots a vertical line at a fixed position on the x axis.
`signal-pdf`	`SignalPDFItem`	Plots a single EOS signal PDF w/o uncertainties as a function of one kinematic variable
`complex-plane`	`ComplexPlaneItem`	Plots a single observable as a function on the complex plan
`errorbars`	`ErrorBarsItem`	Plots one or more error bars at specified position(s).
`point`	`PointItem`	Plots a single point at a fixed position.

static from_dict(**kwargs)

Create an item from its keyword description.

The mandatory type key selects the concrete Item subclass from registry; the remaining keyword arguments are forwarded to that subclass.

Parameters:: kwargs – The item description. Must contain a type key identifying a registered item type.
Returns:: The instantiated item.
Return type:: Item
Raises:: ValueError – If the type key is missing or names an unknown item type.

static from_yaml(yaml_data: str)

Create an item from a YAML description.

Parameters:: yaml_data (str) – A YAML string describing a single item, including its type key.
Returns:: The instantiated item.
Return type:: Item

registry = {'band': <class 'eos.figure.item.BandItem'>, 'complex-plane': <class 'eos.figure.item.ComplexPlaneItem'>, 'constraint': <class 'eos.figure.item.ConstraintItem'>, 'constraint-residue': <class 'eos.figure.item.ConstraintResidueItem'>, 'constraint2D': <class 'eos.figure.item.TwoDimensionalConstraintItem'>, 'contours2D': <class 'eos.figure.item.TwoDimensionalContoursItem'>, 'errorbars': <class 'eos.figure.item.ErrorBarsItem'>, 'expression': <class 'eos.figure.item.ExpressionItem'>, 'histogram1D': <class 'eos.figure.item.OneDimensionalHistogramItem'>, 'histogram2D': <class 'eos.figure.item.TwoDimensionalHistogramItem'>, 'kde1D': <class 'eos.figure.item.OneDimensionalKernelDensityEstimateItem'>, 'kde2D': <class 'eos.figure.item.TwoDimensionalKernelDensityEstimateItem'>, 'observable': <class 'eos.figure.item.ObservableItem'>, 'point': <class 'eos.figure.item.PointItem'>, 'signal-pdf': <class 'eos.figure.item.SignalPDFItem'>, 'uncertainty': <class 'eos.figure.item.UncertaintyBandItem'>, 'uncertainty-binned': <class 'eos.figure.item.BinnedUncertaintyItem'>, 'vertical': <class 'eos.figure.item.VerticalLineItem'>}: Maps each supported type string to the Item subclass that implements it.

class eos.figure.item.ObservableItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, observable: QualifiedName, fixed_kinematics: dict = None, fixed_parameters: dict = None, fixed_parameters_from_file: str = None, options: dict = None, range: tuple[float, float], resolution: int = 100, variable: str)

Plots an observables from the EOS library of builtin observables.

This item type is used to plot observables as a function of one kinematic variable or one parameter.

Parameters:

observable (eos.QualifiedName) – The name of the observable to be plotted.
fixed_kinematics (dict[str, float] | None) – A dictionary of additional kinematic variables and the values to which they shall be fixed.
fixed_parameters (dict[eos.QualifiedName, float] | None) – A dictionary of EOS parameters and the values to which they shall be fixed.
fixed_parameters_from_file (str | None) – Path to a file containing EOS parameters to be used for the observable.
label (str | None) – The label for the observable, which will be used in the plot legend.
options (dict[str, str] | None) – A dictionary of options to be passed to the observable.
range (tuple[float, float]) – A tuple of two float values (min, max) representing the range of the kinematic variable to be plotted on the x-axis.
resolution (int) – The number of points to be used for the evaluation of the observable. Defaults to 100.
variable (str | eos.QualifiedName) –
The name of the kinematic or parameter variable to which the x-axis will be mapped; see the complete list of observables and the complete list of parameters.

Example:

figure_args = '''
plot:
  legend: { position: 'upper center' }
  xaxis: { label: r'$q^2$',                range: [0.0, 11.6]   }
  yaxis: { label: r'$d\mathcal{B}/dq^2$', range: [0.0, 5.0e-3] }
  items:
    - { type: 'observable', observable: 'B->Dlnu::dBR/dq2', options: { 'l': 'mu' },  label: r'$\ell = \mu$',
        variable: 'q2', range: [0.02, 11.6 ], resolution: 5800
      }
    - { type: 'observable', observable: 'B->Dlnu::dBR/dq2', options: { 'l': 'tau' }, label: r'$\ell = \tau$',
        variable: 'q2', range: [3.17, 11.6 ], resolution: 421
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax, **kwargs)

Draw a curve of the observable as a function of the chosen variable.

Parameters:

ax (matplotlib.axes.Axes) – The matplotlib axes onto which the curve is drawn.
kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.plot().

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the drawing by evaluating the observable at the sample points.

Evaluates the observable on a grid of resolution points spanning range of the chosen kinematic or parameter variable and caches the results for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve relative paths. If None, a default context rooted at the current working directory is used.

class eos.figure.item.ExpressionItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, expression: str, range: tuple[float, float], resolution: int = 100)

Plots an arbitrary mathematical expression as a function of the x-axis variable.

This item type evaluates a user-supplied Python expression of the free variable x on a grid spanning range and draws the result as a curve. The expression is evaluated with Python’s eval(), with NumPy’s functions and constants (e.g. sin, exp, sqrt, pi) available by name as well as the np module itself; for example, 'exp(-x**2) * sin(2 * pi * x)'. Because the expression is evaluated as code, it should only be populated from trusted figure descriptions.

Parameters:

expression (str) – The expression to be plotted, given as a Python expression in the free variable x.
range (tuple[float, float]) – A tuple of two float values (min, max) representing the range of the x-axis variable over which the expression is evaluated.
resolution (int) – The number of points to be used for the evaluation of the expression. Defaults to 100.

Example:

figure_args = '''
plot:
  xaxis: { label: r'$x$', range: [0.0, 6.28] }
  yaxis: { label: r'$f(x)$' }
  items:
    - { type: 'expression', expression: 'sin(x)',           label: r'$\sin x$'       }
    - { type: 'expression', expression: 'exp(-x) * cos(x)', label: r'$e^{-x}\cos x$' }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax, **kwargs)

Draw a curve of the expression as a function of the x-axis variable.

Parameters:

ax (matplotlib.axes.Axes) – The matplotlib axes onto which the curve is drawn.
kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.plot().

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the drawing by evaluating the expression at the sample points.

Evaluates expression on a grid of resolution points spanning range and caches the results for draw(). The free variable x is passed as a NumPy array, so vectorized expressions are evaluated in a single pass; constant expressions are broadcast to the grid.

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency and unused.

class eos.figure.item.UncertaintyBandItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, band: set[str] | list[str] | str = <factory>, datafile: str, interpolation: str = 'linear', levels: list[float] = <factory>, range: tuple[float, float] | None=None, resolution: int = 100, variable: str | None = None, observable: str | None = None)

Plots the 68.27% (default) uncertainty band as a function of one kinematic variable or one parameter.

This routine requires EOS data file to have been produced, typically by running predict-observables task.

Parameters:

band (set[str] | list[str] | str) – A set of strings that determines which parts of the uncertainty band to draw. Can be any combination of 'area', 'outer', or 'median'. Defaults to {'area', 'outer', 'median'}. 'area' fills the area between the lower and upper bounds of the uncertainty band, 'outer' draws the outer lines of the uncertainty band, and 'median' draws the median line of the uncertainty band.
datafile (str) – The path to an existing data file of type eos.data.Prediction that contains the uncertainty estimates.
interpolation (str) – The type of interpolation to be used for the band. Can be either linear (default) or cubic.
levels (list[float]) – The credibility levels that shall be visualized in percent (optional) ordered from lowest to highest. Defaults to [68.27].
range (tuple[float, float] | None) – A tuple of two float values (min, max) representing the range of the kinematic variable to be plotted on the x-axis.
resolution (int) – The number of points to be used for the interpolation of the band. Defaults to 100.
variable (str | None) – The name of the kinematic variable that is plotted on the x-axis. Defaults to the first kinematic variable recorded in the data file.
observable (str | None) – The name of the observable that is plotted. This name can include options. Defaults to the first observable recorded in the data file.

Example:

figure_args = '''
plot:
  xaxis: { label: r'$q^2$', unit: r'$\textnormal{GeV}^2$', range: [0.0, 11.63] }
  yaxis: { label: r'$d\mathcal{B}/dq^2$',                  range: [0.0,  5e-3] }
  legend: { position: 'upper center' }
  items:
    - { type: 'uncertainty', label: r'$\ell=\mu$',
        variable: 'q2', range: [0.02, 11.63],
        datafile: './predictions-base/FF-LQCD-SSE/pred-B-to-D-mu-nu'
      }
    - { type: 'uncertainty', label: r'$\ell=\tau$',
        variable: 'q2', range: [3.17, 11.63], resolution: 1000,
        datafile: './predictions-base/FF-LQCD-SSE/pred-B-to-D-tau-nu'
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the uncertainty band on the provided axes.

Depending on the band setting, fills the area between the lower and upper bounds, draws the outer lines, and/or draws the median line.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the band is drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

The key shows those parts of the band that the band option selects, i.e. the filled area, the outer lines as the key’s boundary, and the median line across its middle. Since this item draws one nested region per requested credibility level, the filled area is subdivided into one swatch per region, each carrying the shade that region shows in the plot; see Item._legend_band.

prepare(context: AnalysisFileContext = None)

Prepare the uncertainty band for drawing.

Loads the predictive samples from the data file, selects the requested observable and kinematic variable, computes the central 68% interval at each sample point, and interpolates the lower, central, and upper bounds onto a regular grid for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.BinnedUncertaintyItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, band: set[str] | list[str] | str = <factory>, datafile: str, levels: list[float] = <factory>, range: tuple[float, float] | None=None, rescale_by_width: bool = False, variable: str)

Plots one or more uncertainty band integrated over one kinematic variable.

This routine expects the uncertainty propagation to have produced a data file.

Parameters:

band (set[str] | list[str] | str) – A set of strings that determines which parts of the uncertainty band to draw. Can be any combination of 'area', 'outer', or 'median'. Defaults to {'area', 'outer', 'median'}. 'area' fills the area between the lower and upper bounds of the uncertainty band, 'outer' draws the outer lines of the uncertainty band, and 'median' draws the median line of the uncertainty band.
datafile (str) – The path to an existing data file of type eos.data.Prediction that contains the uncertainty estimates.
levels (list[float]) – The credibility levels that shall be visualized in percent (optional) ordered from lowest to highest. Defaults to [68.27].
range (tuple[float, float] | None) – A tuple of two float values (min, max) representing the range of the kinematic variable to be plotted on the x-axis.
rescale_by_width (bool) – If set to True, the uncertainty band will be rescaled by the inverse of the width of the bin. Defaults to False.
variable (str) – The name of the kinematic variable that is plotted on the x-axis.

Example:

figure_args = '''
plot:
xaxis: { label: r'$q^2$', unit: r'$\textnormal{GeV}^2$', range: [0.0, 11.63] }
yaxis: { label: r'$d\mathcal{B}/dq^2$',                 range: [0.0,  5e-3] }
legend: { position: 'upper center' }
items:
    - { type: 'uncertainty-binned', label: r'$\ell=\mu$',
        variable: 'q2', range: [0.00, 11.63],
        datafile: './predictions-base/FF-LQCD-SSE/pred-B-to-D-mu-nu-binned'
    }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the binned uncertainty band on the provided axes.

Depending on the band setting, fills the area between the lower and upper bounds, draws the outer lines, and/or draws the median line, optionally all rescaled by the inverse of the bin width.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the band is drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

The key shows those parts of the band that the band option selects, i.e. the filled area, the outer lines as the key’s boundary, and the median line across its middle. Since this item draws one nested region per requested credibility level, the filled area is subdivided into one swatch per region, each carrying the shade that region shows in the plot; see Item._legend_band.

prepare(context: AnalysisFileContext = None)

Prepare the binned uncertainty band for drawing.

Loads the predictive samples from the data file and reads, for each bin, the lower and upper edges of the integrated kinematic variable. The samples themselves are reduced to quantiles in draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.ConstraintItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, constraints: QualifiedName | list[QualifiedName], variable: str, observable: QualifiedName | None = None, range: tuple[int, int] | None = None, rescale_by_width: bool = False)

Plots statistical constraints from the EOS library of experimental and theoretical likelihoods.

Parameters:

constraints (eos.QualifiedName | list[eos.QualifiedName]) –
The name or the list of names of the constraints that will be plotted. Must identify at least one of the constraints known to EOS; see the complete list of constraints.
variable (str) – The name of the kinematic variable to which the x axis will be mapped.
observable (eos.QualifiedName | None) –
The name of the observable whose constraints will be plotted. Must identify one of the observables known to EOS; see the complete list of observables. This is only mandatory in multivariate constraints, since these can constrain more than one observable simultaneously.
range (tuple[int, int] | None) – The interval in which the observable is plotted in the case of a multivariate constraint.
rescale_by_width (bool) – Rescales binned constraints by the inverse of the bin width. This is often required to compare theory (integrated) predictions and experimental (averaged) measurements. Defaults to false.

Example:

figure_args = '''
plot:
  xaxis: { label: r'$q^2$', unit: r'$\textnormal{GeV}^2$', range: [0.0, 11.63] }
  yaxis: { label: r'$d\mathcal{B}/dq^2$',                  range: [0.0,  5e-3] }
  legend: { position: 'lower left' }
  items:
    - { type: 'observable', observable: 'B->Dlnu::dBR/dq2;l=e,q=d', label: r'$\ell=e$',
        variable: 'q2', range: [ 0.02, 11.63 ], color: 'black'
      }
    - { type: 'constraint', 'constraints': 'B^0->D^+e^-nu::BRs@Belle:2015A',  observable: 'B->Dlnu::BR', label: r'Belle 2015 $\ell=e,\, q=d$',
        variable: 'q2', rescale_by_width: true
      }
    - { type: 'constraint', 'constraints': 'B^0->D^+mu^-nu::BRs@Belle:2015A', observable: 'B->Dlnu::BR', label: r'Belle 2015 $\ell=\mu,\, q=d$',
        variable: 'q2', rescale_by_width: true
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the constraint on the provided axes.

Renders each data point as an error bar, using horizontal error bars to indicate the bin width of binned constraints.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the constraint is drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the constraint for drawing.

Looks up and deserializes each named constraint, then extracts the central values and (a)symmetric uncertainties of the chosen observable as a function of the kinematic variable, optionally rescaling binned constraints by the inverse of the bin width. The supported constraint types are Gaussian, MultivariateGaussian(Covariance), and MultivariateGaussian.

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency; this item does not read any data files. If None, a default context is used.

class eos.figure.item.ConstraintResidueItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, constraints: QualifiedName | list[QualifiedName], variable: str, observable: QualifiedName | None = None, range: tuple[int, int] | None = None, parameters: dict[QualifiedName, float] | None = None, rescale_by_width: bool = False, mode_file: str | None = None, style: str = 'pull')

Plots the residues of a statistical constraints from the EOS library of experimental and theoretical likelihoods.

Parameters:

constraints (eos.QualifiedName | list[eos.QualifiedName]) –
The name or the list of names of the constraints that will be plotted. Must identify at least one of the constraints known to EOS; see the complete list of constraints.
variable (str) – The name of the kinematic variable to which the x axis will be mapped.
observable (eos.QualifiedName | None) –
The name of the observable whose residues will be plotted. Must identify one of the observables known to EOS; see the complete list of observables. This is only mandatory in multivariate constraints, since these can constrain more than one observable simultaneously.
range (tuple[int, int] | None) – The interval in which the observable is plotted in the case of a multivariate constraint.
parameters (dict[eos.QualifiedName, float] | None) – The set of parameters used to evaluate the constraint’s observables, given as a dictionary mapping parameter names to their values. Values given here take precedence over those loaded from mode_file.
rescale_by_width (bool) – Rescales binned constraints by the inverse of the bin width. This is often required to compare theory (integrated) predictions and experimental (averaged) measurements. Defaults to false.
mode_file (str | None) – Path to a stored eos.data.Mode, whose best-fit parameter values are used to evaluate the constraint’s observables. Values given via parameters override the corresponding entries loaded from this file.
style (str) – The drawing style, either 'pull' (default) or 'delta'. 'pull' draws each residue as a bar showing the deviation in units of standard deviations; 'delta' draws each residue as an error bar showing the absolute deviation.

Example:

figure_args = '''
plot:
  xaxis: { label: r'$q^2$', unit: r'$\textnormal{GeV}^2$', range: [0.0, 11.63] }
  yaxis: { label: r'$d\mathcal{B}/dq^2$',                  range: [0.0,  5e-3] }
  legend: { position: 'lower left' }
  items:
    - { type: 'observable', observable: 'B->Dlnu::dBR/dq2;l=e,q=d', label: r'$\ell=e$',
        variable: 'q2', range: [ 0.02, 11.63 ], color: 'black'
      }
    - { type: 'constraint-residue', 'constraints': 'B^0->D^+e^-nu::BRs@Belle:2015A',  observable: 'B->Dlnu::BR', label: r'Belle 2015 $\ell=e,\, q=d$',
        variable: 'q2', 'parameters': {"mass::e": 1.0}, rescale_by_width: true, style: 'delta'
      }
    - { type: 'constraint-residue', 'constraints': 'B^0->D^+mu^-nu::BRs@Belle:2015A', observable: 'B->Dlnu::BR', label: r'Belle 2015 $\ell=\mu,\, q=d$',
        variable: 'q2', 'parameters': {"mass::e": 1.0}, rescale_by_width: true, style: 'delta'
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the constraint residues on the provided axes.

In the default 'pull' style, draws each residue as a bar showing the deviation in units of standard deviations. In the 'delta' style, draws each residue as an error bar showing the absolute deviation, using a horizontal error bar to indicate the bin width of binned constraints.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the residues are drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the constraint residues for drawing.

Looks up and deserializes each named constraint, evaluates the corresponding observable at the given parameters, and computes the residues (measured value minus prediction) together with their uncertainties as a function of the kinematic variable, optionally rescaling binned constraints by the inverse of the bin width.

Parameters:: context (AnalysisFileContext | None) – The analysis file context, used to resolve mode_file relative to the analysis file’s base directory. If None, a default context is used.

class eos.figure.item.TwoDimensionalConstraintItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, constraint: QualifiedName, x: dict | None = None, y: dict | None = None, sigmas: list[float] = <factory>)

Plots the 2D contours of two correlated observables from a single constraint.

This item type displays the uncertainty region of a single constraint from the EOS library in the plane of two of its observables. For a bivariate (MultivariateGaussian or MultivariateGaussian(Covariance)) constraint, the chosen pair of observables is drawn as one or more covariance ellipses, one per requested confidence level. For a univariate Gaussian constraint, the single observable is drawn as a band spanning the orthogonal axis; in that case exactly one of x or y is given.

Each of x and y is a dictionary with a single mandatory key observable that names the observable mapped to that axis. For the time being, the observable is matched against the constraint by its qualified name only.

Parameters:

constraint (eos.QualifiedName) –
The name of the constraint to be plotted. Must identify one of the constraints known to EOS; see the complete list of constraints.
x (dict | None) – The specification of the observable mapped to the x axis, given as a dictionary with the mandatory key observable.
y (dict | None) – The specification of the observable mapped to the y axis, given as a dictionary with the mandatory key observable.
sigmas (list[float]) – The list of confidence levels (in multiples of the standard deviation) for which a contour is drawn. Defaults to [1.0].

Example:

figure_args = '''
plot:
  xaxis: { label: r'$|V_{ub}|$' }
  yaxis: { label: r'$|V_{cb}|$' }
  items:
    - { type: 'constraint2D', constraint: 'B->pilnu::|V_ub|@HFLAV:2024A',
        x: { observable: 'CKM::abs(V_ub)' }, y: { observable: 'CKM::abs(V_cb)' },
        sigmas: [1.0, 2.0], color: 'C0', label: 'HFLAV 2024'
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the 2D constraint on the provided axes.

Renders a covariance ellipse for each requested confidence level for a bivariate constraint, or a band spanning the orthogonal axis for a univariate Gaussian constraint.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the 2D constraint is drawn.

legend()

Return the item’s legend entry in form of its handle(s) and label(s).

Since this item draws one nested region per requested confidence level, the key is subdivided into one swatch per region, each carrying the shade that region shows in the plot; see Item._legend_composite_patch.

prepare(context: AnalysisFileContext = None)

Prepare the 2D constraint for drawing.

Looks up and deserializes the named constraint and caches the geometry of its uncertainty region: the means, standard deviations, and correlation of the chosen pair of observables for a bivariate constraint, or the mean and (a)symmetric uncertainties of the single observable for a univariate Gaussian constraint. The supported constraint types are Gaussian, MultivariateGaussian(Covariance), and MultivariateGaussian.

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency; this item does not read any data files. If None, a default context is used.

class eos.figure.item.OneDimensionalHistogramItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, bins: int = 50, datafile: str, variable: str, range: tuple[float, float] | None = None)

Plots a one-dimensional histogram.

Parameters:

bins (int) – The number of histogram bins. Defaults to 50.
datafile (str) – The path to an existing data file of type eos.data.ImportanceSamples or eos.data.Prediction that contains the samples.
variable (str) – The name of the variable that is plotted on the x-axis. Defaults to the first variable in the data file.
range (tuple[float, float] | None) – The range of the variable to be plotted on the x-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.

Example:

figure_args = '''
plot:
  xaxis: { label: '$|V_{cb}|$', range: [38.e-3, 47.e-3] }
  legend: { position: 'upper left' }
  items:
    - { type: 'histogram1D', variable: 'CKM::abs(V_cb)', datafile: './inference-base/CKM/samples', color: 'C0' }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the one-dimensional histogram on the provided axes.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the histogram is drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the histogram for drawing.

Loads the data file (of type eos.data.ImportanceSamples or eos.data.Prediction), extracts the samples of the chosen variable, and determines the histogram range if it was not provided explicitly.

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.TwoDimensionalHistogramItem(datafile: str, variables: tuple[str, str], bins: int = 50, xrange: tuple[float, float] | None = None, yrange: tuple[float, float] | None = None, *, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0)

Plots a two-dimensional histogram.

Parameters:

datafile (str) – The path to an existing data file of type eos.data.ImportanceSamples or eos.data.Prediction that contains the histogram data.
variables (tuple[str, str]) – The tuple of names of the two variables that shall be histogrammed on the x- and y-axis, respectively.
bins (int) – Number of histogram bins. Defaults to 50.
xrange (tuple[float, float] | None) – The range of the variable to be plotted on the x-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.
yrange (tuple[float, float] | None) – The range of the variable to be plotted on the y-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.

draw(ax)

Draw the two-dimensional histogram on the provided axes.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the histogram is drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

The default implementation returns an empty list, i.e. the item contributes no dedicated legend entry. Subclasses that require a custom legend handle override this

Returns:: A list of (handle, label) pairs to be added to the plot legend.
Return type:: list[tuple[matplotlib.artist.Artist, str]]

prepare(context: AnalysisFileContext = None)

Prepare the two-dimensional histogram for drawing.

Loads the data file (of type eos.data.ImportanceSamples or eos.data.Prediction), extracts the samples of the two chosen variables, and determines the x- and y-ranges if they were not provided explicitly.

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.OneDimensionalKernelDensityEstimateItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, bandwidth: float | None = None, datafile: str, level: float | None = None, range: tuple[float, float] | None = None, variable: str, xsamples: int = 100)

Plotting a one-dimensional kernel density estimate (KDE).

This item type is used to display a one-dimensional kernel density estimate (KDE) of a variable, be it a prior, a posterior, or a prediction.

Parameters:

bandwidth (float | None) – Relative bandwidth factor that multiplies the automatically determined bandwidth of the KDE. Defaults to None, which means that the default bandwidth is used.
datafile (str) – Path to the file that contains the KDE data, which must be of type eos.data.ImportanceSamples or eos.data.Prediction.
level (float | None) – Credibility level that shall be visualized in percent (optional). Defaults to None, which means that no credibility level is visualized.
range (tuple[float, float] | None) – The range of the variable to be plotted on the x-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.
variable (str) – Name of the datafile’s variable that shall be displayed.
xsamples (int) – The number of samples to be used for the x-axis. Defaults to 100.

Example:

figure_args = '''
plot:
  xaxis: { label: '$|V_{cb}|$', range: [38.e-3, 47.e-3] }
  legend: { position: 'upper left' }
  items:
    - { type: 'kde1D',       variable: 'CKM::abs(V_cb)', datafile: './inference-base/CKM/samples', color: 'C0',
        label: 'posterior'
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the kernel density estimate on the provided axes.

Plots the estimated probability density and, if level is set, shades the smallest region containing the requested credibility level.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the KDE is drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the kernel density estimate for drawing.

Loads the data file, extracts the samples of the chosen variable, fits a Gaussian KDE (optionally rescaling the automatically determined bandwidth), and evaluates the resulting probability density on a grid of xsamples points for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.TwoDimensionalKernelDensityEstimateItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, bandwidth: float | None = None, contours: set[str] = <factory>, datafile: str, levels: list[float] | None = None, variables: tuple[str, str], xrange: tuple[float, float] | None = None, yrange: tuple[float, float] | None = None)

Plots a two-dimensional kernel density estimate (KDE).

This item type is used to display a two-dimensional kernel density estimate (KDE) of two variables, be it a prior, a posterior, or a prediction.

Parameters:

bandwidth (float | None) – Relative bandwidth factor that multiplies the automatically determined bandwidth of the KDE. Defaults to None, which means that the default bandwidth is used.
contours (set[str]) – The types of contours to be drawn. Can be any combination of 'lines', 'areas', or 'labels'. Defaults to {'lines'}.
datafile (str) – Path to the file that contains the KDE data, which must be of type eos.data.ImportanceSamples or eos.data.Prediction.
levels (list[float] | None) – The credibility levels that shall be visualized in percent. Defaults to [0, 68, 95].
variables (tuple[str, str]) – The tuple of names of the two variables that shall be displayed on the x- and y-axis, respectively.
xrange (tuple[float, float] | None) – The range of the variable to be plotted on the x-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.
yrange (tuple[float, float] | None) – The range of the variable to be plotted on the y-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.

Example:

figure_args = '''
plot:
  xaxis: { label: '$|V_{cb}|$', range: [38e-3, 47e-3] }
  yaxis: { label: '$f_+(0)$',   range: [0.6, 0.75]    }
  items:
    - { type: 'kde2D', label: 'posterior', color: 'C1',
        levels: [68, 95], contours: ['lines', 'areas'], bandwidth: 3.0,
        datafile: './inference-base/CKM/samples',
        variables: ['CKM::abs(V_cb)', 'B->D::alpha^f+_0@BSZ2015']
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the two-dimensional kernel density estimate on the provided axes.

Draws contour lines at the requested credibility levels and, depending on the contours setting, optionally fills the contour areas and/or labels the contour lines.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the KDE is drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

Provides a filled rectangle handle when contour areas are drawn, and a line handle otherwise.

Returns:: A list containing a single (handle, label) pair if a label is set, otherwise empty.
Return type:: list[tuple[matplotlib.artist.Artist, str]]

prepare(context: AnalysisFileContext = None)

Prepare the two-dimensional kernel density estimate for drawing.

Loads the data file, extracts the samples of the two chosen variables, fits a Gaussian KDE (optionally rescaling the automatically determined bandwidth), and evaluates the resulting probability density on a regular grid spanning the x- and y-ranges for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.TwoDimensionalContoursItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, bins: int = 100, contours: set[str] = <factory>, datafile: str, levels: list[float] | None = None, variables: tuple[str, str], xrange: tuple[float, float] | None = None, yrange: tuple[float, float] | None = None)

Plots two-dimensional probability contours from a histogram of pre-existing samples.

This item type is used to display the credibility contours of two variables, be it a prior, a posterior, or a prediction. In contrast to TwoDimensionalKernelDensityEstimateItem, the probability density is estimated from a two-dimensional histogram of the samples rather than from a kernel density estimate, so that no smoothing is applied.

Parameters:

bins (int) – The number of histogram bins along each axis used to estimate the density. Defaults to 100.
contours (set[str]) – The types of contours to be drawn. Can be any combination of 'lines', 'areas', or 'labels'. Defaults to {'lines'}.
datafile (str) – Path to the file that contains the samples, which must be of type eos.data.ImportanceSamples or eos.data.Prediction.
levels (list[float] | None) – The credibility levels that shall be visualized in percent. Defaults to [68, 95, 99].
variables (tuple[str, str]) – The tuple of names of the two variables that shall be displayed on the x- and y-axis, respectively.
xrange (tuple[float, float] | None) – The range of the variable to be plotted on the x-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.
yrange (tuple[float, float] | None) – The range of the variable to be plotted on the y-axis, given as a tuple of two float values (min, max). Defaults to the full range of the variable in the data file.

Example:

figure_args = '''
plot:
  xaxis: { label: '$|V_{cb}|$', range: [38e-3, 47e-3] }
  yaxis: { label: '$f_+(0)$',   range: [0.6, 0.75]    }
  items:
    - { type: 'contours2D', label: 'posterior', color: 'C1',
        levels: [68, 95, 99], contours: ['lines', 'labels'],
        datafile: './inference-base/CKM/samples',
        variables: ['CKM::abs(V_cb)', 'B->D::alpha^f+_0@BSZ2015']
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the two-dimensional contours on the provided axes.

Draws contour lines at the requested credibility levels and, depending on the contours setting, optionally fills the contour areas and/or labels the contour lines.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the contours are drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

Provides a filled rectangle handle when contour areas are drawn, and a line handle otherwise.

Returns:: A list containing a single (handle, label) pair if a label is set, otherwise empty.
Return type:: list[tuple[matplotlib.artist.Artist, str]]

prepare(context: AnalysisFileContext = None)

Prepare the two-dimensional contours for drawing.

Loads the data file (of type eos.data.ImportanceSamples or eos.data.Prediction), extracts the samples of the two chosen variables, and estimates the probability density on a regular grid from a weighted two-dimensional histogram spanning the x- and y-ranges for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to datafile. If None, a default context rooted at the current working directory is used.

class eos.figure.item.BandItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, x: tuple[float, float] | None = None, y: tuple[float, float] | None = None)

Plots a shaded band.

This item type is used to display a shaded band, which can be used to represent uncertainties or confidence intervals.

Parameters:

x (tuple[float, float] | None) – The size of the band in the x direction, given as a tuple of two float values (min, max).
y (tuple[float, float] | None) – The size of the band in the y direction, given as a tuple of two float values (min, max).

Either of x or y must be specified to define the band.

Example:

figure_args = '''
plot:
  xaxis: { label: '$x$', range: [0, 10] }
  yaxis: { label: '$y$', range: [0, 10] }
  items:
    - { type: 'band', x: [2, 8], color: 'black', alpha: 0.5 }
    - { type: 'band', y: [2, 8], color: 'blue',  alpha: 0.5 }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the shaded band on the provided axes.

Draws a rectangle spanning x horizontally and y vertically. Whichever of the two is left unspecified spans the full corresponding axis range, yielding a vertical or horizontal band.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the band is drawn.

legend()

Return the item’s legend entry as a list of handle/label pairs.

Provides a filled rectangle handle matching the band’s color and transparency.

Returns:: A list containing a single (handle, label) pair if a label is set, otherwise empty.
Return type:: list[tuple[matplotlib.artist.Artist, str]]

prepare(context: AnalysisFileContext = None)

Prepare the band for drawing.

This item requires no preparation, since its extent is fully determined by the x and y attributes (or the axes limits) at draw time.

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency and unused.

class eos.figure.item.VerticalLineItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, x: float | None = None)

Plots a vertical line at a fixed position on the x axis.

This item type is used to mark a particular value on the x axis, e.g. a kinematic threshold. The line’s appearance is controlled by the inherited color, linestyle, linewidth, and alpha fields.

Parameters:: x (float) – The x-axis position of the vertical line.

Example:

plot:
  xaxis: { label: '$\sqrt{s}$ [GeV]', range: [3.73, 4.085] }
  yaxis: { label: '$\sigma$ [nb]' }
  items:
    - { type: 'vertical', x: 3.875, color: 'gray', linestyle: 'dashed', label: r'$D\bar{D}^*$ threshold' }

draw(ax): Draw the vertical line on the axes.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None): Prepare the vertical line for drawing.

class eos.figure.item.SignalPDFItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, kinematics: dict[str, float] | None = None, options: dict[str, str] | None = None, pdf: QualifiedName, parameters: dict[QualifiedName, float] | None = None, parameters_from_file: str | None = None, range: tuple[float, float], resolution: int = 100, variable: str)

Plots a single EOS signal PDF w/o uncertainties as a function of one kinematic variable

Parameters:

kinematics (dict[str,float] | None) – The set of optional kinematic variables, given as a dictionary mapping variable names to their values.
options (dict[str,str] | None) – The set of optional options for the signal PDF, given as a dictionary mapping option names to their values.
pdf (eos.QualifiedName) – The name of the signal PDF to be plotted.
parameters (dict[eos.QualifiedName,float] | None) – The set of optional parameters for the signal PDF, given as a dictionary mapping parameter names to their values.
parameters_from_file (str | None) – The path to a parameter file containing the optional parameters of the signal PDF.
range (tuple[float,float]) – The range of the variable to be plotted, given as a tuple of two float values (min, max).
resolution (int) – The number of points to be used for plotting the signal PDF. Defaults to 100.
variable (str) – The name of the kinematic variable to which the x axis will be mapped.

Example:

figure_args = '''
plot:
  xaxis: { label: r'$q^2$', unit: r'$\textnormal{GeV}^2$', range: [0.0, 11.63] }
  yaxis: { label: r'$d\mathcal{B}/dq^2$',                 range: [0.0,  5e-3] }
  legend: { position: 'lower left' }
  items:
    - { type: 'signal-pdf', pdf: 'B->Dlnu::dBR/dq2;l=e,q=d', label: 'Signal PDF',
        variable: 'q2', range: [0.02, 11.63], color: 'black', resolution: 100,
        kinematics: { q2_min: 0.02, q2_max: 11.63 },
        parameters: { B->Dlnu::dBR/dq2;l=e,q=d@BSZ2015:alpha^f+_0@BSZ2015:0.75 }
      }

draw(ax)

Draw the signal PDF on the provided axes.

Evaluates the normalized signal PDF on a grid of resolution points spanning range of the chosen kinematic variable and plots the resulting curve.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the signal PDF is drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the signal PDF for plotting.

Builds the parameters (optionally overridden from file), kinematics, and options, instantiates the signal PDF, and caches its normalization for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to parameters_from_file. If None, a default context rooted at the current working directory is used.

class eos.figure.item.ComplexPlaneItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, fixed_kinematics: dict[str, float] | None = None, fixed_parameters: dict[QualifiedName, float] | None = None, fixed_parameters_from_file: str | None = None, observable: QualifiedName, options: dict[str, str] | None = None, variables: tuple[str, str], ranges: tuple[tuple[float, float], tuple[float, float]] = ((-1.0, 1.0), (-1.0, 1.0)), resolution: int = 100)

Plots a single observable as a function on the complex plan

Parameters:

fixed_kinematics (dict[str, float] | None) – A dictionary of additional kinematic variables and the values to which they shall be fixed.
fixed_parameters (dict[eos.QualifiedName, float] | None) – A dictionary of EOS parameters and the values to which they shall be fixed.
fixed_parameters_from_file (str | None) – Path to a file containing EOS parameters to be used for the observable.
observable (eos.QualifiedName) – The name of the observable to be plotted.
options (dict[str, str] | None) – A dictionary of options to be passed to the observable.
ranges (tuple[tuple[float, float], tuple[float, float]]) – A tuple of two float values (min, max) representing the range of the kinematic variable to be plotted on the x- and y-axes.
resolution (int) – The number of points to use for the plot.
variables (tuple[str, str]) – The names of the variables to be used as x and y coordinates.

draw(ax)

Draw the observable on the provided axes as a pseudocolor plot over the complex plane.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the observable is drawn.

evaluate(c: complex)

Evaluate the observable at a complex-valued kinematic variable.

Sets the two kinematic variables given by variables to the real and imaginary parts of c, respectively, and evaluates the observable.

Parameters:: c (complex) – The complex value at which to evaluate the observable.
Returns:: The value of the observable at c.
Return type:: float

legend()

Return the item’s legend entry as a list of handle/label pairs.

The default implementation returns an empty list, i.e. the item contributes no dedicated legend entry. Subclasses that require a custom legend handle override this

Returns:: A list of (handle, label) pairs to be added to the plot legend.
Return type:: list[tuple[matplotlib.artist.Artist, str]]

prepare(context: AnalysisFileContext = None)

Prepare the observable for plotting in the complex plane.

Evaluates the observable on a regular resolution x resolution grid of complex values spanning the two ranges given by ranges and caches the results for draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path to fixed_parameters_from_file. If None, a default context rooted at the current working directory is used.

class eos.figure.item.ErrorBarsItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, marker: str = 'o', positions: list[tuple[float, float]], xerrors: list[float | tuple[float, float]] | None = None, yerrors: list[float | tuple[float, float]] | None = None)

Plots one or more error bars at specified position(s).

Parameters:

positions (list[tuple[float, float]]) – The list of (x, y) positions where the error bars will be plotted.
xerrors (list[float, tuple[float, float]]) – The list of errors to be used in the plotting. Tuples of errors are interpreted as asymmetric errors (i.e., (error_minus, error_plus)).
yerrors (list[float, tuple[float, float]]) – The list of errors to be used in the plotting. Tuples of errors are interpreted as asymmetric errors (i.e., (error_minus, error_plus)).

Example:

figure_args = '''
plot:
  xaxis: { label: '$x$', range: [0, 4] }
  yaxis: { label: '$y$', range: [1, 6] }
  items:
    - type: 'errorbars'
      positions: [[1, 2], [2, 3], [3, 5]]
      xerrors: [0.5, 0.5, 0.5]
      yerrors: [0.2, [0.2, 0.3], 0.5]
      color: 'black'
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the error bars on the provided axes.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the error bars are drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the error bars for drawing.

Converts the positions into x- and y-coordinate arrays and normalizes the xerrors and yerrors into the asymmetric (lower, upper) form expected by draw().

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency and unused.

class eos.figure.item.PointItem(*, alpha: float = 0.5, color: str = None, label: str = None, linestyle: str = 'solid', linewidth: float = 1.0, x: float, y: float, marker: str = 'x', markersize: float | None = None)

Plots a single point at a fixed position.

This item type is used to mark a single data point manually, e.g. a value taken from the literature. The point is drawn as an open (unfilled) marker whose edge uses the inherited color and alpha fields. To draw several points at once, or points with error bars, use an ErrorBarsItem instead.

Parameters:

x (float) – The x-axis position of the point.
y (float) – The y-axis position of the point.
marker (str) – The marker style, given as a valid matplotlib marker. Defaults to 'x'.
markersize (float | None) – The marker size in points. Defaults to None, i.e. matplotlib’s default size.

Example:

figure_args = '''
plot:
  xaxis: { label: r'$q^2$', range: [0.0, 1.0] }
  yaxis: { label: r'$f_+(q^2)$' }
  items:
    - { type: 'point', x: 0.0, y: 0.261, marker: 'o', markersize: 12, color: 'C0',
        label: r'LCSR (Bharucha 2012)'
      }
'''
figure = eos.figure.FigureFactory.from_yaml(figure_args)
figure.draw()

draw(ax)

Draw the point on the provided axes.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the point is drawn.

legend(): Return the item’s legend entry in form of its handle(s) and label(s).

prepare(context: AnalysisFileContext = None)

Prepare the point for drawing.

Parameters:: context (AnalysisFileContext | None) – The analysis file context. Accepted for interface consistency and unused.

Utility Classes

class eos.analysis_file_context.AnalysisFileContext(*, base_directory: str = './')

Auxiliary class used to resolve paths relative to an analysis file’s base directory.

Instances are passed to consumers of an analysis file (e.g. figures and tasks) so that relative data paths can be resolved against a common base directory.

Parameters:: base_directory (str) – The base directory against which relative paths are resolved. Defaults to the current working directory.

base_directory: str = './': The base directory against which relative paths are resolved.

data_path(relative_path: str)

Resolve a path relative to base_directory into an absolute path.

Parameters:: relative_path (str) – A path relative to the base directory.
Returns:: The corresponding absolute path.
Return type:: str

class eos.diagnostic.Diagnostic(path: tuple, severity: eos.diagnostic.Severity, message: str, line: int | None = None)

class eos.diagnostic.Severity(*values)

class eos.figure.DataFile(*, path: str, label: str, color: str = None, kde: bool = False)

Collects the relevant information to load a data file, to extract data, variables, and labels from it.

Parameters:

path (str) – Path to the data file (either in eos.Prediction or eos.ImportanceSample format) that will be used.
label (str) – Title to appear in a figure’s legend in association with this data file.
color (str (optional)) – Color to be used in the plot.
kde (bool) – A boolean determining whether to use kernel density estimates (KDE) to visualize the distributions. Defaults to False, in which case histograms are used.

property empirical_range

An empirically determined plotting range for each variable in the data file.

For each variable, the range is centered on the weighted median and extends to 1.3 times the distance from the median to the weighted 1% and 99% quantiles, respectively.

Returns:: A tuple (min, max) of arrays holding the lower and upper bound for each variable.
Return type:: tuple[numpy.ndarray, numpy.ndarray]

labels(variables)

Return LaTeX labels for the given variables.

For parameter samples, the labels are taken from the corresponding EOS parameters; for predictions, they are taken from the corresponding EOS observables, falling back to the parameter label if the name does not identify an observable.

Parameters:: variables (list[str]) – The names of the variables for which labels are requested.
Returns:: The LaTeX label for each requested variable, in the same order.
Return type:: list[str]
Raises:: NotImplementedError – If the data file has an unsupported format.

prepare(context: AnalysisFileContext = None)

Load the underlying data file and cache it for subsequent access.

Resolves path against the given context, opens the file as either eos.data.ImportanceSamples (a file named samples) or eos.data.Prediction (a file whose name starts with pred-), and records the available variable names. The result is cached, so repeated calls return the already-loaded data file without reloading.

Parameters:

context (AnalysisFileContext | None) – The analysis file context used to resolve the relative path. If None, a default context rooted at the current working directory is used.

Returns:

The loaded data file.

Return type:

eos.data.ImportanceSamples | eos.data.Prediction

Raises:

ValueError – If the data file does not exist.
NotImplementedError – If the data file has an unsupported format.

property variables

The names of the variables contained in the data file.

Returns:: The list of variable names, in the order in which they appear in the data file.
Return type:: list[str]

class eos.figure.Watermark(*, position: str = 'upper right', preliminary: bool = False, xy: tuple[float, float] | None = None, offset: float | tuple[float, float] | None = None)

Inserts an EOS watermark into a figure.

Parameters:

position (str) – The position of the watermark as '<vpos> <hpos>'. The vertical position can be any of 'right', 'left' and 'center'. The horizontal position can be any of 'upper', 'lower', and 'center'.
preliminary (bool) – If true, marks the figure as a preliminary version.
xy (tuple[float, float] | None) – An explicit anchor point in axes fraction. If given, it overrides the coordinates derived from position, while the text alignment is still taken from position. Defaults to None (use the position preset).
offset (float | tuple[float, float] | None) – The offset from the edges for the position presets, given as a single fraction (used for both axes) or as a (xdelta, ydelta) pair. Defaults to None (i.e. 0.04 on both axes).

draw(ax)

Draw the EOS watermark on the provided axes.

Renders the EOS version (or the word Preliminary) as a semi-transparent label at the configured corner of the axes.

Parameters:: ax (matplotlib.axes.Axes) – The matplotlib axes onto which the watermark is drawn.

Analysis File Description Classes

The classes in the eos.analysis_file_description module describe the individual elements of an analysis file. Each class corresponds to a key, or a type of entry, of the analysis file format; its fields correspond to the keys of the respective YAML object.

The metadata of an analysis is described by:

class eos.analysis_file_description.MetadataDescription(title: str = '', id: str = '', authors: list[MetadataAuthorDescription] = <factory>, description: str = '')

Describes the metadata of an analysis file.

Parameters:

title (str) – A human-readable title for the analysis. Optional.
description (str) – A human-readable description of the analysis. Optional.
id (str) – A unique identifier for the analysis. Optional.
authors (list[MetadataAuthorDescription]) – The list of authors of the analysis. Optional.

static from_dict(**kwargs)

Create a MetadataDescription from its keyword description.

Deserializes the nested authors list into MetadataAuthorDescription instances.

Returns:: The instantiated metadata description.
Return type:: MetadataDescription

class eos.analysis_file_description.MetadataAuthorDescription(name: str, affiliation: str = '', email: str = '')

Describes a single author in an analysis file’s metadata.

Parameters:

name (str) – The author’s name.
affiliation (str) – The author’s affiliation. Optional.
email (str) – The author’s email address. Optional.

A named prior, and the prior densities it comprises, are described by:

class eos.analysis_file_description.PriorDescription

Polymorphic description of a single prior on one or more parameters.

This is a dispatcher rather than a concrete description: from_dict() selects the concrete type from the type key. The recognized types are constraint (ConstraintPriorDescription), uniform/flat (UniformPriorDescription), scale (ScalePriorDescription), gauss/gaussian (GaussianPriorDescription, or CurtailedGaussianDescription if min/max are given), poisson (PoissonPriorDescription), and transform (TransformPriorDescription).

For backwards compatibility, a description that omits the type key but provides a constraint key is still interpreted as a ConstraintPriorDescription; this form is deprecated.

static from_dict(**kwargs)

Create the concrete prior description matching the given keyword description.

Returns:: An instance of the concrete PriorDescription subtype selected from type.

class eos.analysis_file_description.PriorComponent(name: str, descriptions: list)

Describes a single named prior, i.e. one entry of an analysis file’s priors list.

A named prior bundles one or more prior descriptions: a single description for a univariate prior, or several for an (uncorrelated) multivariate prior.

Parameters:

name (str) – The unique name of the prior, by which posteriors refer to it.
descriptions (list[PriorDescription]) – The list of prior descriptions that make up this prior.

classmethod from_dict(**kwargs)

Create a PriorComponent from its keyword description.

Deserializes each entry of descriptions via PriorDescription.from_dict(). The deprecated parameters key is still accepted as a fall-back alias for descriptions.

Returns:: The instantiated prior component.
Return type:: PriorComponent

class eos.analysis_file_description.ConstraintPriorDescription(constraint: str)

Describes a (possibly correlated, multivariate) prior taken from a built-in EOS constraint.

Parameters:: constraint (str) – The qualified name of the EOS constraint used as the prior.

class eos.analysis_file_description.UniformPriorDescription(parameter: str, min: float, max: float)

Describes a uniform (flat) prior on a single parameter.

Parameters:

parameter (str) – The qualified name of the parameter.
min (float) – The lower bound of the prior’s support.
max (float) – The upper bound of the prior’s support.

class eos.analysis_file_description.ScalePriorDescription(parameter: str, min: float, max: float, mu_0: float, lambda_scale: float)

Describes a prior on a renormalization scale parameter.

Parameters:

parameter (str) – The qualified name of the scale parameter.
min (float) – The lower bound of the scale variation.
max (float) – The upper bound of the scale variation.
mu_0 (float) – The default (central) scale.
lambda_scale (float) – The multiplicative factor that controls the width of the log-uniform variation.

class eos.analysis_file_description.GaussianPriorDescription(parameter: str, central: float, sigma: float)

Describes a Gaussian prior on a single parameter.

Parameters:

parameter (str) – The qualified name of the parameter.
central (float) – The central value (mean) of the Gaussian.
sigma (float) – The standard deviation of the Gaussian.

class eos.analysis_file_description.CurtailedGaussianDescription(parameter: str, central: float, sigma: float, min: float, max: float)

Describes a Gaussian prior truncated to a finite interval (type: gauss with min/max).

Deprecated since version 1.0.21: The curtailed Gaussian prior description is deprecated and will be removed in a future version of EOS; use type: gaussian without the min/max keys instead.

Parameters:

parameter (str) – The qualified name of the parameter.
central (float) – The central value (mean) of the Gaussian.
sigma (float) – The standard deviation of the Gaussian.
min (float) – The lower bound to which the prior is truncated.
max (float) – The upper bound to which the prior is truncated.

class eos.analysis_file_description.PoissonPriorDescription(parameter: str, k: float)

Describes a Poisson prior on a single parameter.

Parameters:

parameter (str) – The qualified name of the parameter.
k (float) – The number of observed counts that parametrizes the Poisson distribution.

class eos.analysis_file_description.TransformPriorDescription(parameters: list[str], shift: list[float], transform: list[list[float]], min: list[float], max: list[float])

Describes a prior on a linear transformation of several parameters.

Parameters:

parameters (list[str]) – The qualified names of the parameters that enter the transformation.
shift (list[float]) – The constant shift applied to the parameters before the transformation.
transform (list[list[float]]) – The transformation matrix applied to the (shifted) parameters.
min (list[float]) – The lower bounds of the transformed parameters’ support.
max (list[float]) – The upper bounds of the transformed parameters’ support.

A named likelihood, and the constraints it comprises, are described by:

class eos.analysis_file_description.LikelihoodComponent(name: str, constraints: list = <factory>, manual_constraints: list = <factory>, pyhf: PyHFConstraintDescription | None = None)

Describes a single named likelihood, i.e. one entry of an analysis file’s likelihoods list.

A named likelihood may combine any number of built-in constraints, inline (manual) constraints, and pyhf-based contributions; at least one of the three must be present.

Parameters:

name (str) – The unique name of the likelihood, by which posteriors refer to it.
constraints (list[ConstraintLikelihoodDescription]) – The built-in EOS constraints contributing to the likelihood. Optional.
manual_constraints (list[ManualConstraintDescription]) – The inline constraint definitions contributing to the likelihood. Optional.
pyhf (PyHFConstraintDescription | None) – The pyhf-based contribution to the likelihood, or None if there is none. Optional.

classmethod from_dict(**kwargs)

Create a LikelihoodComponent from its keyword description.

Deserializes the constraints, manual_constraints, and pyhf entries into their respective description types.

Returns:: The instantiated likelihood component.
Return type:: LikelihoodComponent

class eos.analysis_file_description.ConstraintLikelihoodDescription(constraint: QualifiedName)

Describes a likelihood contribution taken from a built-in EOS constraint.

Parameters:: constraint (eos.QualifiedName) – The qualified name of the EOS constraint.

class eos.analysis_file_description.ManualConstraintDescription(name: QualifiedName, info: dict)

Describes a likelihood contribution from a constraint defined inline in the analysis file.

Parameters:

name (eos.QualifiedName) – The qualified name under which the manual constraint is registered.
info (dict) – The constraint definition, in the same format as a built-in EOS constraint entry.

class eos.analysis_file_description.PyHFConstraintDescription(file: str, parameter_map: dict = <factory>)

Describes a likelihood contribution imported from a pyhf workspace.

Parameters:

file (str) – The path to the JSON file specifying the pyhf workspace.
parameter_map (dict) – An optional mapping from pyhf parameter names to EOS observables or parameters; see eos.PyhfLogLikelihood.

A named posterior is described by:

class eos.analysis_file_description.PosteriorDescription(name: str, prior: list, likelihood: list, global_options: dict = <factory>, fixed_parameters: dict = <factory>)

Describes a single named posterior, i.e. one entry of an analysis file’s posteriors list.

A posterior combines one or more named priors with one or more named likelihoods, optionally fixing parameters and setting global options for all of its theory predictions.

Parameters:

name (str) – The unique name of the posterior.
prior (list[str]) – The names of the priors that make up the posterior.
likelihood (list[str]) – The names of the likelihoods that make up the posterior.
global_options (dict) – Options forwarded to all theory predictions of the posterior. Optional.
fixed_parameters (dict) – Parameters to fix, given as a mapping from qualified name to value. Optional.

A custom observable is described by:

class eos.analysis_file_description.ObservableComponent(name: str, latex: str, unit: str, expression: str, options: dict = <factory>)

Describes a custom observable defined in an analysis file’s observables section.

Parameters:

name (str) – The qualified name under which the new observable is registered.
latex (str) – The LaTeX representation of the observable, used in figures and tables.
unit (str) – The unit of the observable.
expression (str) – The EOS expression that defines the observable.
options (dict) – Default options applied when evaluating the observable. Optional.

A custom parameter is described by:

class eos.analysis_file_description.ParameterComponent(name: str, latex: str, unit: str, central: float, min: float, max: float, alias_of: list = <factory>)

Describes a custom parameter defined in an analysis file’s parameters section.

Parameters:

name (str) – The new EOS qualified name of the parameter.
latex (str) – The LaTeX representation of the parameter, used in figures and tables.
unit (str) – The unit of the parameter.
central (float) – The default (central) value of the parameter.
min (float) – The lower end of the parameter’s allowed range.
max (float) – The upper end of the parameter’s allowed range.
alias_of (list[str]) – The qualified names of existing parameters for which this parameter is an alias. Optional.

A prediction, and the observables it comprises, are described by:

class eos.analysis_file_description.PredictionDescription(name: str, observables: list, global_options: dict = <factory>, fixed_parameters: dict = <factory>)

Describes a single named prediction, i.e. one entry of an analysis file’s predictions list.

A prediction lists the observables to be evaluated on previously obtained importance samples, optionally fixing parameters and setting global options.

Parameters:

name (str) – The unique name of the prediction.
observables (list[PredictionObservableComponent]) – The observables to be predicted.
global_options (dict) – Options forwarded to all observables of the prediction. Optional.
fixed_parameters (dict) – Parameters to fix, given as a mapping from qualified name to value. Optional.

classmethod from_dict(**kwargs)

Create a PredictionDescription from its keyword description.

Deserializes each entry of observables into a PredictionObservableComponent.

Returns:: The instantiated prediction description.
Return type:: PredictionDescription

class eos.analysis_file_description.PredictionObservableComponent(name: str, kinematics: dict = <factory>, options: dict = <factory>)

Describes a single observable to be predicted, i.e. one entry of a prediction’s observables list.

Parameters:

name (str) – The qualified name of the observable to predict.
kinematics (dict) – The kinematic configuration(s) at which to evaluate the observable. Optional.
options (dict) – Options applied when evaluating the observable. Optional.

A step, and the tasks it comprises, are described by:

class eos.analysis_file_description.StepComponent(title: str, id: str, tasks: list, depends_on: list = <factory>, default_arguments: defaultdict = <factory>)

Describes a single step of a reproducible analysis, i.e. one entry of an analysis file’s steps list.

A step bundles one or more task invocations, may declare dependencies on other steps, and may supply default arguments shared by its tasks.

Parameters:

title (str) – A human-readable title for the step.
id (str) – The unique identifier of the step. Must not contain / or whitespace.
tasks (list[TaskComponent]) – The tasks executed by the step.
depends_on (list[str]) – The ids of steps that must complete before this step runs. Optional.
default_arguments (dict) – Default arguments per task name, applied to this step’s task invocations. Optional.

classmethod from_dict(**kwargs)

Create a StepComponent from its keyword description.

Deserializes each entry of tasks into a TaskComponent and normalizes the default_arguments keys against the per-task command-line argument map.

Returns:: The instantiated step component.
Return type:: StepComponent

class eos.analysis_file_description.TaskComponent(task: str, arguments: dict = <factory>)

Describes a single task invocation within a step, i.e. one entry of a step’s tasks list.

Parameters:

task (str) – The name of the task to run; must be a registered EOS task.
arguments (dict) – The arguments passed to the task, given as a mapping from argument name to value. Optional.

A named mask, and the entries it comprises, are described by:

class eos.analysis_file_description.MaskDescription

Polymorphic description of a single entry in a mask’s description list.

This is a dispatcher rather than a concrete description: from_dict() inspects the keys of an entry and returns the matching concrete type. An entry containing an expression key yields a MaskExpressionComponent, one containing a mask_name key yields a MaskNamedComponent, and otherwise the entry yields a MaskObservableComponent.

static from_dict(**kwargs)

Create the concrete mask-description entry matching the given keyword description.

Returns:: An instance of the concrete MaskDescription subtype selected from the keys.
Return type:: MaskExpressionComponent | MaskNamedComponent | MaskObservableComponent

class eos.analysis_file_description.MaskComponent(name: str, description: list, logical_combination: str = 'and')

Describes a single named mask, i.e. one entry of an analysis file’s masks list.

A mask selects a subset of posterior samples by combining one or more (pseudo-)observables and/or other masks, keeping samples for which all (and) or any (or) of them evaluate positive.

Parameters:

name (str) – The unique name of the mask.
description (list[MaskDescription]) – The entries that make up the mask.
logical_combination (str) – How the entries are combined, either 'and' or 'or'. Defaults to 'and'.

classmethod from_dict(**kwargs)

Create a MaskComponent from its keyword description.

Deserializes each entry of description via MaskDescription.from_dict().

Returns:: The instantiated mask component.
Return type:: MaskComponent

class eos.analysis_file_description.MaskObservableComponent(name: str)

Describes a mask entry given by the name of an existing EOS observable.

Parameters:: name (str) – The qualified name of the observable used for masking.

class eos.analysis_file_description.MaskExpressionComponent(expression: str, name: str)

Describes a mask entry given by a new observable defined through an expression.

Parameters:

expression (str) – The EOS expression that defines the (pseudo-)observable used for masking.
name (str) – The qualified name under which the new observable is registered.

class eos.analysis_file_description.MaskNamedComponent(mask_name: str)

Describes a mask entry that refers to another, previously defined mask.

Parameters:: mask_name (str) – The name of the previously defined mask to include.