CLI Tools¶

gwframe provides a comprehensive command-line interface for manipulating GWF files without writing Python code. All commands support both single files and batch processing of directories.

Common Options¶

All commands support these common patterns:

File or directory input: Pass individual files or directories
Batch processing: Use glob patterns like data/*.gwf
Recursive processing: Use -r/--recursive to process subdirectories
In-place editing: Use -i/--in-place to modify files directly
Output control: Specify output directory with -o/--output-dir

Tip

Use gwframe COMMAND --help to see detailed help for any command.

Commands¶

`rename` - Rename Channels¶

Rename channels within frame files while preserving all other data.

Usage:

gwframe rename INPUT... -m "OLD=>NEW" [-o OUTPUT] [-i] [-r]

Options:

-m, --map TEXT - Channel mapping in format OLD=>NEW (required, can specify multiple)
-o, --output-dir PATH - Output directory or file
-i, --in-place - Modify files in place
-r, --recursive - Recurse into subdirectories

Examples:

Rename a single channel in one file:

gwframe rename input.gwf -o output.gwf -m "L1:OLD_CHAN=>L1:NEW_CHAN"

Rename multiple channels:

gwframe rename input.gwf -o output/ \
    -m "L1:CHAN1=>L1:NEW1" \
    -m "L1:CHAN2=>L1:NEW2"

Process entire directory:

gwframe rename data/ -o output/ -m "L1:GDS-CALIB_STRAIN=>L1:STRAIN"

In-place rename (modifies originals):

gwframe rename data/*.gwf --in-place -m "L1:OLD=>L1:NEW"

`combine` - Combine Channels¶

Merge channels from multiple sources covering the same time period. Useful for combining data from different acquisition systems or adding calibrated channels to raw data files.

Usage:

gwframe combine SOURCE1 SOURCE2 [SOURCE3...] -o OUTPUT [--keep CHAN] [--drop CHAN]

Options:

-o, --output-dir PATH - Output directory (required)
-k, --keep TEXT - Only include these channels (can specify multiple)
-d, --drop TEXT - Exclude these channels (can specify multiple)

Examples:

Combine two files:

gwframe combine raw_data.gwf calibrated.gwf -o output/

Combine directories (matches frame files by time):

gwframe combine raw_dir/ calibrated_dir/ -o combined/

Combine with channel filtering (keep only specific channels):

gwframe combine dir1/ dir2/ dir3/ -o output/ \
    --keep L1:STRAIN \
    --keep L1:LSC-DARM_IN1_DQ

Combine and drop unwanted channels:

gwframe combine source1/ source2/ -o output/ \
    --drop L1:TEMPORARY_CHANNEL

Warning

All sources must cover the same time ranges. Mismatched time ranges will cause an error.

`select` - Keep Specific Channels¶

Keep only specified channels in frame files, removing all others.

Usage:

gwframe select INPUT... -c CHANNEL [-o OUTPUT] [-i] [-r]

Options:

-c, --channel TEXT - Channel(s) to keep (required, can specify multiple)
-o, --output-dir PATH - Output directory or file
-i, --in-place - Modify files in place
-r, --recursive - Recurse into subdirectories

Examples:

Keep a single channel:

gwframe select input.gwf -o output.gwf -c L1:STRAIN

Keep multiple channels:

gwframe select input.gwf -o output.gwf \
    -c L1:STRAIN \
    -c L1:LSC-DARM_IN1_DQ

Process directory and keep only selected channels:

gwframe select data/ -o filtered/ -c L1:STRAIN --recursive

In-place selection (modifies originals):

gwframe select data/*.gwf --in-place -c L1:STRAIN

`drop` - Remove Channels¶

Remove specified channels from frame files. This is the inverse of select.

Usage:

gwframe drop INPUT... -c CHANNEL [-o OUTPUT] [-i] [-r]

Options:

-c, --channel TEXT - Channel(s) to drop (required, can specify multiple)
-o, --output-dir PATH - Output directory or file
-i, --in-place - Modify files in place
-r, --recursive - Recurse into subdirectories

Examples:

Drop single channel:

gwframe drop input.gwf -o output.gwf -c L1:UNWANTED_CHANNEL

Drop multiple channels:

gwframe drop input.gwf -o output.gwf \
    -c L1:CHAN1 \
    -c L1:CHAN2 \
    -c L1:CHAN3

Process directory and drop channels:

gwframe drop data/ -o cleaned/ -c L1:TEMPORARY_DATA

In-place removal (modifies originals):

gwframe drop data/*.gwf --in-place -c L1:DEBUG_CHANNEL

`resize` - Change Frame Duration¶

Split or combine frames to achieve a target duration. Used to convert between different frame lengths (e.g., 64s → 4s).

Usage:

gwframe resize INPUT... -d DURATION [-o OUTPUT] [-i] [-r]

Options:

-d, --duration FLOAT - Target frame duration in seconds (required)
-o, --output-dir PATH - Output directory or file
-i, --in-place - Modify files in place
-r, --recursive - Recurse into subdirectories

Examples:

Split 64-second frames into 4-second frames:

gwframe resize input.gwf -o output/ -d 4.0

Combine 1-second frames into 16-second frames:

gwframe resize data/ -o output/ -d 16.0 --recursive

Convert entire directory:

gwframe resize original_data/ -o resized_data/ -d 8.0

Note

The total duration of input data must be evenly divisible by the target duration
All channels in the frame will be resized together
Frame metadata (GPS time, run number, etc.) is preserved

`impute` - Replace Values¶

Replace specific values (like NaN, -999, or sentinel values) with a fill value.

Usage:

gwframe impute INPUT... [-r VALUE] [-f VALUE] [-c CHANNEL] [-o OUTPUT] [-i]

Options:

-r, --replace-value FLOAT - Value to replace (default: NaN)
-f, --fill-value FLOAT - Replacement value (default: 0.0)
-c, --channel TEXT - Specific channel(s) to impute (if omitted, processes all channels)
-o, --output-dir PATH - Output directory or file
-i, --in-place - Modify files in place
--recursive - Recurse into subdirectories

Examples:

Replace NaN with zeros (default behavior):

gwframe impute input.gwf -o output.gwf

Replace specific sentinel value:

gwframe impute input.gwf -o output.gwf \
    --replace-value -999.0 \
    --fill-value 0.0

Impute only specific channels:

gwframe impute data.gwf -o clean.gwf \
    --fill-value 0.0 \
    --channel L1:STRAIN \
    --channel L1:LSC-DARM

Process directory and replace -inf values:

gwframe impute data/ -o cleaned/ \
    --replace-value -inf \
    --fill-value 0.0

Warning

The fill value is cast to the dtype of each channel, so precision may be lost for integer channels.

`replace` - Update Channel Data¶

Replace channel data in base files with updated versions from other files.

Usage:

gwframe replace BASE... --update UPDATE -o OUTPUT [-c CHANNEL] [-r]

Options:

-u, --update PATH - Source of updated channel data (required)
-o, --output-dir PATH - Output directory (required)
-c, --channel TEXT - Specific channel(s) to replace (if omitted, replaces all matching channels)
-r, --recursive - Recurse into subdirectories

Examples:

Replace all matching channels from update file:

gwframe replace base.gwf --update updated.gwf -o output/

Replace only specific channel:

gwframe replace base.gwf --update calibrated.gwf -o output/ -c L1:STRAIN

Replace data in entire directory (matches by filename/time):

gwframe replace base_dir/ --update update_dir/ -o output/ --recursive

Replace multiple specific channels:

gwframe replace data.gwf --update new_data.gwf -o output/ \
    -c L1:STRAIN \
    -c L1:LSC-DARM_IN1_DQ

Use Cases

Data fixes: Replace corrupted segments with corrected data
Reprocessing: Update specific channels while keeping others unchanged

`recompress` - Change Compression¶

Rewrite frame files with different compression settings.

Usage:

gwframe recompress INPUT... [-c TYPE] [-l LEVEL] [-o OUTPUT] [-i] [-r]

Options:

-c, --compression TEXT - Compression type (default: ZERO_SUPPRESS_OTHERWISE_GZIP)
RAW - No compression (fastest, largest)
GZIP - Standard gzip compression
DIFF_GZIP - Differentiate then gzip (good for slowly-varying data)
ZERO_SUPPRESS_OTHERWISE_GZIP - Zero-suppression with gzip fallback (recommended)
-l, --level INT - Compression level 0-9 (default: 6, higher = more compression)
-o, --output-dir PATH - Output directory or file
-i, --in-place - Modify files in place
-r, --recursive - Recurse into subdirectories

Examples:

Maximum compression for archival:

gwframe recompress input.gwf -o archive.gwf -c GZIP -l 9

Re-compress entire directory with optimal settings:

gwframe recompress data/ -o compressed/ \
    -c ZERO_SUPPRESS_OTHERWISE_GZIP \
    -l 6 \
    --recursive

`inspect` - Inspect Frame Files¶

Display metadata and channel information for a GWF file. Supports tiered verbosity to progressively reveal more detail.

Usage:

gwframe inspect FILE [-v] [-vv] [-vvv]

Verbosity levels:

Flag	Level	Shows
(none)	0	File summary: GPS range, frame/channel counts, compression, file size
`-v`	1	Add channel listing with types (adc/proc/sim)
`-vv`	2	Add per-frame table with GPS start, duration, run, frame number
`-vvv`	3	Replace simple channel listing with detailed table (sample rate, dtype, units, sample count)

Examples:

Quick file summary:

gwframe inspect data.gwf

List all channels with their types:

gwframe inspect -v data.gwf

Show channels and per-frame metadata:

gwframe inspect -vv data.gwf

Full detail including sample rates, dtypes, and units:

gwframe inspect -vvv data.gwf

Tip

Lower verbosity levels read only file-level metadata (fast even for large files). Level 3 (-vvv) reads channel headers to extract per-channel details.

Error Handling¶

Common errors and solutions:

"Channel not found"¶

Error: Channel 'L1:MISSING' not found in frame

Solution: List available channels with inspect:

gwframe inspect -v file.gwf

"Time ranges don't match"¶

Error: Source time ranges do not match

Solution: Use combine only with files covering identical time spans. Check with:

import gwframe
for file in ["file1.gwf", "file2.gwf"]:
    info = gwframe.read(file, channel_list=True)
    print(f"{file}: {info}")

"Duration not evenly divisible"¶

Error: Total duration 100.0s not evenly divisible by target 64.0s

Solution: Choose a target duration that evenly divides the input duration, or pre-process to trim data.

CLI Tools¶

Common Options¶

Commands¶

rename - Rename Channels¶

combine - Combine Channels¶

select - Keep Specific Channels¶

drop - Remove Channels¶

resize - Change Frame Duration¶

impute - Replace Values¶

replace - Update Channel Data¶

recompress - Change Compression¶

inspect - Inspect Frame Files¶

Error Handling¶

"Channel not found"¶

"Time ranges don't match"¶

"Duration not evenly divisible"¶

`rename` - Rename Channels¶

`combine` - Combine Channels¶

`select` - Keep Specific Channels¶

`drop` - Remove Channels¶

`resize` - Change Frame Duration¶

`impute` - Replace Values¶

`replace` - Update Channel Data¶

`recompress` - Change Compression¶

`inspect` - Inspect Frame Files¶