Command line utilities

The pyvela package included a few command line utilities.

pyvela script

The pyvela script can be used to do simple analysis runs where fine control over data handling, prior distributions, sampler, etc is not necessary. It has the followingb syntax.

$ pyvela -h

usage: pyvela [-h] [-J JLSO_FILE] [-P PRIOR_FILE] [-M] [-T TRUTH] [-C CHEAT_PRIOR_SCALE] [-o OUTDIR] [-f] [-N NSTEPS] [-b BURNIN] [-t THIN] par_file [tim_file]

A command line interface for the Vela.jl pulsar timing & noise analysis package. Uses emcee for sampling. This may not be appropriate for more complex datasets. Write your own scripts for such cases.

positional arguments:
  par_file              The pulsar ephemeris file. Should be readable using PINT. The uncertainties listed in the file will be used for 'cheat' priors where applicable.
  tim_file              The pulsar TOA file. Should be readable using PINT. Either this or a JLSO file (-J) should be provided.

options:
  -h, --help            show this help message and exit
  -J JLSO_FILE, --jlso_file JLSO_FILE
                        The JLSO file containing pulsar timing and noise model & TOAs created using `pyvela-jlso`. JLSO files may need to be recreated after updating `Vela.jl` since the data format may change. These
                        files are faster to read and parse.
  -P PRIOR_FILE, --prior_file PRIOR_FILE
                        A JSON file containing the prior distributions for each free parameter. (Ignored if `-J` option is used.)
  -M, --marg_gp_noise   Analytically marginalize the correlated Gaussian noise amplitudes.
  -T TRUTH, --truth TRUTH
                        Pulsar ephemeris file containing the true timing and noise parameter values. Relevant for simulation studies.
  -C CHEAT_PRIOR_SCALE, --cheat_prior_scale CHEAT_PRIOR_SCALE
                        The scale factor by which the frequentist uncertainties are multiplied to get the 'cheat' prior distributions.
  -o OUTDIR, --outdir OUTDIR
                        The output directory. Will throw an error if it already exists (unless -f is given).
  -f, --force_rewrite   Force rewrite the output directory if it exists.
  -N NSTEPS, --nsteps NSTEPS
                        Number of ensemble MCMC iterations
  -b BURNIN, --burnin BURNIN
                        Burn-in length for MCMC chains
  -t THIN, --thin THIN  Thinning factor for MCMC chains

This command created saves the MCMC chain and related metadata into an output directory. This includes the following files. The parameter order in all of these files is the same.

• summary.json : A JSON file containing information about the inputs and the system environment. Useful for debugging.
• The input par and tim files
• The "truth" par file (optional, only relevant for simulations)
• samples.npy : The numpy format file containing the flattened and burned-in MCMC chain. This can be read using numpy.load().
• samples_raw.npy : Same as samples.npy, but the quantities here are in Vela.jl's internal units.
• param_names.txt : An ordered list of free model parameter names following the PINT conventions.
• param_prefixes.txt : An ordered list of free model parameter prefixes following the PINT conventions.
• param_scale_factors.txt : An ordered list of scale factors which convert parameter values from PINT units to Vela.jl's internal units. The values in samples.npy and samples_raw.npy are related by these scale factors.
• params_maxpost.txt : Maximum-posterior sample found in the MCMC chain (May not be the same as the mode of the posterior distribution)
• params_median.txt : The posterior median sample estimated from the MCMC chain
• param_units.txt : Parameter units represented as astropy.units-compatible strings. Empty rows represent dimensionless quantities.
• param_default_values.txt : "Pre-fit" values taken from the input par file.
• <PSR>.maxpost.par : A "post-fit" par file containing the maximum-posterior values taken from the MCMC chain.
• <PSR>.median.par : A "post-fit" par file containing the posterior median values taken from the MCMC chain.
• residuals.txt : Post-fit residuals computed using the posterior median values

pyvela-plot script

Creates a corner plot from a directory containing the output of the pyvela script. The plots are not publication-quality.

$ pyvela-plot -h

usage: pyvela-plot [-h] [-I IGNORE_PARAMS [IGNORE_PARAMS ...]] result_dir

Create a corner plot from pyvela results.

positional arguments:
  result_dir            A directory containing the output of the `pyvela` script.

options:
  -h, --help            show this help message and exit
  -I IGNORE_PARAMS [IGNORE_PARAMS ...], --ignore_params IGNORE_PARAMS [IGNORE_PARAMS ...]
                        Parameters to exclude from the corner plot.

The output looks like this:

pyvela-jlso script

Creates a JLSO file that is a serialization of the Vela.TimingModel and Vector{Vela.TOA} objects from a pair of par and tim files and optionally a prior file. This is useful for reducing the input reading overhead while running repeated analyses on the same input files. The resulting JLSO file can be passed on to the pyvela script through the -J option.

$ pyvela-jlso -h

usage: pyvela-jlso [-h] [-P PRIOR_FILE] [-C CHEAT_PRIOR_SCALE] -o OUTFILE par_file tim_file

Read a par file, tim file, and prior JSON file, and write a JLSO file.

positional arguments:
  par_file              The pulsar ephemeris file. Should be readable using PINT. The uncertainties listed in the file will be used for 'cheat' priors where applicable.
  tim_file              The pulsar TOA file. Should be readable using PINT.

options:
  -h, --help            show this help message and exit
  -P PRIOR_FILE, --prior_file PRIOR_FILE
                        A JSON file containing the prior distributions for each free parameter.
  -C CHEAT_PRIOR_SCALE, --cheat_prior_scale CHEAT_PRIOR_SCALE
                        The scale factor by which the frequentist uncertainties are multiplied to get the 'cheat' prior distributions.
  -o OUTFILE, --outfile OUTFILE
                        The output file name. Will replace an existing file.