summarypages

The summarypages executable is the main interface to PESummary, it generates all plots (publication, detchar, classification), and all webpages to display the plots and a single metafile containing all the data about the analysis. It is the go to executable for your analysis.

To see help for this executable please run:

$ summarypages --help
usage: summarypages [-h] [-w DIR] [-b DIR] [--labels LABELS [LABELS ...]]
                    [-s SAMPLES [SAMPLES ...]] [-c CONFIG [CONFIG ...]]
                    [--email EMAIL] [-i INJ_FILE [INJ_FILE ...]]
                    [--add_to_existing] [-e EXISTING] [--seed SEED] [-v]
                    [--preferred PREFERRED]
                    [--ignore_parameters IGNORE_PARAMETERS [IGNORE_PARAMETERS ...]]
                    [--nsamples NSAMPLES] [--keep_nan_likelihood_samples]
                    [--burnin BURNIN] [--burnin_method BURNIN_METHOD]
                    [--regenerate REGENERATE [REGENERATE ...]]
                    [--mcmc_samples]
                    [--path_to_samples PATH_TO_SAMPLES [PATH_TO_SAMPLES ...]]
                    [--pe_algorithm PE_ALGORITHM [PE_ALGORITHM ...]]
                    [--reweight_samples REWEIGHT_SAMPLES]
                    [--descriptions DESCRIPTIONS [DESCRIPTIONS ...]]
                    [--custom_plotting CUSTOM_PLOTTING] [--publication]
                    [--publication_kwargs PUBLICATION_KWARGS [PUBLICATION_KWARGS ...]]
                    [--kde_plot] [--colors COLORS [COLORS ...]]
                    [--palette PALETTE]
                    [--linestyles LINESTYLES [LINESTYLES ...]]
                    [--include_prior] [--style_file STYLE_FILE]
                    [--add_to_corner ADD_TO_CORNER [ADD_TO_CORNER ...]]
                    [--add_existing_plot EXISTING_PLOT [EXISTING_PLOT ...]]
                    [--dump] [--notes NOTES]
                    [--prior_file PRIOR_FILE [PRIOR_FILE ...]]
                    [--nsamples_for_prior NSAMPLES_FOR_PRIOR]
                    [--disable_prior_sampling] [--disable_comparison]
                    [--disable_interactive] [--disable_corner]
                    [--disable_expert] [--multi_process MULTI_PROCESS]
                    [--file_format FILE_FORMAT [FILE_FORMAT ...]]
                    [--restart_from_checkpoint]
                    [--compare_results COMPARE_RESULTS [COMPARE_RESULTS ...]]
                    [--save_to_json] [--posterior_samples_filename FILENAME]
                    [--external_hdf5_links]
                    [--hdf5_compression HDF5_COMPRESSION]
                    [--disable_injection] [-a APPROXIMANT [APPROXIMANT ...]]
                    [--sensitivity] [--gracedb GRACEDB]
                    [--gracedb_server GRACEDB_SERVER]
                    [--gracedb_data GRACEDB_DATA [GRACEDB_DATA ...]]
                    [--psd PSD [PSD ...]] [--{}_psd IFO:PATH_to_PSD.dat]
                    [--calibration CALIBRATION [CALIBRATION ...]]
                    [--{}_calibration IFO:PATH_to_CAL.txt]
                    [--trigfile INJ_FILE [INJ_FILE ...]]
                    [--gwdata CHANNEL:CACHEFILE or PICKLEFILE [CHANNEL:CACHEFILE or PICKLEFILE ...]]
                    [--multi_threading_for_skymap]
                    [--nsamples_for_skymap NSAMPLES_FOR_SKYMAP]
                    [--calculate_multipole_snr] [--calculate_precessing_snr]
                    [--psd_default PSD_DEFAULT] [--f_low F_LOW [F_LOW ...]]
                    [--f_ref F_REF [F_REF ...]]
                    [--f_final F_FINAL [F_FINAL ...]]
                    [--delta_f DELTA_F [DELTA_F ...]] [--no_ligo_skymap]
                    [--gw] [--public] [--redshift_method {approx,exact}]
                    [--cosmology COSMOLOGY] [--no_conversion]
                    [--disable_remnant] [--force_BBH_remnant_computation]
                    [--force_BH_spin_evolution] [--evolve_spins]
                    [--evolve_spins_forwards]
                    [--evolve_spins_backwards [{precession_averaged,hybrid_orbit_averaged}]]
                    [--NRSur_fits [NRSUR_FITS]] [--waveform_fits]
                    [pesummary]

