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]
[--enable_expert] [--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 ...]]
[--approximant_flags APPROXIMANT_FLAGS [APPROXIMANT_FLAGS ...]]
[--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_start F_START [F_START ...]]
[--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
--enable_expert Whether to generate extra diagnostic plots 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
--approximant_flags APPROXIMANT_FLAGS [APPROXIMANT_FLAGS ...]
flags used to control variant of waveform approximant
used. Must be in the form LABEL:FLAG:VALUE where LABEL
is the analysis label that you wish to assign
FLAG:VALUE to
--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_start F_START [F_START ...]
Starting frequency of the supplied waveform
--f_low F_LOW [F_LOW ...]
Low frequency cutoff for likelihood integration used
to generate the samples
--f_ref F_REF [F_REF ...]
Reference frequency of the waveform used to generate
the samples
--f_final F_FINAL [F_FINAL ...]
Final frequency of the waveform. Used 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.