# Output¶

The results of a cobaya run are in all cases an updated information dictionary (interactive call) or file (shell call), plus the products generated by the sampler used.

## Interactive call¶

The updated information and products mentioned above are returned by the run function of the cobaya.run module, which performs the sampling process.

from cobaya.run import run
updated_info, products = run(your_input)


products here is a dictionary whose contents depend on the sampler used, e.g. one chain for the mcmc sampler.

If the input information contains a non-null output, products are written to the hard drive too, as described below.

## Shell call¶

When called from the shell, cobaya generates most commonly the following output files:

• [prefix].input.yaml: a file with the same content as the input file.
• [prefix].updated.yaml: a file containing the input information plus the default values used by each module.
• [prefix].[number].txt: one or more sample files, containing one sample per line, with values separated by spaces. The first line specifies the columns.

Note

Some samplers produce additional output, e.g.

• MCMC produces an additional [prefix].progress file monitoring the convergence of the chain, that can be inspected or plotted.
• PolyChord produces native output, which is translated into cobaya’s output format with the usual file names, but also kept under a sub-folder within the output folder.

To specify the folder where the output files will be written and their name, use the option output at the top-level of the input file (i.e. not inside any block, see the example input in the Quickstart example):

• output: something: the output will be written into the current folder, and all output file names will start with something.
• output: somefolder/something: similar to the last case, but writes into the folder somefolder, which is created at that point if necessary.
• output: somefolder/: writes into the folder somefolder, which is created at that point if necessary, with no prefix for the file names.
• output: null: will produce no output files whatsoever – the products will be just loaded in memory. Use only when invoking from the Python interpreter.

Warning

Please, do not use a dot, ., in the output prefix: it may confuse Cobaya or GetDist.

If calling cobaya-run from the command line, you can also specify the output prefix with an --output [something] flag (it takes precedence over the output defined inside the yaml file, if it exists).

Note

When calling from the command line, if output has not been specified, it defaults to the first case, using as a prefix the name of the input file sans the yaml extension.

Instead, when calling from a Python interpreter, if output has not been specified, it is understood as output: null.

In all cases, the output folder is based on the invocation folder if cobaya is called from the command line, or the current working directory (i.e. the output of import os; os.getcwd()) if invoked within a Python script or a Jupyter notebook.

Warning

If cobaya output files already exist with the given prefix, it will raise an error, unless you explicitly request to resume or overwrite the existing sample (see Resuming or overwriting an existing sample).

Note

When the output is written into a certain folder different from the invocation one, the value of output in the output .yaml file(s) is updated such that it drops the mention to that folder.

## Sample files or Collection instances¶

Samples are stored in files (if text output requested) or Collection instances (in interactive mode). A typical sample file will look like the one presented in the quickstart example:

# weight  minuslogpost         a         b  derived_a  derived_b  minuslogprior  minuslogprior__0      chi2  chi2__gaussian
10.0      4.232834  0.705346 -0.314669   1.598046  -1.356208       2.221210          2.221210  4.023248        4.023248
2.0      4.829217 -0.121871  0.693151  -1.017847   2.041657       2.411930          2.411930  4.834574        4.834574


Both sample files and collections contain the following columns, in this order:

• weight: the relative weight of the sample.
• minuslogpost: minus the log-posterior, unnormalized.
• a, b...: sampled parameter values for each sample
• derived_a, derived_b: derived parameter values for each sample. They appear after the sampled ones, but cannot be distinguished from them by name (they just happen to start with derived_ in this particular example, but can have any name).
• minuslogprior: minus the log-prior (unnormalized if external priors have been defined), sum of the individual log-priors.
• minuslogprior__[...]: individual priors; the first of which, named 0, corresponds to the separable product of 1-dimensional priors defined in the params block, and the rest to external priors, if they exist.
• chi2: total effective $$\chi^2$$, equals twice minus the total log-likelihood.
• chi2__[...]: individual effective $$\chi^2$$’s, adding up to the total one.