Gather Summary Statistics (ligo-skymap-stats)

Calculate summary statistics for a batch of sky maps.

Under the hood, this script is little more than a command-line interface for the ligo.skymap.postprocess.crossmatch module.

The filenames of the sky maps may be provided as positional command line arguments, and may also be provided as globs (such as *.fits.gz). If supplied with the optional --database argument, then also match sky maps with injections from an inspinjfind-style sqlite database.

All angular separations are in degrees, all areas are in square degrees, and all volumes are in cubic megaparsecs. The output is written as tab-separated values with the following columns:

From the search pipeline database
coinc_event_id	event identifier
simulation_id	injection identifier
far	false alarm rate
snr	signal to noise ratio
Injection finding
searched_area	area of 2D credible region containing the true sky location
searched_prob	probability in that 2D credible region
searched_prob_dist	marginal distance CDF at the true distance
searched_vol	volume of 3D credible region containing the true position
searched_prob_vol	probability contained in that volume
offset	angular separation between the maximum a posteriori position and the true sky position
Additional metadata from the sky maps
runtime	wall clock run time to generate sky map
distmean	mean a posteriori distance
diststd	a posteriori standard deviation of distance
log_bci	natural log Bayes factor, coherent vs. incoherent
log_bsn	natural log Bayes factor, signal vs. noise
Credible levels (if --area or --contour options present)
area(P)	area of the P percent 2D credible region
prob(A)	probability contained within the 2D credible level of area A
dist(P)	distance for a cumulative marginal probability of P percent
vol(P)	volume of the P percent 3D credible region
Modes (if --modes option is present)
searched_modes	number of simply connected figures in the 2D credible region containing the true sky location
modes(P)	number of simply connected figures in the P percent 2D credible region

usage: ligo-skymap-stats [-h] [--version]
                         [-l CRITICAL|ERROR|WARNING|INFO|DEBUG|NOTSET]
                         [-o OUT.dat] [-j [JOBS]] [-p PERCENT [PERCENT ...]]
                         [-a DEG2 [DEG2 ...]] [--modes] [-d DB.sqlite]
                         [--cosmology]
                         GLOB.fits[.gz] [GLOB.fits[.gz] ...]

Positional Arguments

GLOB.fits[.gz]

Input FITS filenames and/or globs

Named Arguments

--version

show program’s version number and exit

-l, --loglevel

Default: INFO

-o, --output

Name of output file

Default: -

-j, --jobs

Number of threads

Default: 1

-p, --contour

Report the area of the smallest contour and the number of modes containing this much probability.

Default: []

-a, --area

Report the largest probability contained within any region of this area in square degrees. Can be repeated multiple times.

Default: []

--modes

Compute number of disjoint modes

Default: False

-d, --database

Input SQLite database from search pipeline

--cosmology

Report volume localizations as comoving volumes.

Default: False