optional arguments:
  -h, --help            show this help message and exit

Core command line options
-------------------------:
  pesummary             Configuration file containing command line arguments
  -w DIR, --webdir DIR  make page and plots in DIR
  -b DIR, --baseurl DIR
                        make the page at this url
  --labels LABELS [LABELS ...]
                        labels used to distinguish runs
  -s SAMPLES [SAMPLES ...], --samples SAMPLES [SAMPLES ...]
                        Path to posterior samples file(s). See documentation
                        for allowed formats. If path is on a remote server,
                        add username and servername in the form
                        {username}@{servername}:{path}. If path is on a public
                        webpage, ensure the path starts with https://. You may
                        also pass a string such as posterior_samples*.dat and
                        all matching files will be used
  -c CONFIG [CONFIG ...], --config CONFIG [CONFIG ...]
                        configuration file associcated with each samples file.
  --email EMAIL         send an e-mail to the given address with a link to the
                        finished page.
  -i INJ_FILE [INJ_FILE ...], --inj_file INJ_FILE [INJ_FILE ...]
                        path to injetcion file
  --add_to_existing     add new results to an existing html page
  -e EXISTING, --existing_webdir EXISTING
                        web directory of existing output
  --seed SEED           Random seed to used through the analysis.
  -v, --verbose         print useful information for debugging purposes
  --preferred PREFERRED
                        label of the preferred run. If only one result file is
                        passed this label is the preferred analysis by default

Options specific to the samples you wish to input
-------------------------------------------------:
  --ignore_parameters IGNORE_PARAMETERS [IGNORE_PARAMETERS ...]
                        Parameters that you wish to not include in the
                        summarypages. You may list them or use wildcards
                        ('recalib*')
  --nsamples NSAMPLES   The number of samples to use and store in the
                        PESummary metafile. These samples will be randomly
                        drawn from the posterior distributions
  --keep_nan_likelihood_samples
                        Do not remove posterior samples where the
                        likelihood='nan'. Without this option, posterior
                        samples where the likelihood='nan' are removed by
                        default.
  --burnin BURNIN       Number of samples to remove as burnin
  --burnin_method BURNIN_METHOD
                        The algorithm to use to remove mcmc samples as burnin.
                        This is only used when `--mcmc_samples` also used
  --regenerate REGENERATE [REGENERATE ...]
                        List of posterior distributions that you wish to
                        regenerate if possible
  --mcmc_samples        treat the passed samples as seperate mcmc chains for
                        the same analysis
  --path_to_samples PATH_TO_SAMPLES [PATH_TO_SAMPLES ...]
                        Path to the posterior samples stored in the result
                        file. If None, pesummary will search for a 'posterior'
                        or 'posterior_samples' group. If more than one result
                        file is passed, and only the third file requires a
                        path_to_samples provide --path_to_samples None None
                        path/to/samples
  --pe_algorithm PE_ALGORITHM [PE_ALGORITHM ...]
                        Name of the algorithm used to generate the result file
  --reweight_samples REWEIGHT_SAMPLES
                        Method to use when reweighting posterior and/or prior
                        samples. Default do not reweight samples.
  --descriptions DESCRIPTIONS [DESCRIPTIONS ...]
                        JSON file containing a set of descriptions for each
                        analysis or dictionary giving descriptions for each
                        analysis directly from the command line (e.g.
                        `--descriptions label1:'description'`). These
                        descriptions are then saved in the output.

Options specific to the plots you wish to make
----------------------------------------------:
  --custom_plotting CUSTOM_PLOTTING
                        Python file containing functions for custom plotting
  --publication         generate production quality plots
  --publication_kwargs PUBLICATION_KWARGS [PUBLICATION_KWARGS ...]
                        Optional kwargs for publication plots
  --kde_plot            plot a kde rather than a histogram
  --colors COLORS [COLORS ...]
                        Colors you wish to use to distinguish result files
  --palette PALETTE     Color palette to use to distinguish result files
  --linestyles LINESTYLES [LINESTYLES ...]
                        Linestyles you wish to use to distinguish result files
  --include_prior       Plot the prior on the same plot as the posterior
  --style_file STYLE_FILE
                        Style file you wish to use when generating plots
  --add_to_corner ADD_TO_CORNER [ADD_TO_CORNER ...]
                        Parameters you wish to include in the corner plot
  --add_existing_plot EXISTING_PLOT [EXISTING_PLOT ...]
                        Path(s) to existing plots that you wish to add to the
                        summarypages. Should be of the form {label}:{path}

