Parameters and priors¶
Synopsis:  Class containing the prior and reference pdf, and other parameter information. 

Author:  Jesus Torrado 
Basic parameter specification¶
The params
block contains all the information intrinsic
to the parameters of the model: their prior pdf and reference pdf, their latex labels,
and useful properties for particular samplers (e.g. width of a proposal pdf in an MCMC
– see the documentation for each sampler).
The prior and reference pdf are managed by the Prior
class.
You can specify three different kinds of parameters:
 Fixed parameters are specified by assigning them a value, and are passed directly to the likelihood or theory code.
 Sampled parameters need a
prior
pdf definition and, optionally, a reference pdf (ref
), a LaTeX label to be used when producing plots, and additional properties to aid particular samplers.  Derived parameters do not have a prior definition
(neither a reference value or pdf),
but can have a LaTeX label and a
min
and/ormax
to be used in the sample analysis (e.g. to guess the pdf tails correctly if the derived quantity needs to be positive or negative – defaulted to.inf
,.inf
resp.).
The (optional) reference pdf (ref
) for sampled parameters
defines the region of the prior which is of most
interest (e.g. where most of the prior mass is expected);
samplers needing an initial point
for a chain will attempt to draw it from the ref
if it has been defined (otherwise
from the prior). A good reference pdf will avoid a long burnin stage during the
sampling. If you assign a single value to ref
, samplers will always start from
that value; however this makes convergence tests less reliable as each chain will
start from the same point (so all chains could be stuck near the same point).
The syntax for priors and ref’s has the following fields:
dist
(default:uniform
): any 1dimensional continuous distribution from scipy.stats; e.g.uniform
,[log]norm
for a [log]gaussian, orhalfnorm
for a halfgaussian.loc
andscale
(default: 0 and 1, resp.): the location and scale of the pdf, as they are understood for each particular pdf inscipy.stats
; e.g. for auniform
pdf,loc
is the lower bound andscale
is the length of the domain, whereas in a gaussian (norm
)loc
is the mean andscale
is the standard deviation). Additional specific parameters of the distribution, e.g.
a
andb
as the powers of a Beta pdf.
Note
For bound distributions (e.g. uniform
, beta
…), you can use the more
intuitive arguments min
and max
(default: 0 and 1 resp.) instead of loc
and
scale
(NB: unexpected behaviour for an unbounded pdf).
The order of the parameters is conserved in the table of samples, except that derived parameters are always moved to the end.
An example params
block:
params:
A: 1 # fixed!
B1: # sampled! with uniform prior on [1,1] and ref pdf N(mu=0,sigma=0.25)
prior:
min: 1
max: 1
ref:
dist: norm
loc: 0
scale: 0.25
latex: \mathcal{B}_2
proposal: 0.25
B2: # sampled! with prior N(mu=0.5,sigma=3) and fixed reference value 1
prior:
dist: norm
loc: 0.5
scale: 3
ref: 1 # fixed reference value: all chains start here!
latex: \mathcal{B}_2
proposal: 0.5
C: # derived!
min: 0
latex: \mathcal{C}
You can find another basic example here.
Multidimensional priors¶
The priors described above are obviously 1dimensional.
You can also define more complicated, multidimensional priors
using a prior
block at the base level (i.e. not indented), as in the
the advanced example. All the details below also apply to
the definition of external likelihoods. We will call these
custom priors “external priors”.
Inside the prior
block, list a pair of priors as [name]: [function]
, where the
functions must return logpriors. This priors will be multiplied by the
onedimensional ones defined above. Even if you define an prior for some parameters
in the prior
block, you still have to specify their bounds in the params
block.
A prior function can be specified in two different ways:
 As a function, either assigning a function defined with
def
, or alambda
. Its arguments must be known parameter names.  As a string, which will be passed to
eval()
. The string can be alambda
function definition with known parameters as its arguments (you can usescipy.stats
andnumpy
asstats
andnp
resp.), or animport_module('filename').function
statement if your function is defined in a separate filefilename
in the current folder and is namedfunction
(see e.g. the advanced example).
Note
Your function definition may contain keyword arguments that aren’t known parameter names. They will simply be ignored and left to their default.
Warning
When resuming a run using an external python object as input (e.g. a prior or a likelihood), there is no way for Cobaya to know whether the new object is the same as the old one: it is left to the user to ensure reproducibility of those objects between runs.
Warning
At this moment, external priors can only be functions of sampled and fixed parameters. This may be extended in the future to dependence on derived parameters, probably just for dynamically defined ones, but not for those computed by the theory code, since otherwise the full prior could not be computed before the likelihood, preventing us from avoiding computating the likelihood when the prior is null, or forcing a postcall to the prior.
Workaround #1: If the derived parameter(s) can be computed easily from sampled and fixed parameters, do the computation inside the call to the external prior.
Workaround #2: Define your function as a external likelihood instead, since likelihoods do have access to derived parameters (for an example, see this comment).
Prior normalization for evidence computation¶
The onedimensional priors defined within the params
block are automatically
normalized, so any sampler that computes the evidence will produce the right results as
long as no external priors have been defined, whose normalization is unknown.
To get the prior normalization if using external functions as priors, you can substitute your likelihood by the dummy unit likelihood, and make an initial run with PolyChord to get the prior volume (see section Computing Bayes ratios).
In general, avoid improper priors, since they will produce unexpected errors, e.g.
params:
a:
prior:
min: .inf
max: .inf
Defining parameters dynamically¶
We may want to sample in a parameter space different than the one understood by the likelihood, e.g. because we expect the posterior to be simpler on the alternative parameters.
For instance, in the advanced example, the posterior on the radius and the angle is a gaussian times a uniform, instead of a more complicated gaussian ring. This is done in a simple way at the end of the example. Let us discuss the general case here.
To enble this, cobaya creates a reparameterization layer between the sampled parameters, and the input parameters of the likelihood. E.g. if we want to sample from the logarithm of an input parameter of the likelihood, we would do:
params:
logx:
prior: [...]
drop: True
x: "lambda logx: np.exp(x)"
y:
derived: "lambda x: x**2"
When that information is loaded cobaya will create an interface between two sets of parameters:
 Sampled parameters, i.e. those that have a prior, including
