.. GlitchPop documentation master file, created by
   sphinx-quickstart on Aug  20 2024.

Welcome to GlitchPop's documentation!
====================================

GlitchPop is a small `Python <http://www.python.org>`_ package
providing tools for simulating gravitational wave (GW) time series strain data. In short, GlitchPop adds parametrized glitch models to the pre-existing methods for generating Gaussian noise and GW waveforms to fully simulate an interferometer's calibrated strain channel.

GlitchPop provides user-friendly and intuitive documentation that breaks down each python module. If you are interested in adding additional parametrized glitch models to the workflow, please add them to the 'scatter' module.

Short Transient Glitches
---------------

Although GlitchPop aims to simulate an interferometer's entire calibrated strain channel, it is mainly concerned with simulating the 'short transient glitches'. The short transient glitches, consisting of blips, low frequency blips, tomtes and koi fish, are known to usually last 5 - 10 ms (but up to 100 ms) and are some of the most common LIGO-Virgo glitches. Due to their short duration, they often mimic high mass binary black hole signals and set off false alarms.

.. figure:: _static/images/sgt.png
   :alt: Spectrograms of each of the short transient glitches.
   :width: 500px
   :height: 400px
   :align: center

   **Figure:** Starting top left and going clockwise; spectrograms of blip, tomte, koi fish and low frequency blip. All spectrograms were generated using GlitchPop and its dependencies.

Subsections
---------------

The GlitchPop documentation is split into 4 subsections and an easy-to-follow examples folder. The 4 subsections are utility files, simulations, injection files and extra populations.

.. toctree::
   :maxdepth: 1

   Utility files/index

.. toctree::
   :maxdepth: 1

   Simulations/index

.. toctree::
   :maxdepth: 1

   Injection files/index

.. toctree::
   :maxdepth: 1

   Extra populations/index

.. toctree::
   :maxdepth: 1

   examples/index

Installation
---------------
The easiest way to install GlitchPop is to use 'pip'. To do so, follow these steps:

1. **Clone the Repository** (if necessary):

   If you want to work with the source code directly, clone the repository:

   .. code-block:: python

      git clone https://git.ligo.org/sean.collins/glitchpop.git
   
      cd glitchpop


2. Install via pip

   .. code-block:: python
   
      pip install git+https://git.ligo.org/sean.collins/glitchpop.git@main


Authors and Acknowledgements
---------------
This project was developed by Sean Collins at the University of British Columbia (UBC), under the supervision of Jess McIver and Raymond Ng at UBC. This project is directly built off the work from Ruxandra Bondarescu, Andrew Lundgren and Ronaldas Macas (https://arxiv.org/abs/2309.06594). I also thank Rhiannon Udall for providing the light scattering models, the UBC LIGO team for all their feedback and suggestions, and the Natural Sciences and Engineering Research Council of Canada (NSERC) for their financial support through an Undergraduate Student Research Award.

This project also makes use of the following libraries:

- **GWpy**: A Python package for gravitational-wave astrophysics. If you use GWpy in your work, please cite the following DOI:

  GWpy: https://zenodo.org/records/846265

- **PyCBC**: A library for gravitational wave data analysis. If you use PyCBC in your work, please cite the following DOI:

  PyCBC: https://zenodo.org/records/10473621