summarytgr

The summarytgr executable is designed to post-process and generate webpages to display results from analyses which test the General Theory of Relativity. For details about the review of this executable, see the review page. To see help for this executable please run:

$ summarytgr --help
usage: summarytgr [-h] -w DIR -t {imrct} [--{test}_kwargs EXAMPLE_TEST_KWARGS]
                  [-s SAMPLES [SAMPLES ...]] [--labels LABELS [LABELS ...]]
                  [-a APPROXIMANT [APPROXIMANT ...]] [--evolve_spins]
                  [--f_low F_LOW [F_LOW ...]]
                  [--cutoff_frequency CUTOFF_FREQUENCY [CUTOFF_FREQUENCY ...]]
                  [--links_to_pe_pages LINKS_TO_PE_PAGES [LINKS_TO_PE_PAGES ...]]
                  [--disable_pe_page_generation]
                  [--pe_page_options PE_PAGE_OPTIONS]
                  [--make_diagnostic_plots]

This executable is used to post-process and generate webpages to display
results from analyses which test the General Theory of Relativity

optional arguments:
  -h, --help            show this help message and exit
  -w DIR, --webdir DIR  make page and plots in DIR
  -t {imrct}, --test {imrct}
                        What test do you want to run? Currently only supports
                        imrct
  --{test}_kwargs EXAMPLE_TEST_KWARGS
                        Kwargs you wish to use when postprocessing the
                        results. Kwargs should be provided as a dictionary
                        'kwarg:value'. For example `--imrct_kwargs N_bins:201
                        multi_process:4` would pass the kwargs N_bins=201,
                        multi_process=4 to the IMRCT function. The test name
                        '{test}' should match the test provided with the
                        --test flag
  -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}
  --labels LABELS [LABELS ...]
                        Labels used to distinguish runs. The label format is
                        dependent on the TGR test you wish to use. For the
                        IMRCT test, labels need to be inspiral and
                        postinspiral if analysing a single event or {label1}:i
                        nspiral,{label1}:postinspiral,{label2}:inspiral,{label
                        2}:postinspiral,... if analysing two or more events
                        (where label1/label2 is a unique string to distinguish
                        files from a single event). If a metafile is provided,
                        labels need to be {inspiral_label}:inspiral
                        {postinspiral_label}:postinspiral where inspiral_label
                        and postinspiral_label are the pesummary labels for
                        the inspiral and postinspiral analyses respectively.
  -a APPROXIMANT [APPROXIMANT ...], --approximant APPROXIMANT [APPROXIMANT ...]
                        Approximant used for the runs
  --evolve_spins        Evolve spins while calculating remnant quantities
  --f_low F_LOW [F_LOW ...]
                        Low frequency cutoff used to generate the samples.
                        Only used when evolving spins
  --cutoff_frequency CUTOFF_FREQUENCY [CUTOFF_FREQUENCY ...]
                        Cutoff Frequency for IMRCT. Overrides any cutoff
                        frequency present in the supplied files. The supplied
                        cutoff frequency will only be used as metadata and
                        does not affect the cutoff frequency used in the
                        analysis. If only one number is supplied, the inspiral
                        maximum frequency and the postinspiral maximum
                        frequency are set to the same number. If a list of
                        length 2 is supplied, this assumes that the one
                        corresponding to the inspiral label is the maximum
                        frequency for the inspiral and that corresponding to
                        the postinspiral label is the minimum frequency for
                        the postinspiral
  --links_to_pe_pages LINKS_TO_PE_PAGES [LINKS_TO_PE_PAGES ...]
                        URLs for PE results pages separated by spaces.
  --disable_pe_page_generation
                        Disable PE page generation for the input samples. This
                        option is only relevant if no URLs for PE results
                        pages are provided using --links_to_pe_pages.
  --pe_page_options PE_PAGE_OPTIONS
                        Additional options to pass to 'summarypages' when
                        generating PE webpages. All options should be wrapped
                        in quotation marks like, --pe_page_options='--
                        no_ligo_skymap --nsamples 1000 --psd...'. See
                        'summarypages --help' for details. These options are
                        added to base executable: 'summarypages --webdir {}
                        --samples {} --labels {} --gw'
  --make_diagnostic_plots
                        Make extra diagnostic plots

TGR output file

As part of the summarytgr pipelines, a pesummary metafile is produced containing all data. This metafile is, by default, called tgr_samples.h5. For details about how to read this file and extract data see the Extract information from a pesummary TGR file tutorial.

IMRCT

This test checks for consistencies between the inspiral and postinspiral estimates for the mass and spin of the final black hole in the binary black hole merger. See Ghosh et al 2018 for details. The IMRCT test can be performed by passing the --test imrct command line argument.

Note

This test requires samples from an inspiral only and postinspiral only parameter estimation analysis for one or more analyses.

You may tailor the postprocessing by passing a selection of kwargs specific to the IMRCT postprocessing (--imrct_kwargs). All kwargs are passed to the imrct_deviation_parameters_from_final_mass_final_spin function in pesummary.gw.conversions.tgr. For details about the allowed kwargs see the conversion docs. One exception is the evolve_spins_forwards kwarg. This kwarg cannot be modified via the --imrct_kwargs command line argument. Instead this is controlled with the --evolve_spins command line argument. If provided, the spins are evolved to ISCO and these are used to calculate the remnant quantities.

The approximant and cutoff-frequencies are extracted from the input files where possible and displayed on the output webpages. If you would like to override these, or provide them in the case where they cannot be extracted, this can be done with the --approximant and --cutoff_frequency command line arguments.

An example command line can be seen below:

$ summarytgr --webdir ./webpage --samples inspiral.dat postinspiral.dat \
             --test imrct --labels inspiral postinspiral \
             --imrct_kwargs N_bins:401 multi_process:16