Module Overview

PycWB is built from ~40 self-contained modules organized by pipeline stage. Each module lives in pycwb/modules/ with its own tests/ subdirectory and communicates through plain Python objects and NumPy arrays.

For the full auto-generated API reference, see pycwb.modules.

Tip

Modules marked (legacy) depend on ROOT/C++ cWB-core bindings and are being phased out in favour of native Python equivalents. Modules marked (experimental) are under active development and not yet production-ready.

Data I/O

Module	Description
read_data	Reads GW strain data from frame files (GWF), online NDS2 servers via gwpy, or generates synthetic noise for simulations. Also supports MDC (mock data challenge) injection I/O and data quality flag checking.
injection	Generates and schedules simulated GW signal injections. Builds injection parameter lists from config, handles sky distribution sampling, time-of-arrival distributions, and assigns injections to specific job segments and trials.
gwosc	Interfaces with the GW Open Science Center (GWOSC) API. Retrieves public event metadata (GPS time, detectors, science segments) and downloads frame files for known GW events.
cwb_results	Reads and summarizes ROOT/C++ cWB liveTime ROOT files. Computes live-time statistics (total seconds, losses, min/max, counts per threshold). (legacy — ROOT-backed)
gracedb	Interfaces with LIGO/Virgo’s GraceDB alert system. Retrieves superevent metadata and GPS times, and uploads online search triggers as new GraceDB events for rapid follow-up.
noise	Generates coloured Gaussian noise from arbitrary PSDs using lalsimulation.SimNoise (same engine as PyCBC). Loads PSDs from text files and evaluates analytic noise models (aLIGO, Einstein Telescope, etc.).

Signal Conditioning

Module	Description
data_conditioning	Pure-Python data conditioning pipeline: regression (line removal) followed by whitening (wavelet-based or MESA). Operates per-lag on native NumPy time series. The production conditioning engine.
data_conditioning_root	ROOT-backed data conditioning using cWB C++ regression and whitening routines via ROOT bindings. Supports parallel processing with multiprocessing. (legacy — ROOT-backed)

Coherence & Clustering

Module	Description
coherence_native	Production coherence engine. JAX-accelerated WDM time→frequency transforms, max-energy computation, threshold-based pixel selection, veto application, and single-resolution pixel clustering. Builds lag plans from config.
coherence_root	ROOT-backed coherence wrapping cWB’s C++ network::getNetworkPixels and network::cluster. Loops over resolution levels and lags using ROOT WSeries/WDM objects. (legacy — ROOT-backed)
clustering	Next-generation pixel clustering algorithms: connected components, DBSCAN, HDBSCAN, OPTICS, and MRA weighted-graph clustering. (experimental — not yet implemented)
super_cluster_native	Native multi-resolution super-clustering. Merges pixel clusters across resolution levels, applies sub-net cuts, and defragments using Numba-accelerated link-matrix computation.
super_cluster_root	ROOT-backed super-clustering wrapping cWB’s netcluster::supercluster. Handles sparse table creation, sky-map resolution, sub-net cuts, and defragmentation. (legacy — ROOT-backed)
sparse_series	Creates sparse time-frequency representations from fragment clusters. Extracts pixel-level data (time, frequency, amplitude, phase) from TF maps at each resolution level for efficient downstream processing.
multi_resolution_wdm	Creates and manages the Wavelet Domain Model (WDM) for all resolution levels. Validates filter lengths against segment edges and time-delay sizes. Wraps pycwb.types.wdm.WDM.

Likelihood

Module	Description
likelihoodWP	Numba-accelerated coherent likelihood on CPU. Computes sky localization (full HEALPix scan), coherent SNR, null energy, correlation, and per-cluster detection statistics using per-pixel time-delay data and antenna patterns. Uses @njit + prange for inner loops.
likelihoodWPGPU	GPU-optimized likelihood, drop-in replacement for likelihoodWP. Uses jax.vmap for batched sky scans, jax.jit compilation, and float32 throughout. Device-agnostic — runs on CPU, GPU, or TPU without code changes.
likelihood_root	ROOT-backed likelihood wrapping cWB’s C++ network::likelihood. Iterates over clusters, converting between native and ROOT types via cwb_conversions. (legacy — ROOT-backed)

Post-processing

Module	Description
postprocess	Comprehensive post-production analysis suite. Trains and evaluates XGBoost classifiers, computes efficiency curves (hrss50 via sigmoid fit), calculates false-alarm rates, runs fake open-box studies, and generates automated reports.
reconstruction	Reconstructs GW waveforms from coherent pixel sums using multi-resolution analysis (MRA). Computes injected waveform statistics, residuals, matched-filter SNR, and amplitude spectral densities (ASD).
cwb_xgboost	XGBoost-based ranking and classification of GW triggers. Reads Parquet catalogs, builds feature matrices with train/test splitting and balanced sampling, trains classifiers, and evaluates with ROC/PR curves.
autoencoder	Neural-network glitch classifier. Computes a “glitchness” score — a per-cluster metric indicating how glitch-like the reconstructed waveform is — to help reject non-astrophysical triggers.
qveto	Data quality veto metrics. Computes Qveto and Qfactor from reconstructed waveforms using zero-crossing segment-maxima analysis and time-domain energy ratios to identify glitch-like signals.
statistics	Statistical tools for GW detection efficiency. Provides sigmoid fitting (via iminuit), efficiency curve computation (hrss percentiles), chunk merging for distributed results, and efficiency plot generation.

Infrastructure & Workflow

Module	Description
catalog	Primary I/O layer. Arrow/Parquet-based trigger and event catalog with schema metadata, atomic writes via SoftFileLock, deduplication on merge, and SQL/DuckDB query support. Also provides JSON catalog format and trigger-to-simulation matching.
config_repo_parser	Parses cWB project names into structured components (observation run, chunk ID, DQ category, search path, label). Extracts GPS times from chunk files and sets up project directories with full configuration.
logger	Initializes PycWB’s structured logging. Configures log format, output destination (file/stdout), and log level. Pins noisy external libraries (JAX, Numba, matplotlib) to WARNING to keep logs readable.
workflow_utils	Trigger persistence utilities. Creates organized folder structures by job segment, trial, GPS time, and hash ID. Saves event, cluster, and skymap data as JSON and registers triggers in the Parquet catalog.
skymask	Creates circular sky masks on HEALPix grids for targeted GW searches. Converts cWB sky coordinates (phi/theta) to geographic coordinates and fills mask pixels within a specified angular radius.
superlag	Generates super-lag (slag) combinations — multi-detector time-shift patterns used for background estimation. Computes shift combinations sorted by slag distance with configurable min/max distance and offset.
xtalk	Cross-talk catalog management. Loads pre-computed crosstalk coefficient files (binary or .npz) and provides fast Numba-accelerated lookup of crosstalk coefficients for pixel pairs.
condor	Generates and submits HTCondor DAG batch jobs for distributed analysis. Creates job scripts, merge scripts, and simulation summary scripts with configurable resource requests (memory, CPUs, disk).
slurm	Generates and submits Slurm job arrays for distributed analysis. Creates job scripts with configurable partitions, constraints, and resource allocations for HPC clusters.
online	Full streaming GW search pipeline. Components: DataSource (abstract data adapter), DataAcquisitionManager (polling daemon), RingBuffer (thread-safe per-IFO buffer), TriggerHandler (deduplication + significance + GraceDB alerts), and LatencyMonitor.
plot	Visualization toolkit. Spectrograms, 1D/2D histograms, event overlays, detector antenna patterns, globe plots, fragment cluster visualization, and data quality diagnostic plots.
cwb_conversions	Bidirectional type conversion between native PycWB types (NumPy arrays, TimeSeries, FragmentCluster, PixelArrays) and ROOT/C++ cWB ROOT types (wavearray, WSeries, netcluster, sseries).
cwb_interop	Creates standalone cWB working directories for direct numerical comparison between PycWB and ROOT/C++ cWB runs. Generates equivalent user_parameters.C configs, frame file lists, and DQ files.
external_module_manager	Manages installation and versioning of external PycWB modules from Git repositories. Loads module config from YAML, checks existence, and pulls/clones external modules into the PycWB modules directory.
job_segment	Constructs the analysis job segmentation. Reads DQ segment lists, builds job segments with frame file selection, injection scheduling, and super-lag generation. Handles flattening by trial index and CAT2 veto windows.