Package: gengli
gengligengli(generating glitches) is a package to provide an handy an easy to use interface to CTGAN, a generative adversarial neural network to generate glitches. A "glitch" is a non stationary noise transient recorded in Gravitational Waves (GW) interferometer. As it resembles some GW signals, their appearece hinders the searches for such signal, downgrading the instrument sensitivity.
A nice characterization of glitches can enable lots of exciting GW science!This network is trained with real (although heavily preprocessed) glitch and when given some random noise, it outputs a whithened glitch.genglioffers a simple API to access the network, enabling some post-processing of the generated glitch that can be useful for downstream analysis. In more, details it allow the user to:Resample the glitchLowpass (i.e. removing spurious high frequency content) and windowScale it to achieve a target SNRSelect among random glitches only those within a given percentile w.r.t. to some anomaly score (more on the paper). This enables the user to get only "normal" glitches and/or "atypical" glitches.You can read the full documentationhere!How to installTo install the latest released version of gengli, available on PyPI:pipinstallgengliFrom the repoIf you want to install the code from this repo, you can use theMakefileprovided:gitclonehttps://git.ligo.org/melissa.lopez/gengli.gitcdgengli
makeinstallIf you want to build a local version of the documention, just typemake docs. This will create the folderdocs/__build/where all the relevant html docs will be located.With a conda environmentIf you don't want to mess up with your existing conda installations, this will create a fresh new conda environment that only containsgengliand its dependencies:condacreate--namegengli_envpython=3.9
condaactivategengli_env
gitclonehttps://git.ligo.org/melissa.lopez/gengli.gitcdgengli
pythonsetup.pysdist
pipinstalldist/gengli-0.1.0.tar.gzA ready made conda environment is also provided inenv.yml.
To use it just type:condaenvcreate--fileenv.ymlThis will create an environment with all the dependencies (andgengliinstalled)How to generate a glitchTo generate a glitch, you will need to instantiate aglitch_generatorobject:importgenglig=gengli.glitch_generator('L1')You should provide the generator the weights of the generator network. Some default (and reviewed) weights are relaesed with this package: if you want to use them, you should just pass the stringL1orH1to specify which interferometer you want to consider and the weights will be loaded authomatically.To generate the raw glitch (as output by the network):g_raw=g.get_glitch()The glitch is whithened and evaluted on a default time grid sampled at 4096Hz. It has a characteristic shape:The functionget_glitchalso provides an easy to use API to the post-processing operations described above. For instance, to generate 10 glitches, filtered and windowed with an SNR of 15 and evaluated at a lower sampling rate, you can just type:g_processed=g.get_glitch(10,srate=2048,snr=15,alpha=0.2,fhigh=250)The generated glitches will look quite different from before:If you want to get three anomalous glitches, you can play with thepercentilesparameter ofget_glitch_confidence_interval. For instance:g.get_glitch_confidence_interval(percentiles=(0,80),n_glitches=3,snr=20)This will take a while to run as it will call internally (only once)glitch_generator.initialize_benchmark_set, which creates a set of benchmark glitches to compute the "anomaly score" against.
To have more controls of the parameters ofinitialize_benchmark_set, you can call it from your script: you will note that, once such initialization is done,get_glitchwill run much faster!You can take a look at someexamplesin a dedicated folder.For more information, you can read thedocs.AboutThis project is developed in the GW group at Utrecht Univerisity. Many people were involved in this project:Vincent BoudartKerwin BuijsmanSarah CaudillMelissa Lopez (corresponding author:m.lopez@uu.nl)Amit RezaStefano Schmidt (package maintener:s.schmidt@uu.nl)If you want to have more information, or just to say hello, please feel free to contact any of us!PublicationsIf you find our work useful, please consider reading and citing our publications.The main work, detailing the method and its performances, is the following:@article{Lopez:2022lkd,
    author = "Lopez, Melissa and Boudart, Vincent and Buijsman, Kerwin and Reza, Amit and Caudill, Sarah",
    title = "{Simulating transient noise bursts in LIGO with generative adversarial networks}",
    eprint = "2203.06494",
    archivePrefix = "arXiv",
    primaryClass = "astro-ph.IM",
    doi = "10.1103/PhysRevD.106.023027",
    journal = "Phys. Rev. D",
    volume = "106",
    number = "2",
    pages = "023027",
    year = "2022"
}A follow up paper describesgengliand its features, providing more details on the network architecture and training:@article{Lopez:2022dho,
    author = "Lopez, Melissa and Boudart, Vincent and Schmidt, Stefano and Caudill, Sarah",
    title = "{Simulating Transient Noise Bursts in LIGO with gengli}",
    eprint = "2205.09204",
    archivePrefix = "arXiv",
    primaryClass = "astro-ph.IM",
    month = "5",
    year = "2022"
}