Python API

Basic Classes

EOS provides its basic functionality via the main eos module.

class eos.Constraints(prefix=None, name=None, suffix=None)
insert((_Constraints)arg1, (QualifiedName)arg2, (str)arg3) → 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.LogLikelihood

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

add((LogLikelihood)arg1, (Constraint)arg2) → None

add( (LogLikelihood)arg1, (LogLikelihoodBlock)arg2) -> None

evaluate((LogLikelihood)arg1) → float
observable_cache((LogLikelihood)arg1) → ObservableCache
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.Gaussian(), and LogPrior.Scale().

static CurtailedGauss((_Parameters)arg1, (str)parameters, (float)name, (float)range, (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 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, strictly positive) – The standard deviation of the prior.

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, strictly positive) – The mode of the prior.

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 / lambda, mu_0 * lambda]. 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, strictly positive) – The central value of the parameter.

  • lambda (float, strictly positive) – The scale factor.

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 (vector) – The shift vector to the original set of parameters

:param transform; The matrix that transforms the original set of parameters :type transform: matrix :param min: The vector of minimum values that the parameters are allowed to take. :type min: vector :param max: The vector of maximum values that the parameters are allowed to take. :type max: vector

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)arg1) → None :

Returns the cumulative probabilities \(p\) assigned to each parameter via its Parameter.evaluate_generator() method.

evaluate((LogPrior)arg1) → float :

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

sample((LogPrior)arg1) → 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
class eos.LogPosterior

Represents a Bayesian posterior on the log scale.

add((LogPosterior)arg1, (LogPrior)arg2, (bool)arg3) → bool :

Adds a new prior object to the posterior.

evaluate((LogPosterior)arg1) → float :

Returns the posterior probability density.

log_likelihood((LogPosterior)arg1) → LogLikelihood :

Returns the likelihood object used as part of the posterior.

log_priors((LogPosterior)arg1) → object :

Returns a range of LogPrior objects used as part of the posterior.

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)arg1) → Kinematics :

Returns the set of kinematic variables bound to this observable.

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

Makes a new Observable object.

Parameters:
Returns:

The new observable object.

Return type:

eos.Observable

name((Observable)arg1) → QualifiedName :

Returns the name of the observable.

options((Observable)arg1) → Options :

Returns the set of options used when creating the observable.

parameters((Observable)arg1) → _Parameters :

Returns the set of parameters bound to this observable.

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)arg1, (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 (std::string) – 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 (std::string) – The expression to be parsed.

sections((_Observables)arg1) → object
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)arg1, (qnpOptionKey)arg2, (qnpOptionValue)arg3) → None
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)arg1) → float
evaluate((Parameter)arg1) → float :

Return the current value of a parameter.

evaluate_generator((Parameter)arg1) → float :

Return the current generator value of a parameter.

latex((Parameter)arg1) → str :

Returns the LaTeX representation of the parameter.

max((Parameter)arg1) → float
min((Parameter)arg1) → float
name((Parameter)arg1) → str :

Returns the name of the parameter.

set((Parameter)arg1, (float)arg2) → None :

Set the value of a parameter.

Parameters:

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

set_generator((Parameter)arg1, (float)arg2) → None :

Set the generator value of a parameter.

Parameters:

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

set_max((Parameter)arg1, (float)arg2) → None
set_min((Parameter)arg1, (float)arg2) → None
unit((Parameter)arg1) → 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.

See also the complete list of parameters.

static Defaults() → _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)arg1, (int)arg2) → 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)arg1, (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 (iterable of str (optional)) – Names of the parameters that shall be converted.

has((_Parameters)arg1, (QualifiedName)arg2) → bool
override_from_file((_Parameters)arg1, (str)arg2) → None
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 – The name of the parameter to be redirected.

  • id (eos.Parameter::Id) – The id of the parameter to which the name shall be redirected.

sections((_Parameters)arg1) → object
set((_Parameters)arg1, (QualifiedName)arg2, (float)arg3) → 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 – 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)arg1) → str :

Returns the full name, i.e., the concatenation of all parts.

name_part((QualifiedName)arg1) → qnpName :

Returns the name part of the name, i.e., the part following the ‘::’ and preceeding any optional ‘@’.

