Output files

The outputs from a kima run are basic text files.

During a run, three files are continuously updated

• levels.txt
• sample.txt
• sample_info.txt

and the analysis of the results with the pykima package creates another three

• posterior_sample.txt
• posterior_sample_info.txt
• weights.txt

important note
The complete output of a run is contained in the levels.txt, sample.txt, and sample_info.txt files. If you delete or change one of these files, it is impossible to recover the results.

Below we will go into details of each file, but the simplest way to analyse the results is by using the pykima package. It's unlikely that you will ever need to read these output text files (unless you're not working in Python).

You can also store the output of a run in a .zip file with the kima-showresults command:

kima-showresults zip
# type in the filename

and load it later with pykima:

import pykima as pk
res = pk.load('filename.zip')

Let's go in detail over each of the output files.

• levels.txt
  contains information about the Diffusive Nested Sampling levels created during the run. The first column is the (log) enclosed prior mass — usually denoted log(X) — in units of nats. The second column contains the (log) likelihood of each level. Level 0, which has log(X)=0, thus X=1, and a likelihood effectively equal to minus infinity, is the prior.
  The remaining columns are less interesting (see Brewer & Foreman-Mackey (2016) for more details).

• sample.txt
  contains samples from the mixture of constrained distributions sampled by the diffusive nested sampling algorithm, not the posterior distribution. Each line represents one point in parameter space, with one value for each of the parameters in the model. Therefore, depending on the model settings, this file can have different number of columns. The name of each parameter is in the first (commented) line. In order, they are

  • extra white noise ("jitter")
  • slope [if trend=true]
  • (4) GP hyperparameters [if GP=true]
  • number of parameters in Keplerian (always 5)
  • maximum number of planets in the model
  • number of planets in this sample [always fixed if fix=true]
  • orbital period(s)
    • P1, P2, ... Pn, for a sample with n planets
  • semi-amplitude(s)
    • K1, K2, ... Kn
  • fraction of orbit
    • phi1, ....
  • eccentrity
    • e1, ....
  • omega, argument of periastron
    • w1, ....
  • staleness
  • systemic velocity

  Note: one way to follow the progress of the sampler during a run is to run the command

  tail -f sample.txt
  

• sample_info.txt
  contains extra information about each of the samples from sample.txt. The first column is the level corresponding to that sample (remember level 0 represents the prior), the second column is the value of the (log) likelihood, the third a likelihood tiebreaker, and the final column says which thread the particle belonged to.

After postprocessing with the pykima package, the two new files contain information about the posterior distribution.

• posterior_sample.txt
  this file is similar in structure to the sample.txt but it contains samples from the posterior distribution. The number of lines should be equal to the (integer floor) of the effective sample size, which is shown in the terminal when running kima-showresults. Histograms of the columns on this file will represent the marginal posteriors for each parameter.

• posterior_sample_info.txt this file is similar in structure to the sample_info.txt, but it contains information on the posterior samples.

• weights.txt
  the posterior weight of each sample in sample.txt.