gwframe

High-level Python library to work with gravitational-wave frame (GWF) files, based on framecpp

Resources

• Documentation
• Source Code
• Issue Tracker

Installation

With pip:

pip install gwframe

Pre-built wheels are available for:

With conda:

conda install -c conda-forge gwframe

Features

• Multi-frame writing - Write multiple frames to a single file
• Multi-channel support - Read all channels or specific lists with a single call
• Masked array support - Detect and propagate invalid-data flags as NumPy masked arrays
• Self-contained wheels - No external dependencies required for pip installation

Quickstart

Reading frames

import gwframe

# Read single channel
data = gwframe.read('data.gwf', 'L1:GWOSC-16KHZ_R1_STRAIN')
print(f"Read {len(data.array)} samples at {data.sample_rate} Hz")
print(f"Time range: {data.start} to {data.start + data.duration}")

# Read all channels
channels = gwframe.read('data.gwf', channels=None)
for name, timeseries in channels.items():
    print(f"{name}: {len(timeseries.array)} samples")

# Time-based slicing (automatically stitches multiple frames)
data = gwframe.read('multi_frame.gwf', 'L1:STRAIN',
                    start=1234567890.0, end=1234567900.0)

Writing single frames

import gwframe
import numpy as np

data = np.random.randn(16384)
gwframe.write('output.gwf', data, start=1234567890.0,
              sample_rate=16384, name='L1:TEST')

Writing multiple frames

import gwframe
import numpy as np

# Write multiple frames to a single file
with gwframe.FrameWriter('multi_frame.gwf') as writer:
    for i in range(20):
        data = np.random.randn(16384)
        writer.write(data, start=1234567890.0 + i,
                     sample_rate=16384, name='L1:TEST')

# Or without a context manager
writer = gwframe.FrameWriter('multi_frame.gwf')
writer.open()
for i in range(20):
    data = np.random.randn(16384)
    writer.write(data, start=1234567890.0 + i,
                 sample_rate=16384, name='L1:TEST')
writer.close()

Inspecting frames

From the command line:

gwframe inspect data.gwf            # file summary
gwframe inspect -v data.gwf         # + channel listing
gwframe inspect -vvv data.gwf       # + sample rates, dtypes, units, validity
gwframe inspect -vvvv data.gwf      # + invalid-channel report
gwframe inspect -vvvvv data.gwf     # + data preview (reads all data)

Or from Python:

import gwframe

# Get frame information
info = gwframe.get_info('data.gwf')
print(f"Number of frames: {info.num_frames}")
for frame in info.frames:
    print(f"Frame {frame.index}: {frame.name} at GPS {frame.start}, duration {frame.duration}s")

# List all channels
channels = gwframe.get_channels('data.gwf')
for channel in channels:
    print(channel)

Advanced: Full control with Frame objects

import gwframe
import numpy as np

# Create frame with multiple channels and metadata
frame = gwframe.Frame(
    start=1234567890.0,
    duration=1.0,
    name='L1',
    run=1
)

# Add channels
strain = np.random.randn(16384)
frame.add_channel('L1:STRAIN', strain,
                  sample_rate=16384,
                  unit='strain',
                  channel_type='proc')

aux = np.random.randn(1024).astype(np.float32)
frame.add_channel('L1:AUX', aux,
                  sample_rate=1024,
                  unit='counts',
                  channel_type='adc')

# Add metadata
frame.add_history('gwframe', 'Created with gwframe')

# Write with custom compression
frame.write('output.gwf', compression=gwframe.Compression.GZIP)

Handling invalid / masked data

ADC channels in GWF files can carry a data-valid flag indicating the entire channel is suspect. gwframe surfaces this through NumPy masked arrays:

import gwframe

# By default, reading a channel flagged invalid raises an error
try:
    data = gwframe.read('data.gwf', 'H1:ADC-CHANNEL')
except gwframe.InvalidDataError as e:
    print(e)  # suggests allow_invalid=True

# Allow invalid data — returns a masked array
data = gwframe.read('data.gwf', 'H1:ADC-CHANNEL', allow_invalid=True)
if isinstance(data.array, np.ma.MaskedArray):
    print(f"{data.array.count()} valid samples out of {len(data.array)}")

# Write a masked array — ADC channels preserve the flag,
# proc/sim channels warn that the mask is discarded
masked = np.ma.MaskedArray(values, mask=quality_mask)
frame = gwframe.Frame(start=1234567890.0, duration=1.0, name='H1')
frame.add_channel('H1:ADC-CHANNEL', masked,
                  sample_rate=16384, channel_type='adc')

# Control behavior when mask fidelity is lost
frame.add_channel('H1:PROC-CHANNEL', masked,
                  sample_rate=16384, channel_type='proc',
                  on_mask_loss='ignore')  # or 'warn' (default), 'raise'

CLI Tools

gwframe includes a command-line interface for common frame manipulation tasks:

# Inspect a frame file (add -v, -vv, -vvv for more detail)
gwframe inspect data.gwf

# Rename channels
gwframe rename input.gwf -o output.gwf -m "L1:OLD=>L1:NEW"

# Combine channels from multiple files
gwframe combine file1.gwf file2.gwf -o output/

# Keep only specific channels
gwframe select input.gwf -o output.gwf -c L1:STRAIN

# Remove unwanted channels
gwframe drop input.gwf -o output.gwf -c L1:UNWANTED

# Change frame duration
gwframe resize input.gwf -o output/ -d 4.0

# Replace NaN or sentinel values
gwframe impute input.gwf -o output.gwf --fill-value 0.0

# Update channel data from another file
gwframe replace base.gwf --update new.gwf -o output/ -c L1:STRAIN

# Change compression settings
gwframe recompress input.gwf -o output.gwf -c GZIP -l 9

# Chain stages in a single pass, e.g. raw -> curated dataset
gwframe transform raw/ -o curated/ --compression GZIP --level 9 \
    rename -m "L1:GDS-CALIB_STRAIN=>L1:STRAIN" \
    drop -c L1:DEBUG \
    resize -d 4
gwframe transform raw/ -o curated/ --dry-run @curated.recipe   # preview a recipe

# Check two files (or directories) for consistency of data and metadata
gwframe validate a.gwf b.gwf
gwframe validate dir1/ dir2/ --common          # only compare what both sides have
gwframe validate a.gwf b.gwf --metadata-only   # skip sample data (faster)
gwframe validate a.gwf b.gwf --atol 1e-9       # tolerate small float differences

All commands support batch processing with directories and glob patterns. See the CLI documentation for detailed usage and examples.