# 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](https://dcc.ligo.org/LIGO-P2100239/public) , [arXiv](https://arxiv.org/abs/2111.03634) 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](mailto:alan.weinstein@ligo.org) ; 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](https://pypi.org/project/bilby/) and [gwpopulation](https://pypi.org/project/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!