Package: gwcatalog
AboutA Python package and a CLI that generates catalogs of standard sirens events, which currently supports the following sources:GWTC real dataLIGO forecastsLISA forecastsET forecastsTable of contentsInstallationDependenciesStable versionDevelopment versionPost installationGenerating CatalogsGWTCLIGOLISAETOther FeaturesSaving and loading catalogsPlotting catalogsChanging default cosmological modelDebugCitationFeedbackRelease cycleLicenseReferencesInstallationTo avoid conflicts the usage of virtual environments is recommended.DependenciesThis program requires Python version 3, as well as the following packages:NumpyScipyMatplotlibPandasDependencies are automatically resolved bypip.Stable versionThis program can be installed directly from PyPI with:$pipinstallgwcatalogDevelopment versionIf you wish to use this program updated to the latests commits, you can install this package directly from the development branch present in this repository:$pipinstall-egit+https://github.com/jpmvferreira/gwcatalog.git@dev#egg=gwcatalogIf instead you wish to make changes to the source code as you are using the program, start by cloning the development branch locally, followed by an installation in editable mode:$gitclone-bdevhttps://github.com/jpmvferreira/gwcatalog$pipinstall-egwcatalogPost installationYou can either use this program as a Python package or as a CLI.To ensure that the Python package is operational, import it as:importgwcatalogasgwcTo ensure that the terminal version is working, call the programgwcwith the help flag:#gwc--helpGenerating CatalogsIn this section we will show you how you can use this program to generate catalogs of standard siren events, both in Python and in the CLI.GWTCThe Gravitational Wave Transient Catalog (GWTC) is a cumulative set of gravitational wave transients maintained by the LIGO/Virgo/KAGRA collaboration, available online atgw-openscience.org.Here we provide the data found in GWTC-1, GWTC-2 and GWTC-3, with the redshifts, luminosity distances and errors coming directly from the previously mentioned database, symmetrizing both the redshift and luminosity distance error and then propagate the redshift error to the luminosity distance.These are not necessarily standard siren events, however they can be used for testing purposes.To obtain that data simply call the function with no arguments:redshifts,distances,errors=gwc.GWTC()And in the CLI:$gwcgenerateGWTCLIGOAlthough currently operational, here we will focus our efforts on generating forecast events for the Laser Interferometer Gravitational-Wave Observatory (LIGO).The redshift distribution is given in[4], while the error for each measurement is provided in[5].To generate a mock catalog for LIGO all you need is to specify the number of events.If, for example, you wish to generate a mock catalog consisting of 50 events:redshifts,distances,errors=gwc.LIGO(events=50)Being the CLI equivalent:$gwcgenerateLIGO--events50Instead of specifying the events, you can also provide a list of redshifts which you would like your catalog to have. Naturally, this will ignore the underlying redshift distribution. To create a catalog with user specified redshifts:redshifts,distances,errors=gwc.LIGO(redshifts=[0.1,0.125,0.15,0.175])And in the CLI:$gwcgenerateLIGO--redshifts'[0.1, 0.125, 0.15, 0.175]'There is also an added option to generate an ideal catalog, i.e. a catalog where all events lay on top of the theoretical line for the luminosity distance:redshifts,distances,errors=gwc.LIGO(events=50,ideal=True)Or in the CLI:$gwcgenerateLIGO--events50--idealLISAIn this subsection we will generate standard sirens mock catalogs for the Laser Interferometer Space Antenna (LISA).The redshift distribution is provided in[2], which corresponds to the mission specification L6A2M5N2, with modifications and errors as outlined in[1].To generate the LISA mock catalog you must specify two things: A population of massive black hole binaries (MBHB), either "Pop III", "Delay" or "No Delay", and specify either mission lifetime in years or the number of observed events.For example if you wish to generate the result of a 4 year mission lifetime of population "Pop III" events:redshifts,distances,errors=gwc.LISA(population="Pop III",years=4)The CLI equivalent would be:$gwcgenerateLISA--population"Pop III"--years4If instead you would like to generate 15 events of the population "No Delay":redshifts,distances,errors=gwc.LISA(population="No Delay",events=15)Or in the CLI:$gwcgenerateLISA--population"No Delay"--events15You can also ignore the underlying redshift distribution and specify the redshift for all events:redshifts,distances,errors=gwc.LISA(population="No Delay",redshifts=[1,2,3,4,5,6,7,8])Or in the CLI:$gwcgenerateLISA--population"No Delay"--redshifts'[1, 2, 3, 4, 5, 6, 7, 8, 9]'You also have the option to generate an ideal catalog, where all events lay on top of the theoretical luminosity distance:redshifts,distances,errors=gwc.LISA(population="No Delay",events=15,ideal=True)Or in the CLI:$gwcgenerateLISA--population"No Delay"--events15--idealETHere we will show how to generate a mock catalog for the Einstein Telescope (ET).Both the redshift distribution and error distribution used to generate the mock catalogs are provided in[3].To generate a mock catalog for the ET the only requirement is to provide the number of events you wish to have in your catalog.For example, if you wish to generate a mock catalog with 1000 events:redshifts,distances,errors=gwc.ET(events=1000)Being the CLI equivalent:$gwcgenerateET--events1000You can also decide to specify the redshift for each event:redshifts,distances,errors=gwc.ET(redshifts=[0.5,1,1.5])Where in the CLI you have:$gwcgenerateET--redshifts'[0.5, 1, 1.5]'And you can also have an ideal catalog, where the events lay on top of the theoretical line for the luminosity distance:redshifts,distances,errors=gwc.ET(events=1000,ideal=True)Which in the CLI is:$gwcgenerateET--events1000--idealOther FeaturesHere we list other features which are available in this package, developed in order to facilitate common operations.Saving and loading catalogsThis package also includes an easy way to save your catalogs to a.csvfile:gwc.save(redshifts,distances,errors,"catalog.csv")Which you can easily import later with:redshifts,distances,errors=gwc.load("catalog.csv")In the CLI you can also provide the output file using the-o,--outputflag, which allows you to save whatever it is that the command returns, if you want to save a LISA mock catalog:$gwc--outputcatalog.csvgenerateLISA--population"No Delay"--events15The output flag is a global flag, meaning that it should come before any subcommand.Plotting catalogsIf you are inside a Python script, you can plot your catalog, along with its label, which in this case is "catalog1", with:gwc.plot(redshifts,distances,errors,"catalog1")The CLI equivalent, where the data is stored incatalog1.csv:$gwcplot--inputcatalog1.csv--legend"catalog 1"You can provide more than one catalog, as long as the number of arguments and the order remains the same. So if you have another catalog with variablesredshift2,distances2anderrors2, and you would like to label it as "catalog2", you can have them both in the same plot with:gwc.plot(redshifts,distances,errors,"catalog1",redshifts2,distances2,errors2,"catalog2")Being the CLI equivalent, where both catalog are stored as files:$gwcplot--inputcatalog1.csvcatalog2.csv--legend"catalog 1""catalog 2"You can also plot the theoretical line of the default cosmological model, with a custom label that supports LaTeX (e.g.: "$\LambdaCDM$"):gwc.plot(redshifts,distances,errors,"catalog1",theoretical="$\LambdaCDM$")And in the CLI$gwcplot--inputcatalog1.csv--legend"catalog 1"--theoretical"$\LambdaCDM$"Changing default cosmological modelAllows you to use a custom cosmological model when generating your samples.This feature is only available in the CLI.To do so, write a Python script that defines two functions, bothH(z)anddL(z, H), and then using the-c,--cosmologyflag, point it towards the previously mentioned Python script.For example, if you wish to use a custom cosmology, defined inmycosmology.py, to generate 1000 events for ET:$gwc--cosmologymycosmology.pygenerateET--events1000This is a global flag, which means it should always be present before any of the available subcommands.Optionally, you may add a variable nameddescriptionto the previous file, that should be a string with a descriptive name of the cosmological model being used, which will be printed in the header of the generated catalogs and kept for future reference.DebugFor the sake of transparency, ease of use to check the underlying distributions is provided to the end user.For LISA, you can plot the probability redshift distribution with:gwc.LISA_dist()Being the CLI equivalent:$gwcdebugLISA--distributionAnd the error as a function of redshift with:gwc.LISA_error()With the CLI equivalent:$gwcdebugLISA--errorThe same pattern applies for the ET and LIGO, where all you have to do is replace LISA by ET or LIGO, according to your wish, where appropriate.Because GWTC includes real data there is no underlying distribution, only the data pulled directly from the GWTC catalog source.CitationThis program was developed in the context ofarXiv:2203.13788. Although it is completely independent from it, if you used any of the contents available in this repository, or found it useful in any way, you can cite it using the following BibTeX entry:@misc{Ferreira2022,
  doi = {10.48550/ARXIV.2203.13788},
  url = {https://arxiv.org/abs/2203.13788},
  author = {Ferreira, Jos\'e and Barreiro, Tiago and Mimoso, Jos\'e and Nunes, Nelson J.},
  title = {Forecasting F(Q) cosmology with $\Lambda$CDM background using standard sirens},
  publisher = {arXiv},
  year = {2022},
}FeedbackAny discussion, suggestions, pull requests or bug reports are always welcome. Feel free to use this issue section in this repository for everything else, or even send me an email at:Personal email:jose@jpferreira.me- [PGP key]Institutional email:jpmferreira@fc.ul.pt- [PGP key]If you wish to submit you code, pull requests should be targeted towards the dev branch.Release cycleAll versions will have the format X.Y.Z, with the first one being 1.0.0, which will be released as soon as I think that both the code and the documentation are good enough to be shared.Each time that there is an update which does not modify the program behavior (e.g.: documentation, packaging) it will increment Z (e.g.: 1.0.0 -> 1.0.1).Each time that there is an update which modifies the program behavior (e.g.: adding features, fixing bugs) it will increment Y and reset Z (e.g.: 1.0.1 -> 1.1.0).Each time that there is an update which is not backwards compatible (e.g.: removing features, fundamental change on how the program is used) it will increment X and reset both Y and Z (e.g.: 1.1.2 -> 2.0.0).In this repository you will find two branches: the stable branch (master) and the development branch (dev). All modifications are done in the development branch and, after being properly tested, are merged in the stable branch, with the appropriate version bump.LicenseAll of the contents provided in this repository are available under the MIT license.For further information, refer to the fileLICENSE.mdprovided in this repository.References[1]L. Speri, N. Tamanini, R. R. Caldwell, J. R. Gair, and B. Wang, Testing the quasar hubble diagram with lisa standard sirens, Physical Review D103,10.1103/physrevd.103.083526(2021).[2]C. Caprini and N. Tamanini, Constraining early and interacting dark energy with gravitational wave standard sirens: the potential of the elisa mission,Journal of Cosmology and Astroparticle Physics2016(10), 006–006.[3]E. Belgacem, Y. Dirian, S. Foffa, and M. Maggiore, Modified gravitational-wave propagation and standard sirens, Physical Review D 98,10.1103/physrevd.98.023510(2018).[4]M. Lagos, M. Fishbach, P. Landry, and D. E. Holz, Standard sirens with a running planck mass, Physical Review D 99,10.1103/physrevd.99.083504(2019).[5]T. Baker and I. Harrison, Constraining scalar-tensor modified gravity with gravitational waves and large scale structure surveys,Journal of Cosmology and Astroparticle Physics 2021 (01), 068–068.