types

Data types and constants for gwframe.

ChannelType

Bases: str, Enum

Channel data types in GWF files.

• PROC: Processed data (FrProcData)
• ADC: Raw ADC data (FrAdcData)
• SIM: Simulated data (FrSimData)

Compression

Bases: IntEnum

Compression schemes for GWF files.

See LIGO-T970130 for details on compression algorithms.

Standard modes: - RAW: No compression - GZIP: Standard GZIP compression - DIFF_GZIP: Differentiate data then apply GZIP - ZERO_SUPPRESS_WORD_2: Zero-suppress 2-byte (16-bit) words - ZERO_SUPPRESS_WORD_4: Zero-suppress 4-byte (32-bit) words - ZERO_SUPPRESS_WORD_8: Zero-suppress 8-byte (64-bit) words

Meta modes (adaptive): - ZERO_SUPPRESS_OTHERWISE_GZIP: Zero-suppress integers, GZIP floats (recommended) - BEST_COMPRESSION: Try all modes, use best compression ratio

Aliases: - ZERO_SUPPRESS_SHORT: Alias for ZERO_SUPPRESS_WORD_2 - ZERO_SUPPRESS_INT_FLOAT: Alias for ZERO_SUPPRESS_WORD_4

DetectorLocation

Bases: IntEnum

Detector location identifiers for GWF files.

These constants identify specific gravitational wave detectors and are used with the GetDetector function.

• G1: GEO600 (Germany)
• H1: LIGO Hanford 4km (USA)
• H2: LIGO Hanford 2km (USA, decommissioned)
• K1: KAGRA (Japan)
• L1: LIGO Livingston 4km (USA)
• T1: TAMA300 (Japan, decommissioned)
• V1: Virgo (Italy)

FrProcDataSubType

Bases: IntEnum

Subtype classification for FrProcData structures.

Provides detailed information about the data processing or analysis type.

FrProcDataType

Bases: IntEnum

Type classification for FrProcData structures.

Indicates the dimensionality and structure of processed data.

FrameFileInfo dataclass

FrameFileInfo(num_frames: int, channels: list[str], frames: list[FrameInfo], compression: int, frame_spec: int | None = None)

Complete metadata about a GWF file.

This dataclass holds file-level and frame-level metadata for a GWF file.

Attributes:

Name	Type	Description
num_frames	int	Total number of frames in the file
channels	list[str]	List of all channel names in the file
frames	list[FrameInfo]	List of metadata for each frame
compression	int	Compression scheme used for all channels in the file (e.g., Compression.GZIP)
frame_spec	int or None	Frame specification version (e.g., 8). None if unknown.

Examples:

>>> info = gwframe.get_info('data.gwf')
>>> print(f"File contains {info.num_frames} frames")
>>> print(f"Channels: {', '.join(info.channels)}")
>>> print(f"Frame spec: v{info.frame_spec}")
>>> print(f"Compression: {Compression(info.compression).name}")
>>> # Preserve compression when writing
>>> with FrameWriter('output.gwf', **info.compression_settings) as writer:
...     pass

compression_settings property

compression_settings: dict[str, int]

Return compression settings as kwargs for FrameWriter.

Returns:

Type	Description
dict[str, int]	Compression settings suitable for FrameWriter constructor

Examples:

>>> info = gwframe.get_info('input.gwf')
>>> with gwframe.FrameWriter(
...     'output.gwf', **info.compression_settings
... ) as writer:
...     # Frames written with same compression as input file
...     pass

FrameInfo dataclass

FrameInfo(index: int, start: float, duration: float, name: str, run: int, frame_number: int)

Metadata about a single frame in a GWF file.

This dataclass holds metadata for a frame without the actual channel data.

Attributes:

Name	Type	Description
index	int	Frame index in the file (0-based)
start	float	Start time in GPS seconds
duration	float	Frame duration in seconds
name	str	Frame name (e.g., 'H1', 'L1')
run	int	Run number (negative for simulated data)
frame_number	int	Frame sequence number