Options specific to the webpages you wish to produce
----------------------------------------------------:
  --dump                dump all information onto a single html page
  --notes NOTES         Single file containing notes that you wish to put on
                        summarypages

Options specific for passing prior files
----------------------------------------:
  --prior_file PRIOR_FILE [PRIOR_FILE ...]
                        File containing for the prior samples for a given
                        label
  --nsamples_for_prior NSAMPLES_FOR_PRIOR
                        The number of prior samples to extract from a bilby
                        prior file or a bilby result file
  --disable_prior_sampling
                        Skip generating prior samples using bilby

Options specific for enhancing the performance of the code
----------------------------------------------------------:
  --disable_comparison  Whether to make a comparison webpage if multple
                        results are present
  --disable_interactive
                        Whether to make interactive plots or not
  --disable_corner      Whether to make a corner plot or not
  --disable_expert      Whether to generate extra diagnostic plots or not
  --multi_process MULTI_PROCESS
                        The number of cores to use when generating plots
  --file_format FILE_FORMAT [FILE_FORMAT ...]
                        The file format of each result file.
  --restart_from_checkpoint
                        Restart from checkpoint if a checkpoint file can be
                        found in webdir

Options specific for reading and manipulating pesummary metafiles
-----------------------------------------------------------------:
  --compare_results COMPARE_RESULTS [COMPARE_RESULTS ...]
                        labels for events stored in the posterior_samples.json
                        that you wish to compare
  --save_to_json        save the meta file in json format
  --posterior_samples_filename FILENAME
                        name of the posterior samples metafile that is
                        produced
  --external_hdf5_links
                        save each analysis as a seperate hdf5 file and connect
                        them to the meta file through external links
  --hdf5_compression HDF5_COMPRESSION
                        compress each dataset with a particular compression
                        filter. Filter must be integer between 0 and 9. Only
                        applies to meta files stored in hdf5 format. Default,
                        no compression applied
  --disable_injection   whether or not to extract stored injection data from
                        the meta file

=====================================================
Options specific for gravitational wave results files
=====================================================:
  -a APPROXIMANT [APPROXIMANT ...], --approximant APPROXIMANT [APPROXIMANT ...]
                        waveform approximant used to generate samples
  --sensitivity         generate sky sensitivities for HL, HLV
  --gracedb GRACEDB     gracedb of the event
  --gracedb_server GRACEDB_SERVER
                        service url to use when accessing gracedb
  --gracedb_data GRACEDB_DATA [GRACEDB_DATA ...]
                        data you wish to download from gracedb and store in
                        the metafile
  --psd PSD [PSD ...]   psd files used
  --{}_psd IFO:PATH_to_PSD.dat
                        psd files used for a specific label. '{}' should be
                        replaced with the label of interest. For example
                        --IMRPhenomPv3_psd H1:IF0_psd.dat
  --calibration CALIBRATION [CALIBRATION ...]
                        files for the calibration envelope
  --{}_calibration IFO:PATH_to_CAL.txt
                        calibration files used for a specific label. '{}'
                        should be replaced with the label of interest. For
                        example --IMRPhenomPv3_calibration H1:IF0_cal.dat
  --trigfile INJ_FILE [INJ_FILE ...]
                        xml file containing the trigger values
  --gwdata CHANNEL:CACHEFILE or PICKLEFILE [CHANNEL:CACHEFILE or PICKLEFILE ...]
                        channels and paths to strain cache files
  --multi_threading_for_skymap
                        use multi-threading to speed up generation of
                        ligo.skymap
  --nsamples_for_skymap NSAMPLES_FOR_SKYMAP
                        The number of samples used to generate the
                        ligo.skymap. These samples will be randomly drawn from
                        the posterior distributions
  --calculate_multipole_snr
                        Calculate the SNR in the (ell, m) = [(2, 1), (3, 3),
                        (4, 4)] subdominant multipoles based on the posterior
                        samples
  --calculate_precessing_snr
                        Calculate the precessing SNR based on the posterior
                        samples
  --psd_default PSD_DEFAULT
                        The PSD to use for conversions when no psd file is
                        provided. Default aLIGOZeroDetHighPower
  --f_low F_LOW [F_LOW ...]
                        Low frequency cutoff used to generate the samples
  --f_ref F_REF [F_REF ...]
                        Reference frequency used to generate the samples
  --f_final F_FINAL [F_FINAL ...]
                        Final frequency to use when calculating the precessing
                        snr
  --delta_f DELTA_F [DELTA_F ...]
                        Difference in frequency samples when calculating the
                        precessing snr
  --no_ligo_skymap      do not generate a skymap with ligo.skymap
  --gw                  run with the gravitational wave pipeline
  --public              generate public facing summary pages
  --redshift_method {approx,exact}
                        The method to use when estimating the redshift
  --cosmology COSMOLOGY
                        The cosmology to use when calculating the redshift
  --no_conversion       Do not generate any conversions

