Using gwpopulation_pipe

The format of gwpopulation_pipe is based on the bilby_pipe package. The most important executables are:

gwpopulation_pipe - the main executable that builds a bash script for local use and HTCondor for submission to a computing cluster. If you’re interested in SLURM support please let us know.
gwpopulation_pipe_collection - reads in posterior samples for individual events and combines them into a single file containing the requested parameters and files containing data products used to estimate the search sensitivity, which are also downsampled.
gwpopulation_pipe_analysis - reads in the output of gwpopulation_pipe_collection and performs the population analysis using Bilby and/or numpyro.
gwpopulation_pipe_plot - makes plots of the results of the population analysis.
gwpopulation_pipe_to_common_format - converts the result files to the common format for LVK population analyses.

`gwpopulation_pipe` help

Other documentation pages describe how to specify some of these arguments in more detail, but here is a brief overview of the command line arguments for gwpopulation_pipe.

For reference, here is the full output of

$ gwpopulation_pipe --help

usage: gwpopulation_pipe [-h] [-v] [--version] [--run-dir RUN_DIR]
                         [--log-dir LOG_DIR] [--label LABEL] [--user USER]
                         [--vt-file VT_FILE]
                         [--vt-ifar-threshold VT_IFAR_THRESHOLD]
                         [--vt-snr-threshold VT_SNR_THRESHOLD]
                         [--vt-function VT_FUNCTION] [--prior-file PRIOR_FILE]
                         [--request-gpu REQUEST_GPU]
                         [--require-gpus REQUIRE_GPUS]
                         [--backend {numpy,cupy,jax}] [--cosmo COSMO]
                         [--cosmology COSMOLOGY] [--container CONTAINER]
                         [--conda-env CONDA_ENV] [--pool {osg,local}]
                         [--all-models ALL_MODELS]
                         [--source-files SOURCE_FILES]
                         [--existing-data-directory EXISTING_DATA_DIRECTORY]
                         [--parameters PARAMETERS] [--ignore IGNORE]
                         [--sample-regex SAMPLE_REGEX]
                         [--preferred-labels PREFERRED_LABELS] [--plot PLOT]
                         [--n-simulations N_SIMULATIONS]
                         [--samples-per-posterior SAMPLES_PER_POSTERIOR]
                         [--collection-seed COLLECTION_SEED]
                         [--data-label DATA_LABEL]
                         [--distance-prior DISTANCE_PRIOR]
                         [--mass-prior MASS_PRIOR] [--spin-prior SPIN_PRIOR]
                         [--max-redshift MAX_REDSHIFT]
                         [--minimum-mass MINIMUM_MASS]
                         [--maximum-mass MAXIMUM_MASS] [--sampler SAMPLER]
                         [--sampler-kwargs SAMPLER_KWARGS]
                         [--vt-parameters VT_PARAMETERS]
                         [--enforce-minimum-neffective-per-event ENFORCE_MINIMUM_NEFFECTIVE_PER_EVENT]
                         [--maximum-uncertainty MAXIMUM_UNCERTAINTY]
                         [--periodic-restart-time PERIODIC_RESTART_TIME]
                         [--injection-file INJECTION_FILE]
                         [--injection-index INJECTION_INDEX]
                         [--sample-from-prior SAMPLE_FROM_PRIOR]
                         [--post-plots POST_PLOTS]
                         [--make-summary MAKE_SUMMARY]
                         [--n-post-samples N_POST_SAMPLES]
                         [--make-popsummary-file MAKE_POPSUMMARY_FILE]
                         ini

Positional Arguments

ini: Configuration ini file

Named Arguments

-v, --verbose

Verbose output

Default: False

--version

show program’s version number and exit

Generic arguments

Generic arguments

--run-dir

Output directory for posterior samples

Default: 'outdir'

--log-dir

Output directory for writing log files

Default: 'logs'

--label

Run label

Default: 'label'

--user

User name

--vt-file

File to load VT data from or a glob string matching multiple files to combine.

--vt-ifar-threshold

IFAR threshold for resampling injections

Default: 1

--vt-snr-threshold

IFAR threshold for resampling injections. This is only used for O1/O2 injections

Default: 11

--vt-function

Function to generate selection function from.

Default: 'injection_resampling_vt'

--prior-file

Prior file containing priors for all considered parameters

--request-gpu

Whether to request a GPU for the relevant jobs.

Default: 0

--require-gpus

The GPU requirements to pass for HTCondor.

Default: 'DeviceName=="GeForce GTX 1050 Ti"'

--backend

Possible choices: numpy, cupy, jax

The backend to use for the analysis, default is jax

Default: 'jax'

--cosmo

Whether to fit cosmological parameters.

Default: False

--cosmology

Cosmology to use for the analysis, this should be one of FlatLambdaCDM, FlatwCDM, WMAP1, WMAP3, WMAP5, WMAP7, WMAP9, Planck13, Planck15, Planck18, Planck15_LAL. Some of these are fixed pre-defined cosmologies while others are parameterized cosmologies. If a parameterized cosmology is used the parameters relevant parameters should be included in the prior specification.

Default: 'Planck15_LAL'

--container

The path to the singularity image to use

--conda-env

The conda environment to use

--pool

Possible choices: osg, local

Which HTCondor pool to submit to, if osg, the local pool is also allowed