Examples:

>>> info = gwframe.get_info('data.gwf')
>>> frame = info.frames[0]
>>> print(f"Frame {frame.index}: {frame.name} at GPS {frame.start}")

FrameSpec

Bases: IntEnum

Frame specification version for GWF files.

Controls which version of the frame format is used when writing:

• V8: Frame spec v8 (default). ADC channels support a channel-level data-valid flag; proc/sim channels have no masking support.

OnMaskLoss

Bases: str, Enum

Behavior when mask information cannot be preserved in the frame format.

On frame spec versions < 9, only ADC channels support a (channel-level) data-valid flag. Proc and sim channels have no masking support, and ADC masking is per-channel (not per-sample). This enum controls what happens when a masked array is written to a channel type that cannot preserve the full mask.

TimeSeries dataclass

TimeSeries(array: NDArray[floating], name: str, dtype: dtype, start: float, dt: float, duration: float, sample_rate: float, unit: str, type: str, mask: NDArray[bool_] | None = None)

Time series data from a GWF channel.

This dataclass holds the array data and metadata for a channel read from a GWF file.

Attributes:

Name	Type	Description
array	ndarray	NumPy array containing the time series data
name	str	Channel name (e.g., 'H1:LOSC-STRAIN')
dtype	dtype	NumPy dtype of the samples. Always mirrors array.dtype.
start	float	Start time in GPS seconds
dt	float	Sample spacing in seconds
duration	float	Total duration in seconds
sample_rate	float	Sampling rate in Hz (1/dt)
unit	str	Physical unit of the data (e.g., 'strain')
type	str	Channel type: 'proc' (processed), 'adc' (raw ADC), or 'sim' (simulated)
mask	ndarray or None	Boolean mask where True indicates invalid samples. None when all samples are valid. Only populated when reading with allow_invalid=True and the file contains dataValid flags.

Examples:

>>> data = gwframe.read('data.gwf', 'H1:LOSC-STRAIN')
>>> print(f"Channel: {data.name}")
>>> print(f"Duration: {data.duration} s at {data.sample_rate} Hz")
>>> print(f"Data shape: {data.array.shape}")
>>> # Check for invalid samples
>>> if data.mask is not None:
...     print(f"Invalid samples: {data.mask.sum()}")

to_masked

to_masked() -> NDArray[floating] | MaskedArray

Return data as a masked array if a mask is present, otherwise plain array.

This is useful when passing data to APIs that understand masked arrays, or when you want numpy operations to automatically skip invalid samples.

Returns:

Type	Description
MaskedArray or ndarray	Masked array if mask is set, plain array otherwise.

Source code in gwframe/types.py

def to_masked(self) -> npt.NDArray[np.floating] | np.ma.MaskedArray:
    """Return data as a masked array if a mask is present, otherwise plain array.

    This is useful when passing data to APIs that understand masked arrays,
    or when you want numpy operations to automatically skip invalid samples.

    Returns
    -------
    np.ma.MaskedArray or np.ndarray
        Masked array if ``mask`` is set, plain array otherwise.
    """
    if self.mask is not None:
        return np.ma.MaskedArray(self.array, mask=self.mask)
    return self.array

frvect_to_dtype

frvect_to_dtype(code: int) -> dtype

Map a frameCPP FrVect type code to a NumPy dtype.

Raises:

Type	Description
ValueError	If the code does not correspond to a NumPy-representable type.

Source code in gwframe/types.py

def frvect_to_dtype(code: int) -> np.dtype:
    """Map a frameCPP FrVect type code to a NumPy dtype.

    Raises
    ------
    ValueError
        If the code does not correspond to a NumPy-representable type.
    """
    try:
        return _FRVECT_TO_DTYPE[code]
    except KeyError as exc:
        msg = f"Unsupported frameCPP vector type code: {code}"
        raise ValueError(msg) from exc