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. .. code:: python from cobaya import run updated_info, sampler = run(your_input) ``sampler`` here is the sampler instance that just ran, e.g. the ``mcmc`` sampler. The results of the sampler can be obtained as ``sampler.products()``, which returns 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. .. _output_shell: 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 component. - ``[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. - :doc:`MCMC ` produces an additional ``[prefix].progress`` file monitoring the convergence of the chain, that can be inspected or :ref:`plotted `. - :doc:`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 :doc:`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. 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 without 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 :ref:`input_resume`). .. 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. .. _output_format: Sample files or ``SampleCollection`` instances ----------------------------------------------- Samples are stored in files (if text output requested) or :class:`~collection.SampleCollection` instances (in interactive mode). A typical sample file will look like the one presented in the :doc:`quickstart example `: .. code:: # 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 :ref:`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 :ref:`external priors `, if they exist. * ``chi2``: total effective :math:`\chi^2`, equals twice minus the total log-likelihood. * ``chi2__[...]``: individual effective :math:`\chi^2`'s, adding up to the total one. ``output`` module documentation ------------------------------- .. automodule:: output :noindex: .. autofunction:: output.split_prefix .. autofunction:: output.get_info_path .. autofunction:: output.get_output .. autoclass:: output.OutputReadOnly :members: .. autoclass:: output.Output :members: .. autoclass:: output.OutputDummy :noindex: ``collection`` module documentation ----------------------------------- .. automodule:: collection :noindex: .. autoclass:: collection.SampleCollection :members: .. autoclass:: collection.OnePoint :noindex: .. autoclass:: collection.OneSamplePoint :noindex: