glitchgan 0.1.0__tar.gz

glitchgan-0.1.0/.gitattributes

@@ -0,0 +1 @@
+*pkl filter=lfs diff=lfs merge=lfs -text

glitchgan-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Build distributions
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          pip install build
+          python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publisher (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

glitchgan-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Data (too large for git — see README for download instructions)
+data/
+
+# Generated outputs
+evaluation_plots/
+plots/
+GAN_outputs*/
+
+# GravitySpy model weights (large binary — download separately)
+models/
+
+# PyTorch weights (not part of published release)
+weights/pytorch/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+src/cdvgan/_version.py
+src/glitchgan/_version.py
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment
+.env
+*.log
+
+# macOS
+.DS_Store
+
+# Classification output CSVs
+notebooks/*.csv
+
+# Sphinx docs build + auto-copied notebooks (canonical copies live in notebooks/)
+docs/_build/
+docs/notebooks/

glitchgan-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

glitchgan-0.1.0/MODEL_CARD.md

@@ -0,0 +1,146 @@
+---
+license: mit
+tags:
+  - gravitational-waves
+  - time-series
+  - generative-model
+  - gan
+  - ligo
+  - detector-characterization
+  - physics
+library_name: keras
+pipeline_tag: time-series-to-time-series
+---
+
+# GlitchGAN — Synthetic LIGO Glitch Generator
+
+GlitchGAN is a class-conditional generative model that synthesizes realistic
+gravitational-wave detector glitches directly in the time domain.
+It is built on the **cDVGAN** (Conditional Derivative GAN) architecture,
+which uses a first-derivative discriminator alongside the standard signal
+discriminator to enforce temporal smoothness in generated waveforms.
+
+The model is trained on high-quality glitch reconstructions produced by
+[DeepExtractor](https://github.com/fbianco/deepextractor), a U-Net framework
+for glitch reconstruction from LIGO strain data, covering seven common glitch
+classes observed during LIGO's third observing run (O3).
+
+## Supported glitch classes
+
+| Index | Class | Description |
+|-------|-------|-------------|
+| 0 | Blip | Short, broadband transient |
+| 1 | Fast\_Scattering | Arches at low frequency from scattered light |
+| 2 | Koi\_Fish | Low-frequency dispersive burst |
+| 3 | Low\_Frequency\_Burst | Broadband low-frequency transient |
+| 4 | Scattered\_Light | Repeated arch pattern from optical scattering |
+| 5 | Tomte | Short, low-frequency transient |
+| 6 | Whistle | Narrow-band high-frequency chirp |
+
+## Quick start
+
+```bash
+pip install glitchgan
+```
+
+```python
+from cdvgan import GlitchGAN
+
+# Download pretrained weights automatically (cached after first call)
+model = GlitchGAN.from_pretrained()
+
+# Generate 10 Blip glitches at SNR 50
+blips = model.generate("Blip", n=10, snr=50)
+# blips.shape → (10, 8192)  — 2 s at 4096 Hz
+
+# Generate a mix of classes
+glitches = model.generate(["Blip", "Tomte", "Whistle"], n=3, snr=30)
+
+# Class interpolation — hybrid Blip/Koi Fish morphology
+hybrids = model.interpolate([0.5, 0, 0.5, 0, 0, 0, 0], n=5)
+```
+
+Output waveforms are 2-second segments at 4096 Hz (8192 samples).
+Pass `snr=None` (default) to get the raw normalized generator output,
+or specify a target SNR to rescale to a physically meaningful amplitude.
+
+## Model details
+
+| Property | Value |
+|----------|-------|
+| Architecture | cDVGAN (conditional WGAN-GP + derivative discriminator) |
+| Signal length | 8192 samples (2 s at 4096 Hz) |
+| Noise dim | 100 |
+| Num classes | 7 |
+| Training epochs | 210 |
+| Optimizer | RMSprop (lr=1e-4) |
+| Gradient penalty weight | 10 |
+| Framework | TensorFlow / Keras 3 |
+
+## Training data
+
+The model was trained on DeepExtractor reconstructions of real LIGO glitches
+from O3 (2019–2020), curated using [Gravity Spy](https://www.zooniverse.org/projects/zooniverse/gravity-spy)
+classifications.
+Seven glitch classes were selected with balanced class sizes.
+Waveforms are whitened and normalized before training; the generator
+therefore learns a normalized waveform distribution and SNR scaling is
+applied at inference time.
+
+## Evaluation
+
+Synthetic glitches were evaluated against real data using:
+
+1. **Gravity Spy classification** — the fraction of generated samples
+   correctly classified by the state-of-the-art Gravity Spy classifier.
+2. **UMAP embeddings** — unsupervised 3-D projections to compare the
+   morphological distributions of real and synthetic samples.
+
+Selected Gravity Spy results at SNR 100 (100 samples per class):
+
+| Class | Accuracy |
+|-------|----------|
+| Blip | 88% |
+| Fast Scattering | 72% |
+| Koi Fish | 20% (SNR-sensitive; 79% at SNR 150) |
+| Low Frequency Burst | 100% |
+| Scattered Light | 42% (often confused with Fast Scattering) |
+| Tomte | 92% |
+| Whistle | 94% |
+
+UMAP embeddings show strong overlap between real and synthetic samples
+for most classes. Whistle glitches show partial separation, attributed to
+the model's difficulty with fine-scale high-frequency structure.
+
+## Limitations
+
+- **SNR sensitivity**: GlitchGAN does not model an SNR distribution.
+  Generated waveforms must be manually rescaled. Classification accuracy
+  for morphologically ambiguous classes (Koi Fish, Scattered Light) is
+  strongly SNR-dependent.
+- **Whistle class**: Synthetic Whistle glitches form a partially distinct
+  cluster from real data in UMAP space, indicating incomplete capture of
+  high-frequency structure.
+- **Seven classes only**: The model covers the seven classes present in
+  the O3 training set. It cannot generate unseen glitch morphologies.
+- **LIGO-specific**: Trained on LIGO H1/L1 data. Generalization to Virgo
+  or KAGRA data has not been evaluated.
+
+## Citation
+
+If you use GlitchGAN in your work, please cite:
+
+```bibtex
+@article{Dooney2026GlitchGAN,
+  title   = {Realistic Time-Domain Synthesis of Gravitational-Wave Detector
+             Glitches using Class-Conditional Derivative Generative Adversarial Networks},
+  author  = {Dooney, Tom and de Boer, Mees and Narola, Harsh and Lopez, Melissa
+             and Bromuri, Stefano and Tan, Daniel Stanley and Van Den Broeck, Chris},
+  journal = {Physical Review D},
+  year    = {2026},
+}
+```
+
+## License
+
+MIT

glitchgan-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: glitchgan
+Version: 0.1.0
+Summary: Synthetic LIGO gravitational-wave glitch generator (cDVGAN architecture)
+Author-email: Tom Dooney <tom.dooney95@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/tomdooney95/glitchgan
+Project-URL: Documentation, https://glitchgan.readthedocs.io/
+Keywords: gravitational-waves,LIGO,GAN,glitch,machine-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: huggingface_hub>=0.23
+Requires-Dist: tensorflow>=2.16
+Requires-Dist: keras>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: sphinx-autoapi>=3; extra == "docs"
+Requires-Dist: furo>=2024.1.29; extra == "docs"
+Requires-Dist: myst-parser>=3; extra == "docs"
+Requires-Dist: nbsphinx>=0.9; extra == "docs"
+Provides-Extra: all
+Requires-Dist: glitchgan[dev,docs]; extra == "all"
+
+# GlitchGAN
+
+Conditional Dual-discriminator Variational GAN (cDVGAN) for synthesising LIGO gravitational-wave glitch signals. Trained on seven Gravity Spy glitch classes from the O3 observing run.
+
+## Overview
+
+GlitchGAN uses a Wasserstein GAN with gradient penalty (WGAN-GP) augmented by a first-derivative discriminator. The derivative discriminator encourages the generator to produce signals with realistic time-domain structure, not just realistic amplitude distributions.
+
+**Architecture:** Generator + Discriminator + Derivative Discriminator  
+**Classes:** Blip, Fast Scattering, Koi Fish, Low Frequency Burst, Scattered Light, Tomte, Whistle  
+**Signal length:** 8192 samples @ 4096 Hz (~2 s)  
+
+## Repository structure
+
+```
+glitchgan/
+├── evaluation.ipynb          # UMAP + GravitySpy evaluation notebook
+├── src/cdvgan/
+│   ├── tf/
+│   │   ├── model_components.py   # Generator / discriminator layers
+│   │   ├── gan_models.py         # cWGAN, cDVGAN, cDVGAN2, GlitchGAN
+│   │   ├── train.py              # Training entry point
+│   │   └── utils.py              # Dataset, callbacks, checkpointing
+│   └── utils.py                  # Signal processing utilities
+├── weights/tensorflow/
+│   └── generator_210_keras3.keras   # Trained generator (epoch 210)
+├── models/                       # GravitySpy CNN weights (gitignored — see below)
+├── data/                         # Training data (gitignored — see below)
+└── environment.yml
+```
+
+## Setup
+
+```bash
+conda env create -f environment.yml
+conda activate cdvgan
+```
+
+The environment installs TensorFlow, Keras 3, GWpy, PyCBC, umap-learn, and GravitySpy.
+
+> **Note:** `environment.yml` targets Apple Silicon (tensorflow-macos / tensorflow-metal). On Linux/HPC replace those with `tensorflow` and remove `tensorflow-metal`.
+
+## Data
+
+The training data (~2.3 GB) is not included in this repository.
+
+**Download from Zenodo:** *(link TBD — will be added before publication)*
+
+Place the downloaded files in `data/`:
+
+```
+data/
+├── glitch_GAN_samples_scaled_balanced.npy   # (N, 8192) float32 signals
+├── glitch_GAN_labels_balanced.npy           # (N, 7) one-hot labels
+└── glitch_GAN_label_order.npy               # class name ordering
+```
+
+## GravitySpy model
+
+The GravitySpy O3 CNN (`sidd-cqg-paper-O3-model.h5`) is not included. It ships with the `gravityspy` package or can be found in a local GravitySpy clone.
+
+1. Install GravitySpy: `pip install gravityspy`
+2. Copy the model to `models/sidd-cqg-paper-O3-model.h5`
+3. Set `PATH_TO_REPO` in `evaluation.ipynb` to your GravitySpy clone path
+
+## Training
+
+```bash
+python -m cdvgan.tf.train \
+    --data-dir data/ \
+    --variant cDVGAN \
+    --epochs 500 \
+    --output-dir GAN_outputs/
+```
+
+See `src/cdvgan/tf/train.py` for all options.
+
+## Evaluation
+
+Open `evaluation.ipynb` and run all cells. The notebook:
+
+1. Loads real glitch data and the trained generator
+2. Visualises real vs generated waveforms
+3. Embeds real and generated signals jointly in 3D UMAP space (correlation metric)
+4. Injects generated signals into whitened H1 background and classifies with GravitySpy
+
+## Citation
+
+*(BibTeX will be added upon publication)*

glitchgan-0.1.0/README.md

@@ -0,0 +1,89 @@
+# GlitchGAN
+
+Conditional Dual-discriminator Variational GAN (cDVGAN) for synthesising LIGO gravitational-wave glitch signals. Trained on seven Gravity Spy glitch classes from the O3 observing run.
+
+## Overview
+
+GlitchGAN uses a Wasserstein GAN with gradient penalty (WGAN-GP) augmented by a first-derivative discriminator. The derivative discriminator encourages the generator to produce signals with realistic time-domain structure, not just realistic amplitude distributions.
+
+**Architecture:** Generator + Discriminator + Derivative Discriminator  
+**Classes:** Blip, Fast Scattering, Koi Fish, Low Frequency Burst, Scattered Light, Tomte, Whistle  
+**Signal length:** 8192 samples @ 4096 Hz (~2 s)  
+
+## Repository structure
+
+```
+glitchgan/
+├── evaluation.ipynb          # UMAP + GravitySpy evaluation notebook
+├── src/cdvgan/
+│   ├── tf/
+│   │   ├── model_components.py   # Generator / discriminator layers
+│   │   ├── gan_models.py         # cWGAN, cDVGAN, cDVGAN2, GlitchGAN
+│   │   ├── train.py              # Training entry point
+│   │   └── utils.py              # Dataset, callbacks, checkpointing
+│   └── utils.py                  # Signal processing utilities
+├── weights/tensorflow/
+│   └── generator_210_keras3.keras   # Trained generator (epoch 210)
+├── models/                       # GravitySpy CNN weights (gitignored — see below)
+├── data/                         # Training data (gitignored — see below)
+└── environment.yml
+```
+
+## Setup
+
+```bash
+conda env create -f environment.yml
+conda activate cdvgan
+```
+
+The environment installs TensorFlow, Keras 3, GWpy, PyCBC, umap-learn, and GravitySpy.
+
+> **Note:** `environment.yml` targets Apple Silicon (tensorflow-macos / tensorflow-metal). On Linux/HPC replace those with `tensorflow` and remove `tensorflow-metal`.
+
+## Data
+
+The training data (~2.3 GB) is not included in this repository.
+
+**Download from Zenodo:** *(link TBD — will be added before publication)*
+
+Place the downloaded files in `data/`:
+
+```
+data/
+├── glitch_GAN_samples_scaled_balanced.npy   # (N, 8192) float32 signals
+├── glitch_GAN_labels_balanced.npy           # (N, 7) one-hot labels
+└── glitch_GAN_label_order.npy               # class name ordering
+```
+
+## GravitySpy model
+
+The GravitySpy O3 CNN (`sidd-cqg-paper-O3-model.h5`) is not included. It ships with the `gravityspy` package or can be found in a local GravitySpy clone.
+
+1. Install GravitySpy: `pip install gravityspy`
+2. Copy the model to `models/sidd-cqg-paper-O3-model.h5`
+3. Set `PATH_TO_REPO` in `evaluation.ipynb` to your GravitySpy clone path
+
+## Training
+
+```bash
+python -m cdvgan.tf.train \
+    --data-dir data/ \
+    --variant cDVGAN \
+    --epochs 500 \
+    --output-dir GAN_outputs/
+```
+
+See `src/cdvgan/tf/train.py` for all options.
+
+## Evaluation
+
+Open `evaluation.ipynb` and run all cells. The notebook:
+
+1. Loads real glitch data and the trained generator
+2. Visualises real vs generated waveforms
+3. Embeds real and generated signals jointly in 3D UMAP space (correlation metric)
+4. Injects generated signals into whitened H1 background and classifies with GravitySpy
+
+## Citation
+
+*(BibTeX will be added upon publication)*

glitchgan-0.1.0/docs/_static/custom.css

@@ -0,0 +1,120 @@
+/* ── GlitchGAN custom dark theme ─────────────────────────────────────── */
+
+/* Force dark mode as default */
+:root {
+    color-scheme: dark;
+}
+
+/* Code blocks */
+[data-theme="dark"] div[class*="highlight"] {
+    background: #161b27;
+    border: 1px solid #2a3147;
+    border-radius: 6px;
+}
+
+[data-theme="dark"] pre {
+    background: #161b27 !important;
+}
+
+/* Inline code */
+[data-theme="dark"] code.literal {
+    background: #1c2333;
+    border: 1px solid #2a3147;
+    border-radius: 4px;
+    color: #79c0ff;
+    padding: 1px 5px;
+}
+
+/* Tables */
+[data-theme="dark"] table.docutils {
+    border: 1px solid #2a3147;
+    border-radius: 6px;
+    overflow: hidden;
+}
+
+[data-theme="dark"] table.docutils th {
+    background: #161b27;
+    color: #e6edf3;
+    border-bottom: 2px solid #2a3147;
+}
+
+[data-theme="dark"] table.docutils td {
+    border-color: #2a3147;
+}
+
+[data-theme="dark"] table.docutils tr:hover td {
+    background: #1c2333;
+}
+
+/* Admonition boxes */
+[data-theme="dark"] .admonition {
+    border-radius: 6px;
+    border-left: 4px solid var(--color-brand-primary);
+    background: #161b27;
+}
+
+[data-theme="dark"] .admonition.note {
+    border-left-color: #58a6ff;
+}
+
+[data-theme="dark"] .admonition.warning {
+    border-left-color: #d29922;
+}
+
+[data-theme="dark"] .admonition.tip {
+    border-left-color: #3fb950;
+}
+
+/* Sidebar logo / title */
+.sidebar-brand-text {
+    font-weight: 700;
+    letter-spacing: 0.02em;
+}
+
+/* Content headings */
+[data-theme="dark"] h1,
+[data-theme="dark"] h2,
+[data-theme="dark"] h3 {
+    color: #e6edf3;
+}
+
+[data-theme="dark"] h1 {
+    border-bottom: 1px solid #2a3147;
+    padding-bottom: 0.3em;
+}
+
+/* API reference member entries */
+[data-theme="dark"] dl.py dt {
+    background: #161b27;
+    border-left: 3px solid #58a6ff;
+    border-radius: 0 4px 4px 0;
+    padding: 4px 8px;
+    color: #79c0ff;
+}
+
+/* Search bar */
+[data-theme="dark"] input[type="search"] {
+    background: #161b27;
+    border: 1px solid #2a3147;
+    color: #e6edf3;
+    border-radius: 6px;
+}
+
+/* Scrollbar */
+[data-theme="dark"] ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+}
+
+[data-theme="dark"] ::-webkit-scrollbar-track {
+    background: #0d1117;
+}
+
+[data-theme="dark"] ::-webkit-scrollbar-thumb {
+    background: #2a3147;
+    border-radius: 3px;
+}
+
+[data-theme="dark"] ::-webkit-scrollbar-thumb:hover {
+    background: #58a6ff;
+}

glitchgan-0.1.0/docs/conf.py

@@ -0,0 +1,83 @@
+import os
+import shutil
+
+# Auto-copy notebooks into docs/notebooks/ so Sphinx can include them in the
+# toctree (Sphinx cannot reference files outside its source directory).
+# docs/notebooks/ is gitignored — the canonical copies live in notebooks/.
+_here = os.path.dirname(__file__)
+_nb_src = os.path.join(_here, "..", "notebooks")
+_nb_dst = os.path.join(_here, "notebooks")
+os.makedirs(_nb_dst, exist_ok=True)
+for _nb in [
+    "evaluation.ipynb",
+    "gspy_classification.ipynb",
+    "inject_into_detector_noise.ipynb",
+]:
+    _src = os.path.join(_nb_src, _nb)
+    if os.path.exists(_src):
+        shutil.copy(_src, os.path.join(_nb_dst, _nb))
+
+project = "GlitchGAN"
+author = "Tom Dooney"
+copyright = "2026, Tom Dooney"
+html_title = "GlitchGAN"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",       # Google/NumPy-style docstrings
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "autoapi.extension",
+    "myst_parser",               # Markdown support
+    "nbsphinx",                  # Render Jupyter notebooks
+]
+
+autoapi_dirs = ["../src"]
+autoapi_type = "python"
+autoapi_options = ["members", "undoc-members", "show-inheritance"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy":  ("https://numpy.org/doc/stable", None),
+}
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+html_theme_options = {
+    "dark_css_variables": {
+        "--color-background-primary":   "#0f1117",
+        "--color-background-secondary": "#161b27",
+        "--color-background-hover":     "#1c2333",
+        "--color-background-border":    "#2a3147",
+        "--color-brand-primary":        "#58a6ff",
+        "--color-brand-content":        "#79c0ff",
+        "--color-foreground-primary":   "#e6edf3",
+        "--color-foreground-secondary": "#8b949e",
+        "--color-foreground-muted":     "#6e7681",
+        "--color-foreground-border":    "#30363d",
+        "--color-sidebar-background":               "#0d1117",
+        "--color-sidebar-background-border":        "#21262d",
+        "--color-sidebar-brand-text":               "#e6edf3",
+        "--color-sidebar-caption-text":             "#8b949e",
+        "--color-sidebar-link-text":                "#c9d1d9",
+        "--color-sidebar-link-text--top-level":     "#e6edf3",
+        "--color-sidebar-item-background--current": "#1f2937",
+        "--color-sidebar-item-background--hover":   "#1c2333",
+        "--color-sidebar-item-expander-background--hover": "#1c2333",
+        "--color-inline-code-background": "#1c2333",
+        "--color-admonition-background":  "#161b27",
+    },
+    "light_css_variables": {
+        "--color-brand-primary": "#0969da",
+        "--color-brand-content": "#0969da",
+    },
+    "navigation_with_keys": True,
+}
+
+exclude_patterns = ["_build", "**/_build", "**.ipynb_checkpoints"]
+
+# Do not re-execute notebooks during the docs build
+nbsphinx_execute = "never"