Default: 'osg'

Analysis models

Analysis models

--all-models: All models to use, formatted as a json string
--source-files: Files containing source models to use for user-defined models. These files are transferred to the execute node when using the HTCondor file transfer mechanism. If the job is being run locally the file should be in the users PYTHONPATH.

Data collection arguments

Data collection arguments

--existing-data-directory

Directory containing existing data

Default: '/fail'

--parameters

Parameters that are fit with the model. These are the parameters that will be extracted from the posterior samples and should follow Bilby naming conventions with the exception that all masses are assumed to be in the source frame. Here is a list of parameters for which prior factors will be properly accounted. mass_1: source frame primary mass, mass_2: source frame secondary mass, mass_1_detector: detector frame primary mass, mass_2_detector: detector frame secondary mass, chirp_mass: source frame chirp mass, chirp_mass_detector: detector frame chirp mass,mass_ratio: mass ratio, redshift: redshift, luminosity_distance: luminosity distance,a_1: primary spin magnitude, a_2: secondary spin magnitude, cos_tilt_1: cosine primary spin tilt, cos_tilt_2: cosine secondary spin tilt, chi_1: aligned primary spin, chi_2: aligned secondary spin.Any other parameters will be assumed to have a flat prior.These parameters are also used to set the fiducial prior values. No redundancy checks are performed so users should be careful to not include unused parameters as that may have unintended consequences.

--ignore

Events to ignore.

--sample-regex

Pattern to match for sample files

--preferred-labels

Run labels to search for in sample files

--plot

Whether to generate diagnostic plots

Default: True

--n-simulations

Number of posteriors to simulate

--samples-per-posterior

Number of samples per posterior. If larger than the number of samples in the shortest posterior dataset, will ignore this input.

Default: 1000000

--collection-seed

Seed for the downsampling of the posteriors for each event. For reproducibility.

--data-label

Label for data product.

Default: 'posteriors'

--distance-prior

Distance prior format, e.g., euclidean, comoving. ‘euclidean’ assumes the distance prior goes like D^2. ‘comoving’ assumes sources are uniformly distributed in the comoving frame using the Planck15_LAL cosmology. Can be in the format of a dict with the same keys as the sample-regex

Default: 'comoving'

--mass-prior

Mass prior used during the initial sampling, must match one of the following options.: ‘flat-detector’: Flat in detector frame primary and secondary masses. ‘chirp-mass’: Flat in detector frame chirp mass and mass ratio. ‘flat-detector-components’: Flat in detector frame primary and secondary masses. This is the default for LVK samples and the same as the deprecated ‘flat-detector’ option. ‘flat-source-components’: Flat in source frame primary and secondary masses. ‘flat-detector-chirp-mass-ratio’: Flat in detector frame chirp mass and mass ratio. This is the same as the deprecated ‘chirp-mass’ option. Can be in the format of a dict with the same keys as the sample-regex

Default: 'flat-detector'

--spin-prior

Spin prior, the only supported spin prior assumes the spins are isotropically distributed with a flat prior on the magnitude. Can be in the format of a dict with the same keys as the sample-regex.

Default: 'component'

Arguments describing analysis jobs

Analysis arguments

--max-redshift

The maximum redshift considered, this should match the injections.

Default: 2.3

--minimum-mass

The minimum mass considered, this should match the injections and is important for smoothed mass models.

Default: 2

--maximum-mass

The maximum mass considered, this should match the injections and is important for smoothed mass models.

Default: 100

--sampler

The sampler to use, the default is dynesty

Default: 'dynesty'

--sampler-kwargs

Dictionary of sampler-kwargs to pass in, e.g., {nlive: 1000} OR pass pre-defined set of sampler-kwargs {Default, FastTest}

Default: 'Default'

--vt-parameters

Which parameters to include in the VT estimate, should be some combination of mass, redshift, spin parameters, see the ‘–parameters’ option for more details.

--enforce-minimum-neffective-per-event

Require that all Monte Carlo integrals for the single event marignalizaed likleihoods have at least as many effective samples as the number of events.

Default: True

--maximum-uncertainty

Require that all log likelihood evaluations have an uncertainty (standard deviation) less than this value. It is not recommended to use with the ‘–enforce-minimum-neffective-per-event’ option.See Talbot and Golomb (2023) arxiv:2304.06138

Default: inf

--periodic-restart-time

The periodic restart time for running on HTCondor, this should be set when using the HTCondor file transfer system to avoid losing progress on eviction. See https://computing.docs.ligo.org/guide/htcondor/checkpointing/ for more details.

Arguments describing injections

Injection arguments

--injection-file: JSON file containing population parameters, should be pandas readable.
--injection-index: Index in injection file to use.
--sample-from-prior: Simulate posteriors from prior.

Post processing arguments

Post arguments

--post-plots

Whether to make post-processing plots.

Default: True

--make-summary

Whether to make a summary page.

Default: True

--n-post-samples

Number of samples to use in the common format script

Default: 5000

--make-popsummary-file

Whether to make a summary result file in popsummary format.

Default: True

Using gwpopulation_pipe

gwpopulation_pipe help

Positional Arguments

Named Arguments

Generic arguments

Analysis models

Data collection arguments

Arguments describing analysis jobs

Arguments describing injections

Post processing arguments

`gwpopulation_pipe` help