.. _output:

Output
=======

After fitting, bayesn-td writes several files to the output directory specified
by the ``output`` argument (in Python) or the ``outputdir`` key (in the YAML
input file).

chains.pkl
-----------

A pickled Python dictionary containing the processed MCMC samples:

.. code-block:: python

    import pickle

    with open('results/my_fit/chains.pkl', 'rb') as f:
        samples = pickle.load(f)

The dictionary contains the following keys. The intrinsic SN parameters are
shared across images, while the per-image parameters and derived quantities
each have an ``images`` dimension.

Shared SN parameters
~~~~~~~~~~~~~~~~~~~~~

- ``theta`` — light-curve shape parameter. Shape: ``(chains, samples, SNe)``.
- ``AV`` — host-galaxy dust extinction :math:`A_V`.
  Shape: ``(chains, samples, SNe)``.
- ``RV`` — host dust :math:`R_V` (only present for ``pop_RV`` models).
  Shape: ``(chains, samples, SNe)``.
- ``eps`` — residual colour variation :math:`\epsilon` (if ``include_eps``
  was ``True``). Stored as a flat vector of spline knot coefficients
  (excluding boundary knots, which are zero by construction).

Per-image parameters
~~~~~~~~~~~~~~~~~~~~~

- ``tmax`` — rest-frame correction to the estimated time of maximum for each
  image. Shape: ``(chains, samples, images, SNe)``.
- ``Ds`` — effective distance modulus for each image.
  Shape: ``(chains, samples, images, SNe)``.

Derived quantities
~~~~~~~~~~~~~~~~~~~

These are computed in post-processing from the sampled parameters:

- ``delta_t`` — time delays between image 0 and each subsequent image
  (see :ref:`time_conventions`), in observer-frame days:
  :math:`\Delta t_{0i} = \mathrm{peak\_mjd}^{(0)} - \mathrm{peak\_mjd}^{(i)}`.
  Negative values mean image :math:`i` arrives later than image 0.
  Shape: ``(chains, samples, N_images-1, SNe)``.
- ``peak_mjd`` — observer-frame peak MJD for each image.
  Shape: ``(chains, samples, images, SNe)``.
- ``mu`` — distance modulus per image, drawn in post-processing from a
  Normal whose mean is the precision-weighted average of the sampled
  :math:`D_s` and the fiducial distance modulus :math:`\hat\mu` (computed from
  the source redshift and the fiducial cosmology), with variance set by the
  BayeSN intrinsic scatter :math:`\sigma_0`.
  Shape: ``(chains, samples, images, SNe)``.
- ``delM`` — grey offset :math:`\delta M = D_s - \mu`.
  Shape: ``(chains, samples, images, SNe)``.
- ``delta`` — Hubble residual :math:`\delta = \mu - \hat\mu`, where
  :math:`\hat\mu` is the distance modulus computed from the source redshift
  and the fiducial cosmology (flat :math:`\Lambda\mathrm{CDM}` with
  :math:`H_0 = 73.24`, :math:`\Omega_m = 0.28` by default).
  Shape: ``(chains, samples, images, SNe)``.

Microlensing parameters
~~~~~~~~~~~~~~~~~~~~~~~~

These are only present if ``include_ml`` was ``True``:

- ``A`` — GP amplitude. Shape: ``(chains, samples, images, SNe)``.
- ``tscale`` — GP time-scale :math:`\lambda`.
  Shape: ``(chains, samples, images, SNe)``.
- ``tau_ml`` — GP localisation in phase.
  Shape: ``(chains, samples, images, SNe)``.
- ``p`` — GP modulation parameter. Shape: ``(chains, samples, images, SNe)``.
- ``eta`` — GP modulation width. Shape: ``(chains, samples, images, SNe)``.
- ``beta_t`` — realised GP function values (the microlensing signal in
  magnitude space). The same magnitude offset is applied to all bands at
  each epoch.

Diagnostics
~~~~~~~~~~~~

- ``diverging`` — boolean array indicating divergent transitions.

initial_chains.pkl
-------------------

The raw MCMC output before post-processing. This contains the same sample
arrays as ``chains.pkl`` but without the derived quantities (``delta_t``,
``peak_mjd``, ``mu``, ``delM``, ``delta``), and before any reshaping of
the sample dimensions.

fit_summary.csv
----------------

A CSV file containing ArviZ summary statistics for all sampled parameters,
including posterior mean, standard deviation, effective sample size
(:math:`n_{\mathrm{eff}}`), and :math:`\hat{R}` convergence diagnostic.
This is generated by ``arviz.summary()``.

Values of :math:`\hat{R}` above 1.05 indicate that the chains have not
converged.

sn_list.txt
-------------

A small CSV file recording the SN name(s) and, if provided, the true time
delays (for simulated data or validation purposes).