README for GWTC-3-population-data

Welcome to the GWTC-3-population data release, associated with the LIGO-Virgo-KAGRA paper: The population of merging compact binaries inferred using gravitational waves through GWTC-3 LIGO dcc , arXiv

This is a rather large and complex data release. It is also preliminary - it will be updated when the paper is accepted by the journal. If you see any problems, please alert us ; thank you!

Description

  • Tables I, II, III, IV, XV, and XVI contain numerical data (the others only contain textual descriptions of the priors used). The files in table_data.tar.gz are csv files that can be read in by excel, google sheets, or pandas.DataFrame. Unpack with tar xzvf table_data.tar.gz .

  • The python notebook snapshot PowerLaw_Peak_DipBreak_Spline_Tutorial.html is intended to show readers how to load in the data associated with some of the gwpopulation-based models used in this paper, and make some plots.

  • The file paper_figures.tar.gz contain png or pdf files of all the figures in the paper. Unpack with tar xzvf paper_figures.tar.gz .

  • The file GWTC-3-population-data.tar.gz (10 GB!!) contains:

    • Makefile for running all of the figure_scripts.
    • py_requirements.txt lists the packages that you will need to install in your python environment (see below).
      This includes some LVK-specific software: bilby and gwpopulation.
    • tutorials/PowerLaw_Peak_DipBreak_Spline_Tutorial.ipynb contains the python-3.8 notebook mentioned above. It is designed to be run in the tutorials directory, with a python environment that includes bilby and gwpopulation. Note that these are example plots, which don't necessarily correspond to the figures in the paper.
    • figure_scripts/ contains python scripts for making all the figures in the paper from many different sources of input data.
    • utils/ contains some utility scripts used to make figures.
    • analysis/ contains data products associated with many of the analyses described in the paper.
    • postproc/ contains post-processing files derived from upstream data, needed to make many of the figures in the paper.
    • injections/ contains files of signal injections for evaluating search sensitivity. You will need to download those files; see below.
    • o3a_population_data_release/ contains the data release from the paper: Population Properties of Compact Objects from the Second LIGO-Virgo Gravitational-Wave Transient Catalog arxiv.org/abs/2010.14533, Published in Astrophys. J. Lett. 913, L7 (2021) You will need to download those files; see below.
    • external_catalog_data/ contains data releases from other GW catalogs. You will need to download those files; see below.

Instructions

  • Your computer should know how to run make and latex (and probably other standard linux-based scientific computing tools). You will need at least 50 GB of storage available.

  • Download GWTC-3-population-data.tar.gz (10 GB) into your chosen working directory (we'll call it $ROOT) and un-tar it (tar xzvf GWTC-3-population-data.tar.gz). This will create the directory (folder) GWTC-3-population-data, and all the sub-directories listed above. After that, you can rm GWTC-3-population-data.tar.gz if you like.

  • Set up your python environment, and install GWTC-3-population-data/py_requirements.txt into it. If you are using conda:

conda create -n GWTC-3-population;
conda activate GWTC-3-population;
conda install python==3.8;
pip install -r py_requirements.txt

You can do this in any directory, but it should point to py_requirements.txt. If you prefer, you can do conda install -r py_requirements.txt instead of pip.

  • Download and install already-public data:

    • cd $ROOT/GWTC-3-population-data/injections ; ./download_injections.sh
    • cd $ROOT/GWTC-3-population-data/o3a_population_data_release ; ./download_o3a_population_data_release.sh
    • cd $ROOT/GWTC-3-population-data/external_catalog_data ; ./download_external_catalog_data.sh
  • Now run the Makefile: cd $ROOT/GWTC-3-population-data ; make

    • This can take up to an hour or more (you can say make -j 4 if you have a multi-core computer). Many of the figure scripts are re-doing long computations.
    • If you've downloaded everything successfully, there shouldn't be any errors and the Makefile will run to completion.
    • There will be numerous warnings, but they are all ignorable! (For now).
    • The Makefile will populate the (initially empty) directory figures/ with all the figures produced by the figure_scripts.
    • These figures should look very similar to what's in the paper, but not exactly the same. This is because many figure scripts choose PE samples randomly, and they don't (yet) specify a random number seed. We intend to fix this for the updated data release associated with the published paper. For now, it's a feature!