Options specific for calculating the remnant properties
-------------------------------------------------------:
  --disable_remnant     Prevent remnant quantities from being calculated when
                        the conversions module is used
  --force_BBH_remnant_computation
                        Use BBH fits to calculate remnant quantities for
                        systems that include tidal deformability parameters
  --force_BH_spin_evolution
                        Use BH spin evolution methods to evolve spins in
                        systems that include tidal deformability parameters
  --evolve_spins        Evolve the spins up to the Schwarzschild ISCO
                        frequency for remnant fits evaluation
  --evolve_spins_forwards
                        Evolve the spins up to the Schwarzschild ISCO
                        frequency for remnant fits evaluation
  --evolve_spins_backwards [{precession_averaged,hybrid_orbit_averaged}]
                        Method to use when evolving spins backwards to
                        infinite separation. Default 'precession_averaged'.
  --NRSur_fits [NRSUR_FITS]
                        The NRSurrogate you wish to use to calculate the
                        remnant quantities from your posterior samples. If not
                        passed, the average NR fits are used
  --waveform_fits       Use the provided approximant (either from command line
                        or stored in the result file) to calculate the remnant
                        quantities from your posterior samples. If not passed,
                        the average NR fits are used

For details about each page produced, visit the summary pages section.

Multiple result files

summarypages allows for you to pass a single or multiple result files generated from any parameter estimation code. If a multiplt result files are passed, then all single plots/pages as well as comparison plots/pages are generated.

Multiple MCMC chains

summarypages allows for you to pass multiple mcmc chains for a single analysis. This may be done by passing the –mcmc_samples command line argument. An example command line is shown below:

$ summarypages --webdir ./mcmc --samples chain1.hdf5 chain2.dat chain2.json \
               --labels one --mcmc_chains

When this is run, a single plot for each parameter is generated which shows the posterior distribution for each chain. The Gelman-Rubin statistic is then printed at the top of each plot to measure convergence. If you have already generated a summarypage comparing 10 seperate chains, you may then select a subset of chains to compare by rerunning with the –compare option:

$ summarypages --webdir ./select \
               --samples ./mcmc/samples/posterior_samples.h5 \
               --compare chain_0 chain_1

Add to existing

PESummary also allows for you to add to an existing webpage that has already been generated using the summarypages executable. This is done by using the –existing_webdir flag as opposed to the –webdir flag.

Labels

Each result file requires a label that is unique. This label is used throughout the PESummary workflow and is used to index the plots and html pages to ensure that the plots are associated with the correct result file. If no label is chosen, then summarypages will assign a label for the given result file. This label is chosen to be {time}_{filename} where time is the time at which you submitted the job and filename is the name of the result file.

Passing a PESummary configuration file

You are also able to pass PESummary a configuration file storing all of the command line arguments. For instance, you can generate a summarypage by running,

$ summarypages pesummary.ini

Where the configuration file has the following structure:

You are also able to override all commands in the configuration file by also including them in the command line. For instance, if you run,

$ summarypages pesummary.ini --webdir ./different_webpage

The webpages will be saved in the directory ./different_webpage.