logx
but notx
(it does not have a prior: it’s fixed by a function). Those are the ones with which the sampler interacts. Since the likelihood does not understand them, they must be dropped withdrop: True
.  Likelihood input parameters: those that will be passed to the likelihood
(or theory). They are identified by either having a prior and not being dropped, or
having being assigned a fixed value or a function. Here,
x
would be an input parameter, but notlogx
.
We can use a similar approach to define dynamical derived parameters, which can depend
on input and sampled parameters. To distinguish their notation from that of input
parameters, we insert the functions defining them under a derived
property
(see the parameter y
in the example above).
Note
Dynamical derived parameters can also be functions of yetundefined parameters. In that case, those parameters will be automatically requested from the likelihood (or theory code) that understands them.
Note
Also available are the \(\chi^2 = 2 \log \mathcal{L}\) of the used likelihoods, as chi2__[name], e.g.
likelihood:
my_like: [...]
params:
my_derived:
derived: "lambda chi2__my_like: [...]"
Note
By default, the values of dynamical input parameters (e.g. x
above) are saved
as if they were derived parameters. If you would like to ignore them, define them using
the following extended notation:
params:
x:
value: "lambda logx: np.exp(logx)"
derived: False
Note
If you want to fix the value of a parameter whose only role is being an argument of a
dynamically defined one and is not supposed to be passed to the likelihood, you need
to explicilty drop it. E.g. suppose that you want to sample from a likelihood that
depends on x
, but want to use log(x)
as the sampled parameter; you would do it
like this:
params:
logx:
prior: [...]
drop: True
x:
value: "lambda logx: np.exp(x)"
Now, if you want to fix the value of logx
without changing the structure of the
input, do
params:
logx:
value: [fixed_value]
drop: True
x:
value: "lambda logx: np.exp(x)"
Changing and redefining parameters; inheritance¶
As we will see in the likelihoods documentation, just by mentioning a likelihood, the parameters of its default experimental model are inherited without needing to restate them.
But you may want to fix their value, redefine their prior or some other property in your input file. To do that, simply state you new parameter definition as you would normally do. For your convenience, if you do that, you don’t need to restate all of the properties of the parameters (e.g. the latex label if just changing the prior).
As a general rule, when trying to redefine anything in a parameter, everything not redefined is inherited, except for the prior, which must not be inheritable in order to allow redefining sampled parameters into something else.
Just give it a try and it should work fine, but, in case you need the details:
 Redefining fixed into:
 fixed: simply assign it a new value
 sampled: define a prior for it (and optionally reference, label, etc.)
 derived: mention the parameter and assign nothing to it (you may define a min, max or latex label, but not a prior)
 Redefining sampled into:
 fixed: simply assign it a value
 sampled: change any of prior/ref/latex, etc, to your taste; the rest are inherited from the defaults
 derived: mention the parameter and assign nothing to it (you may define a min, max or latex label, but not a prior; the label is inherited from the defaults)
 Redefining derived into:
 fixed: simply assign it a value
 sampled: define a prior for it (and optionally reference, label, etc.)
 derived: change any of prior/ref/latex, etc, to your taste; the rest are inherited from the defaults
prior
class¶

class
cobaya.prior.
Prior
(parameterization, info_prior=None)¶ Class managing the prior and reference pdf’s.

d
()¶ Returns: Dimensionality of the parameter space.

bounds
(confidence_for_unbounded=1)¶ For unbounded parameters, if
confidence_for_unbounded < 1
given, the returned interval contains the requested confidence level interval with equal areas around the median.Returns: An array of bounds [min,max]
for the parameters, in the order given by the input.NB: If an external prior has been defined, the bounds given in the ‘prior’ subblock of that particular parameter’s info may not be faithful to the externally defined prior.

sample
(n=1, ignore_external=False)¶ Generates samples from the prior pdf.
If an external prior has been defined, it is not possible to sample from the prior directly. In that case, if you want to sample from the “default” pdf (i.e. ignoring the external prior), set
ignore_external=True
.Returns: Array of n
samples from the prior, as vectors[value of param 1, ...]
.

logps
(x)¶ Takes a point (sampled parameter values, in the correct order).
Returns: An array of the prior logprobability densities of the given point or array of points. The first element on the list is the products of 1d priors specified in the params
block, and the following ones (if present) are the priors specified in theprior
block in the same order.

logp
(x)¶ Takes a point (sampled parameter values, in the correct order).
Returns: The prior logprobability density of the given point or array of points.

logps_external
(x)¶ Evaluates the logprior using the external prior only.

covmat
(ignore_external=False)¶ Returns: The covariance matrix of the prior.

reference
(max_tries=inf, max_tries_warning='10d')¶ Returns: One sample from the ref pdf. For those parameters that do not have a ref pdf defined, their value is sampled from the prior. NB: The way this function works may be a little dangerous: if two parameters have an (external) joint prior defined and only one of them has a reference pdf, one should sample the other from the joint prior conditioned to the first one being drawn from the reference. Otherwise, one may end up with a point with null prior pdf. In any case, it should work for getting initial reference points, e.g. for an MCMC chain.

reference_covmat
()¶ Returns: The standard deviation of the 1d ref pdf’s. For those parameters that do not have a ref pdf defined, the standard deviation of the prior is taken instead.