options_part((QualifiedName)arg1) → Options :

Returns the optional options part of the name, i.e., the part following the optional ‘;’.

prefix_part((QualifiedName)arg1) → qnpPrefix :

Returns the prefix part of the name, i.e., the part preceeding the ‘::’.

suffix_part((QualifiedName)arg1) → qnpSuffix :

Returns the optional suffix part of the name, i.e., the part following the optional ‘@’.

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)arg1) → Kinematics :

Returns the set of kinematic variables bound to this PDF.

log_pdf(x)

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

Parameters:

x (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:
Returns:

The new PDF object.

Return type:

eos.SignalPDF

name((_SignalPDF)arg1) → QualifiedName :

Returns the name of the PDF.

normalization((_SignalPDF)arg1) → 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.

options((_SignalPDF)arg1) → Options :

Returns the set of options used when creating the PDF.

parameters((_SignalPDF)arg1) → _Parameters :

Returns the set of parameters bound to this PDF.

sample_mcmc(N, stride, pre_N, preruns, cov_scale=0.1, start_point=None, rng=<module 'numpy.random.mtrand' from '/opt/venv/lib/python3.14/site-packages/numpy/random/mtrand.cpython-314-x86_64-linux-gnu.so'>)

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 (list-like, 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.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.

sections((_SignalPDFs)arg1) → object
class eos.Unit

Represents the unit of the observables.

Thirteen possible entries are currently implemented in EOS:

  • Undefined

  • None

  • GeV

  • GeV2

  • GeV3

  • InverseGeV

  • InverseGeV2

  • InverseGeV4

  • Second

  • InverseSecond

  • InversePicoSecond

  • GeVSecond

  • Femtometer2

static Femtometer2() → Unit
static GeV() → Unit
static GeV2() → Unit
static GeV3() → Unit
static GeVSecond() → Unit
static InverseGeV() → Unit
static InverseGeV2() → Unit
static InverseGeV4() → Unit
static InversePicoSecond() → Unit
static InverseSecond() → Unit
static Second() → Unit
static Undefined() → Unit
static Unity() → Unit
latex((Unit)arg1) → str

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 (iterable) – The priors for this analysis as a list of prior descriptions. See below for what consitutes a valid prior description.

  • likelihood (iterable) – 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 (list or iterable 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 (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 (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 (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=<module 'numpy.random.mtrand' from '/opt/venv/lib/python3.14/site-packages/numpy/random/mtrand.cpython-314-x86_64-linux-gnu.so'>, **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 (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=<module 'numpy.random.mtrand' from '/opt/venv/lib/python3.14/site-packages/numpy/random/mtrand.cpython-314-x86_64-linux-gnu.so'>, 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 (list-like, optional) – Observables for which posterior-predictive samples shall be obtained.

  • start_point (list-like, 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, 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.

  • print_function (callable, optional) – The function used to print progress messages. Defaults to using a dynesty-based function.

  • seed ({None, int, array_like[ints], 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=<module 'numpy.random.mtrand' from '/opt/venv/lib/python3.14/site-packages/numpy/random/mtrand.cpython-314-x86_64-linux-gnu.so'>, 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=<module 'numpy.random.mtrand' from '/opt/venv/lib/python3.14/site-packages/numpy/random/mtrand.cpython-314-x86_64-linux-gnu.so'>)

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.

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)

Create an eos.Analysis object for the named posterior.

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()

Validates the analysis file.

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 (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)arg1) → float :

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

total_degrees_of_freedom((GoodnessOfFit)arg1) → int :

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

class eos.ObservableCache

Provides a cache for the efficient evaluation of observables.

add((ObservableCache)arg1, (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:

int

parameters((ObservableCache)arg1) → _Parameters :

Retrieve the set of parameters bound to this cache.

update((ObservableCache)arg1) → None :

Update the cache for the current parameter point.

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.corner_plot(analysis_file: str, posterior: str, base_directory: str = './', format: str = 'pdf', distribution: str = 'posterior', begin: int = 0, end: int = None, mask_name=None)

Generates a corner plot of the 1-D and 2-D marginalized posteriors.

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

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.

  • format (str or list of str, optional) – The file extension of the data files. Can also be a list of file extensions.

  • distribution (str, optional) – The distribution to plot. Can be either ‘posterior’ or the name of a prediction.

  • begin (int, optional) – The index of the first parameter to plot. Defaults to 0.

  • end (int or NoneType, optional) – The index beyond the last parameter to plot. Defaults to None.

  • mask_name (str, optional) – The label of the mask to apply to the observables. Defaults to None.

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/.

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 data 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 > 1.0, optional) – The R value threshold. 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 >= 1, optional) – The number of mixture components per cluster. 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 (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.

  • convert_to_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 >= 0) – The index assigned to the Markov chain. 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 (list-like, 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, 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) – Relative tolerance for the remaining evidence. Defaults to 5%.

  • 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.

  • 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 > 0, optional) – The number of samples to be used in each adaptation step. These samples will be discarded. Defaults to 500.

  • steps (int > 0, optional) – The number of adaptation steps, which are used to adapt the PMC proposal to the posterior. Defaults to 10.

  • final_N (int > 0, optional) – The number of samples to be stored in the output file. Defaults to 5000,

  • perplexity_threshold (0.0 < float <= 1.0, optional) – The threshold for the perplexity in the last step after which further adaptation steps are to be skipped. Defaults to 1.0.

  • weight_threshold (0.0 < float <= 1.0, optional.) – Mixture components with a weight smaller than this threshold are pruned.

  • sigma_test_stat (list or 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 > 0, optional, advanced) – Maximum number of update of the PMC, changing this value may make the update unstable.

  • pmc_rel_tol (float > 0.0, optional, 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 (float > 0.0, optional, 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 (int >= 0, 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”. 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)

Validates the analysis file by checking that all posteriors and all prediction sets can be created.

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.

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.

  • samples – The samples in parameter space as a 2D array of shape (N, P).

  • 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 (list or iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (P, ).

  • samples (2D numpy array) – Samples as a 2D array of shape (N, P).

  • weights (1D numpy array, optional) – Weights on a linear scale as a 1D array of shape (N, ).

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.

  • samples – The samples in parameter space as a 2D array of shape (N, P).

  • 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 (list or iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (N, ).

  • samples (2D numpy array) – Samples in parameter space as a 2D array of shape (N, P).

  • usamples (2D numpy array) – Samples in u space as a 2D array of shape (N, P).

  • weights (1D numpy array, optional) – Weights on a linear scale as a 1D array of shape (N, ).

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, optionally together with the qualified names of the varied parameters and 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'.

  • components – The descriptions of the mixture components.

  • weights – The component weights of the mixture.

  • varied_parameters – The qualified names of the varied parameters, or None if not stored.

  • 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 (iterable of pypmc.density.MixtureDensity) – List of mixture densities.

static create(path, density, varied_parameters=None, 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.

  • varied_parameters (numpy.array of str, optional) – List of the qualified names of varied parameters.

  • sigma_test_stat (list or iterable) – (optional) If provided, the inverse CDF of -2*log(PDF) will be evaluated, using the provided values as the respective significance.

  • samples (2D numpy array, optional) – Samples as a 2D array of shape (N, P). Needed to generate the test statistic.

  • weights (1D numpy array, 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.

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().

Variables:

  • type – The type identifier of the data object, always 'Mode'.

  • 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 – The local p-values at the mode.

  • 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, local_pvalues, global_chi2, dof)

Write a new Mode object to disk.

Parameters:

  • path (str) – Path to the storage location, which will be created as a directory.

  • parameters (list or iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (N, ).

  • mode (numpy.ndarray) – The mode to be stored.

  • pvalue (float) – The p-value of the mode.

  • local_pvalues (dict) – The local p-values of the mode.

  • global_chi2 (float) – The global chi2 value of the mode.

  • dof (float) – The degrees of freedom of the mode.

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'.

  • varied_parameters – The descriptions (name, min, max) of the varied parameters.

  • 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.

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 iterable of eos.Parameter) – Parameter descriptions as a 1D array of shape (P, ).

  • sigma_test_stat (list or iterable) – (optional) If provided, the inverse CDF of -2*log(PDF) will be evaluated, using the provided values as the respective significance.

  • samples (2D numpy array, optional) – Samples as a 2D array of shape (N, P). Needed to generate the test statistic.

  • weights (1D numpy array, 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.

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().

Variables:

  • type – The type identifier of the data object, always 'Prediction'.

  • varied_parameters – The descriptions (name, kinematics, options) of the predicted observables.

  • lookup_table – A mapping from each observable’s qualified name (including options and kinematics) to its column index in samples.

  • samples – The predictive samples as a 2D array of shape (N, O).

  • 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 (list or iterable of eos.Observable) – Observables as a 1D array of shape (O, ).

  • samples (2D numpy array) – Samples as a 2D array of shape (N, O).

  • weights (1D numpy array) – Weights on a linear scale as a 1D array of shape (N, ).

Plotting

EOS provides a plotting framework based on Matplotlib. Plots can readily be created from a Python script, from within a Jupyter notebook, or in the command line using the eos-plot script. For all of these cases a description of the plot is required in the format described below. For the command-line script eos-plot, the Python dictionary describing the plots must be provided as a YAML file.

Note

Import eos.plot before you do something like import matplotlib.pyplot as plt, because the eos.plot module sets its default plot style and a 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.

class eos.plot.Plotter(description, output=None)

Produces publication-quality plots

Plots can contain EOS observables, EOS constraints, and Analysis results. See Plot description format for documentation of how to create a plot.

Parameters:

  • description (dict) – Description of the plot and its contents, see Plot description format.

  • output (string, optional) – Name of the output file. The file format is automatically determined based on the file’s extension.

class Band(plotter, item)

Plots a shaded band

class BasePlot(plotter, item)

Base class for any of the plots supported by Plotter

class Constraint(plotter, item)

Plots constraints from the EOS library of experimental and theoretical likelihoods

class Constraint2D(plotter, item)

Plot 2D contours for two correlated observables from a single constraint

class ConstraintOverview(plotter, item)

Plots overview of several constraints from the EOS library of experimental and theoretical likelihoods

class Contours2D(plotter, item)

Plots 2D contours of a pair of parameters based on pre-existing random samples

class ErrorBar(plotter, item)

Plots a single errors bar

class Expression(plotter, item)

Plots a given expression

class ExternalLikelihood2D(plotter, item)

Plots contours of a user-provided function

class Graph(plotter, item)

Plots the graph of a function

class Histogram1D(plotter, item)

Plots a 1D histogram of pre-existing random samples

class Histogram2D(plotter, item)

Plots a 2D histogram of pre-existing random samples

class KernelDensityEstimate1D(plotter, item)

Plots a 1D Kernel Density Estimate (KDE) of pre-existing random samples

class KernelDensityEstimate2D(plotter, item)

Plots contours of a 2D Kernel Density Estimate (KDE) of pre-existing random samples

class Observable(plotter, item)

Plots a single EOS observable w/o uncertainties as a function of one kinematic variable or one parameter

class Point(plotter, item)

Plots a single point

class SignalPDF(plotter, item)

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

class Uncertainty(plotter, item)

Plots an uncertainty band as a function of one kinematic variable

This routine expects the uncertainty propagation to have produced an EOS data file

class UncertaintyBinned(plotter, item)

Plots one or more uncertainty band integrated over one kinematic variable

This routine expects the uncertainty propagation to have produced an data file

class UncertaintyOverview(plotter, item)

Plots an overview of uncertainty estimates

This routine expects the uncertainty propagation to have produced an HDF5 file

class Watermark(plotter, item)

Inserts an EOS watermark into the plots

property next_color

Returns the next available color

property next_z_order

Returns the next available z-order value, incremented for each plot w/o pre-defined z-order value

plot()

Produces the plot

Returns:

  • fig (matplotlib.figure.Figure) - the created figure

  • ax (matplotlib.axes.Axes) - the created axes

plot_contents()

Plots the contents specified in the instructions provided to Plotter

setup_plot()

Setting up the plot based on the provided instruction

Plot description format

The input must be formatted as a dictionary containing the keys plot and contents. The plot key must be mapped to a dictionary; it describes the layout of the plot, including axis labels, positioning of the key, and similar settings. The contents key must be mapped to a list; it describes the contents of the plot, expressed in terms of independent plot items.

plot_desc = {
    'plot': {
        'x': { ... },       # description of the x axis
        'y': { ... },       # description of the y axis
        'legend': { ... },  # description of the legend
        ...                 # further layouting options
    },
    'contents': [
        { ... }, # first plot item
        { ... }, # second plot item
    ]
}
eos.plot.Plotter(plot_desc, FILENAME).plot()

In the above, FILENAME is an optional argument naming the file into which the plot shall be placed. The format is automatically determined based on the file name extension.

Plot Layouting

By default plots lack any axis labels and units, and any legend.

An axis’ description is provided through the following key/value pairs, which can apply equally to the x and y axis:

  • label (str, may contain LaTeX commands) – The axis’ label.

  • unit (str, may contain LaTeX commands) – The axis’ unit, which will be appended to the axis’ label in square brackets.

  • range (list or tuple of two float) – The tuple of [minimal, maximal] values, which will be displayed along the axis.

  • scale (str) – Can be either linear or log.

  • scaling_factor (number) – The axis’ scale by which all tick coordinates will be divided. The scale will not be appended to the axis’ label automatically. Using this argument is not recommended as it prevents automatic axis tick formatting and providing the argument below is required.

  • format (str, Python 3 format string) – The axis’ tick label format can be provided and is only in use when scale is used, to avoid a bad string representation of the axis ticks. For example, the user might need to determine the necessary number of digits manually. Due to a Matplotlib peculiarity, the format string must always format the variable x. See Matplotlib format strings for details.

The legend description presently only includes options for its location:

  • location (str, valid Matplotlib legend location) – The legend’s location within the plot.

Further layouting options are:

  • title (str) – The plot’s title.

  • size (tuple of two numbers) – The plot’s size in x and y directions provided in centimeters.

  • axes (str, equal) – Enforces equal scaling of the plot’s x and y axes, if set.

  • grid (str, either major, minor, or both) – Enables the plot’s gridline, if set.

An example illustrating plot layouting follows:

plot_args = {
    'plot': {
        'x': { 'label': r'$q^2$', 'unit': r'$\textnormal{GeV}^2$', 'range': [0.0, 11.60] },
        'y': { 'label': r'$d\mathcal{B}/dq^2$',                    'range': [0.0,  5e-3] },
        'legend': { 'location': 'upper center' },
        'size': [10, 5]
    },
    'contents': [
        ...
    ]
}

Plot Contents

Each item in a plot’s contents is represented by a dictionary. Each features the mandatory type key and more type-specific (mandatory or optional) keys.

  • type (str, mandatory) – The type of the plot item, from one of the following recognized item types:

    value

    description

    band

    Plots a shaded band

    constraint

    Plots constraints from the EOS library of experimental and theoretical likelihoods

    constraint2D

    Plot 2D contours for two correlated observables from a single constraint

    constraint-overview

    Plots overview of several constraints from the EOS library of experimental and theoretical likelihoods

    graph

    Plots the graph of a function

    expression

    Plots a given expression

    errorbar

    Plots a single errors bar

    histogram

    Plots a 1D histogram of pre-existing random samples

    histogram2D

    Plots a 2D histogram of pre-existing random samples

    kde

    Plots a 1D Kernel Density Estimate (KDE) of pre-existing random samples

    kde2D

    Plots contours of a 2D Kernel Density Estimate (KDE) of pre-existing random samples

    likelihood2D

    Plots contours of a user-provided function

    observable

    Plots a single EOS observable w/o uncertainties as a function of one kinematic variable or one parameter

    point

    Plots a single point

    signal-pdf

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

    uncertainty

    Plots an uncertainty band as a function of one kinematic variable

    uncertainty-binned

    Plots one or more uncertainty band integrated over one kinematic variable

    watermark

    Inserts an EOS watermark into the plots

All item types recognize the following optional keys:

  • name (str, optional) – The name of the plot item, for convenience when reporting warnings and errors.

  • alpha (float, between 0.0 and 1.0) – The opacity of the plot item expressed as an alpha value. 0.0 means completely transparent, 1.0 means completely opaque.

  • color (str, containing any valid Matplotlib color specification) – The color of the plot item. Defaults to one of the colors in the Matplotlib default color cycler.

  • label (str, may contain LaTeX commands) – The label that appears in the plot’s legend for this plot item.

  • style (str, containing any valid Matplotlib style specification) – The style of the plot item.

Plotting Constraints

Contents items of type constraints are used to display one of the built-in experimental or theoretical constraints. The following keys are mandatory:

  • constraints (QualifiedName or iterable thereof) – 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.

When plotting multivariate constraints, the following key is also mandatory:

  • observable (QualifiedName) – 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.

The following keys are optional:

  • xrange (list of int) – 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:

plot_args = {
    'plot': { ... },
    'contents': [
        {
            'label': r'Belle 2015 $\ell=e,\, q=d$',
            'type': 'constraint',
            'color': 'C0',
            'constraints': 'B^0->D^+e^-nu::BRs@Belle:2015A',
            'observable': 'B->Dlnu::BR',
            'variable': 'q2',
            'rescale-by-width': False
        }
    ]
}

Plotting a Function Graph

The graph of a function can be easily plotted by providing the coordinates (x, f(x)) of the function. The coordinates are provided using a data object containing:

  • xvalues (array-like of float) – The values on the x axis at which the function has been evaluated.

  • yvalues (array-like of float) – The values oof the function at the points provided by xvalues.

Example:

xvalues = np.linspace(0, 5, 20)
plot_args = {
    'plot': {
        'x': { 'label': r'$q^2$' },
        'y': { 'label': r'$q^4$' }
    },
    'contents': [
        {
            'label': r'$\ell=\mu$',
            'type': 'graph',
            'data': { 'yvalues': xvalues**2, 'xvalues': xvalues },
            'range': [0, 5],
        },
    ]
}

Plotting Histograms

Contents items of type histogram are used to display samples of a probability density, be it a prior, a posterior, or a signal PDF. The following key is mandatory:

  • data (dict, see below) – The data on probability density that will be histogramed.

Within the data object, the following keys are understood.

  • samples (list of float) – The samples that will be histogramed. Mandatory.

  • weights or log_weights (list of float, optional) – The weights of the samples, on a linear or logarithmic scale. Defaults to uniform weights.

Example:

analysis = ... # eos.Analysis object as discussed in the example notebook `inference.ipynb`
parameter_samples, _, = analysis.sample(N=5000, pre_N=1000)
plot_args = {
    'plot': {
        'x': { 'label': r'$|V_{cb}|$' },
        'y': { 'label': r'$d\mathcal{B}/dq^2$' }
    },
    'contents': [
        {
            'type': 'histogram',
            'data': { 'samples': parameter_samples[:, 0] },
        },
    ]
}

Plotting 2D Histograms

Contents items of type histogram2D are used to display samples of a two-dimension probability density, be it a prior, a posterior, or a signal PDF. The following key is mandatory:

  • data (dict, see below) – The data on probability density that will be histogramed.

Within the data object, the following keys are understood.

  • samples (list of float with shape (N, 2)) – The samples that will be histogramed. Mandatory.

  • weights or log_weights (list of float with length N, optional) – The weights of the samples, on a linear or logarithmic scale, respectively. Defaults to uniform weights.

Additional optional keys are:

  • bins (int or list of int, optional) – The number of bins for both dimensions together or in each dimension seperately. Defaults to 100 for both dimensions.

Example:

analysis = ... # eos.Analysis object as discussed in the example notebook `inference.ipynb`
dstarlnu_kinematics = ... # create kineamtics and SignalPDF as discussed in the example notebook `simulation.ipynb`
dstarlnu_pdf        = ...
dstarlnu_samples, _ = dstarlnu_pdf.sample_mcmc(N=50000, stride=5, pre_N=1000, preruns=3, rng=rng)
plot_args = {
    'plot': {
        'x': { 'label': r'$q^2$', 'unit': r'$\textnormal{GeV}^2$', 'range': [ 0.0, 10.50] },
        'y': { 'label': r'$cos(\theta_\ell)$',                     'range': [-1.0,  +1.0] },
    },
    'contents': [
        {
            'label': r'samples ($\ell=\mu$)',
            'type': 'histogram2D',
            'data': {
                'samples': dstarlnu_samples[:, (0, 1)]
            },
            'bins': 40
        },
    ]
}
eos.plot.Plotter(plot_args).plot()

Plotting Kernel Density Estimates

Contents items of type kde are used to display a kernel density estimate (a smooth histogram) of samples of a probability density, be it a prior, a posterior, or a signal PDF.

The following key is mandatory:

  • data (dict, see below) – The data on the probability density that will be histogramed.

    Within the data object, the following keys are understood.

    • samples (list of float) – The samples that will be histogramed. Mandatory.

    • weights or log_weights (list of float, optional) – The weights of the samples, on a linear or logarithmic scale. Defaults to uniform weights.

The following keys are optional:

  • bandwidth (float) – The factor by which the automatically determined kernel bandwidth is scaled. See the SciPy documentation for gaussian_kde, bw_method='silverman'. Defaults to 1.

  • range (tuple of two float) – The minimum and maximum value of the x coordinate for which the smooth histogram is plotted.

  • level (float) – The probability level of the contour. Defaults to 68.27.

Example:

analysis = ... # eos.Analysis object as discussed in the example notebook `inference.ipynb`
parameter_samples, _, = analysis.sample(N=5000, pre_N=1000)
plot_args = {
    'plot': {
        'x': { 'label': r'$|V_{cb}|$', 'range':[38e-3, 45e-3] }
    },
    'contents': [
        {
            'type': 'kde', 'color': C0, 'label': 'posterior', 'bandwidth': 1,
            'range': [40e-3, 45e-3],
            'data': { 'samples': parameter_samples[:, 0] }
        }
    ]
}

Plotting 2D Kernel Density Estimates

Contents items of type kde2D are used to display contours of a two-dimensional kernel density estimate (a 2D smooth histogram) of samples of a probability density, be it a prior, a posterior, or a signal PDF.

The following key is mandatory:

  • data (dict, see below) – The data on the probability density that will be histogramed.

    Within the data object, the following keys are understood.

    • samples (list of float with shape (N, 2)) – The samples that will be histogramed. Mandatory.

    • weights or log_weights (list of float, optional) – The weights of the samples, on a linear or logarithmic scale. Defaults to uniform weights.

The following keys are optional:

  • bandwidth (float) – The factor by which the automatically determined kernel bandwidth is scaled. See the SciPy documentation for gaussian_kde, bw_method='silverman'. Defaults to 1.

  • contours (a list containing 'lines', 'areas', or both) – The setting for the illustration of the contours. If 'lines' is provided, the contour lines are drawn. If 'areas' is provided, the contour areas are filled. Defaults to ['lines'].

  • levels (list of float) – The probability levels of the contours. Defaults to [68, 95, 99].

Example:

analysis = ... # eos.Analysis object as discussed in the example notebook `inference.ipynb`
parameter_samples, _, = analysis.sample(N=5000, pre_N=1000)
plot_args = {
    'plot': {
        'x': { 'label': r'$|V_{cb}|$', 'range': [38e-3, 47e-3] },
        'y': { 'label': r'$f_+(0)$',   'range': [0.6, 0.75] },
    },
    'contents': [
        {
            'type': 'kde2D', 'color': 'C1', 'label': 'posterior',
            'levels': [68, 95], 'contours': ['lines','areas'], 'bandwidth':3,
            'data': { 'samples': parameter_samples[:, (0,1)] }
        }
    ]
}
eos.plot.Plotter(plot_args).plot()

Plotting a user-provided Likelihood

The following key is mandatory:

  • likelihood (evaluable, see below) – The 2D probability density that will be plotted.

The following keys are optional:

  • contours (a list containing 'lines', 'areas', or both) – The setting for the illustration of the contours. If 'lines' is provided, the contour lines are drawn. If 'areas' is provided, the contour areas are filled. Defaults to ['lines'].

  • levels (list of float) – The probability levels of the contours. Defaults to [68, 95, 99].

  • xrange (list of float) – The x-axis range where the likelihood is evaluated, defaults to the plot ranges if provided.

  • yrange (list of float) – The y-axis range where the likelihood is evaluated, defaults to the plot ranges if provided.

Plotting Observables

Contents items of type observable are used to display one of the built-in observables. The following keys are mandatory:

  • observable (QualifiedName) – The name of the observable that will be plotted. Must identify one of the observables known to EOS; see the complete list of observables.

  • range (list or tuple of two float) –The tuple of [minimal, maximal] values of the specified kinematic variable for which the observable will be evaluated.

  • variable (str) – The name of the kinematic or parameter variable to which the x axis will be mapped; see the complete list of parameters.

Example:

plot_args = {
    'plot': { ... },
    'contents': [
        {
            'label': r'$\ell=\mu$',
            'type': 'observable',
            'observable': 'B->Dlnu::dBR/dq2;l=mu',
            'variable': 'q2',
            'range': [0.02, 11.60],
        },
    ]
}

Plotting Points

Content items of type point are used to display a single data point manually. The following keys are mandatory:

  • x (number) – The point’s x coordinate.

  • y (number) – The point’s y coordinate.

Beside the common set of optional keys, this item type recognizes the following optional keys:

  • marker (str, a valid Matplotlib marker style) – The point’s marker style.

  • markersize (number, a valid Matplotlib marker size) – The point’s marker size in pts.

Example:

plot_args = {
    'plot': { ... },
    'contents': [
        {
            'label': r'LCSR (Bharucha 2012)',
            'type': 'point',
            'color': 'C0',
            'x': 0,
            'y': 0.261,
            'marker': 'o',
            'markersize': 12
        }
    ]
}

Plotting Uncertainty Bands

Contents items of type uncertainty are used to display uncertainty bands at 68% probability for one of the built-in observables. This item type requires that either a predictive distribution of the observables has been previously produced.

Exactly one of the following keys is mandatory:

  • data (dict, see below) – The data on predictive distribution of the observable whose uncertainty band will be plotted.

  • data-file (str, path to an existing data file of type eos.data.Prediction) – The path to a data file that was generated with the eos-analysis command-line client.

For data object, the following keys are mandatory:

  • xvalues (array-like of float) – The values on the x axis at which the observable has been evaluated.

  • samples (list of tuples of float) – The list of samples of the predictive distribution. Each tuple of samples corresponds to an evaluation of the observables at the kinematic configuration corresponding to the xvalues entry with the same index.

  • weights (array-like of float, optional) – The weights of the samples, on a linear scale. Defaults to uniform weights.

The following keys are optional:

  • band (a list containing 'lines', 'areas', or both) – The setting for the illustration of the band. If 'outer' is provided, the band’s outer lines are drawn. If 'median' is provided, the band’s median line is drawn. If 'area' is provided, the band’s areas are filled. Defaults to ['area', 'outer', 'median'].

  • interpolation-type (str) – The type of interpolation to be used for the band. Can be either linear (default) or cubic.

  • plot-data (bool) – If set to True, the data points are plotted on top of the band.

Example:

analysis = ... # eos.Analysis object as discussed in the example notebook `predictions.ipynb`
mu_q2values = numpy.unique(numpy.concatenate((numpy.linspace(0.02,1.00,20), numpy.linspace(1.00,11.60,20))))
mu_obs      = [eos.Observable.make('B->Dlnu::dBR/dq2', prior.parameters,
                                   eos.Kinematics(q2=q2), eos.Options({'form-factors':'BSZ2015','l':'mu'}))
               for q2 in mu_q2values]
_, _, mu_samples = analysis.sample(N=5000, pre_N=1000, observables=mu_obs)
plot_args = {
    'plot': {
        'x': { 'label': r'$q^2$' },
        'y': { 'label': r'$d\mathcal{B}/dq^2$' }
    },
    'contents': [
        {
            'label': r'$\ell=\mu$',
            'type': 'uncertainty',
            'data': { 'samples': mu_samples, 'xvalues': mu_q2values },
            'range': [0.02, 11.60],
        },
    ]
}

Plotting Classes

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.ItemFactory class, which returns an object of a class descended from eos.figure.items.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.

Utility Classes

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)

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.

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>)

Describes the metadata of an analysis file.

Parameters:

  • title (str) – A human-readable title for 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.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: list = <factory>)

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) – The pyhf-based contribution to the likelihood. 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

Raises:

ValueError – If none of constraints, manual_constraints, or pyhf is provided.

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.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.