inspect

File inspection and metadata functions.

ChannelInfo dataclass

ChannelInfo(name: str, type: str, dtype: dtype, sample_rate: float, n_samples: int, unit: str, data_valid: int = 0)

Metadata about a single channel in a GWF file.

Attributes:

Name	Type	Description
name	str	Channel name (e.g., 'H1:LOSC-STRAIN')
type	str	Channel type: 'adc', 'proc', or 'sim'
dtype	dtype	NumPy dtype of the channel samples (e.g., np.dtype('float64')).
sample_rate	float	Sampling rate in Hz
n_samples	int	Number of samples in the channel
unit	str	Physical unit of the data (e.g., 'strain')
data_valid	int	Raw dataValid flag for ADC channels in the inspected frame. Nonzero means the channel data is invalid. Always 0 for proc and sim channels, which carry no dataValid flag.

dtype_name property

dtype_name: str

Human-readable name for the data type (e.g., 'float64').

is_valid property

is_valid: bool

Whether the channel data is valid (dataValid == 0).

get_channel_details

get_channel_details(filename: str | PathLike[str], frame_index: int = 0) -> list[ChannelInfo]

Get detailed metadata for all channels in a GWF file.

Reads channel headers (without decompressing data) to extract sample rate, data type, sample count, and units for each channel.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required
frame_index	int	Frame index to read metadata from (default: 0)	0

Returns:

Name	Type	Description
details	list[ChannelInfo]	List of channel metadata, ordered by type (adc, proc, sim)

Examples:

>>> details = gwframe.get_channel_details('data.gwf')
>>> for ch in details:
...     print(f"{ch.name}: {ch.dtype_name} @ {ch.sample_rate} Hz")

Source code in gwframe/inspect.py

def get_channel_details(
    filename: str | PathLike[str],
    frame_index: int = 0,
) -> list[ChannelInfo]:
    """
    Get detailed metadata for all channels in a GWF file.

    Reads channel headers (without decompressing data) to extract sample rate,
    data type, sample count, and units for each channel.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file
    frame_index : int, optional
        Frame index to read metadata from (default: 0)

    Returns
    -------
    details : list[ChannelInfo]
        List of channel metadata, ordered by type (adc, proc, sim)

    Examples
    --------
    >>> details = gwframe.get_channel_details('data.gwf')
    >>> for ch in details:
    ...     print(f"{ch.name}: {ch.dtype_name} @ {ch.sample_rate} Hz")
    """
    path = fspath(filename)
    stream = _core.IFrameFStream(path)
    toc = stream.get_toc()
    return _get_channel_details_from_stream(stream, toc, frame_index)

get_channels

get_channels(filename: str | PathLike[str]) -> list[str]

Get a list of all channels in a GWF file.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
channels	list[str]	List of all channel names

Examples:

>>> channels = gwframe.get_channels('data.gwf')
>>> print(f"Found {len(channels)} channels")
>>> for channel in channels:
...     print(channel)

Source code in gwframe/inspect.py

def get_channels(filename: str | PathLike[str]) -> list[str]:
    """
    Get a list of all channels in a GWF file.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    channels : list[str]
        List of all channel names

    Examples
    --------
    >>> channels = gwframe.get_channels('data.gwf')
    >>> print(f"Found {len(channels)} channels")
    >>> for channel in channels:
    ...     print(channel)
    """
    stream = _core.IFrameFStream(fspath(filename))
    toc = stream.get_toc()
    return [*toc.get_adc(), *toc.get_proc(), *toc.get_sim()]

get_channels_by_type

get_channels_by_type(filename: str | PathLike[str]) -> dict[str, list[str]]

Get channel names grouped by type (adc, proc, sim).

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
channels	dict[str, list[str]]	Dictionary with keys 'adc', 'proc', 'sim' mapping to channel name lists

Examples:

>>> by_type = gwframe.get_channels_by_type('data.gwf')
>>> print(f"ADC channels: {len(by_type['adc'])}")
>>> print(f"Proc channels: {len(by_type['proc'])}")

Source code in gwframe/inspect.py

def get_channels_by_type(
    filename: str | PathLike[str],
) -> dict[str, list[str]]:
    """
    Get channel names grouped by type (adc, proc, sim).

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    channels : dict[str, list[str]]
        Dictionary with keys 'adc', 'proc', 'sim' mapping to channel name lists

    Examples
    --------
    >>> by_type = gwframe.get_channels_by_type('data.gwf')
    >>> print(f"ADC channels: {len(by_type['adc'])}")
    >>> print(f"Proc channels: {len(by_type['proc'])}")
    """
    stream = _core.IFrameFStream(fspath(filename))
    toc = stream.get_toc()
    return {
        "adc": list(toc.get_adc()),
        "proc": list(toc.get_proc()),
        "sim": list(toc.get_sim()),
    }

get_info

get_info(filename: str | PathLike[str]) -> FrameFileInfo

Get metadata about a GWF file.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
info	FrameFileInfo	Structured metadata containing: - num_frames: number of frames in file - channels: list of all channel names - frames: list of FrameInfo objects with complete frame metadata

Examples:

>>> info = gwframe.get_info('data.gwf')
>>> print(f"File contains {info.num_frames} frames")
>>> print(f"Frame 0: {info.frames[0].name} at GPS {info.frames[0].start}")
>>> print(f"Channels: {', '.join(info.channels)}")

Source code in gwframe/inspect.py

def get_info(filename: str | PathLike[str]) -> FrameFileInfo:
    """
    Get metadata about a GWF file.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    info : FrameFileInfo
        Structured metadata containing:
        - num_frames: number of frames in file
        - channels: list of all channel names
        - frames: list of FrameInfo objects with complete frame metadata

    Examples
    --------
    >>> info = gwframe.get_info('data.gwf')
    >>> print(f"File contains {info.num_frames} frames")
    >>> print(f"Frame 0: {info.frames[0].name} at GPS {info.frames[0].start}")
    >>> print(f"Channels: {', '.join(info.channels)}")
    """
    stream = _core.IFrameFStream(fspath(filename))
    toc = stream.get_toc()
    return _build_info_from_stream(stream, toc, fspath(filename))

get_invalid_channels

get_invalid_channels(filename: str | PathLike[str]) -> dict[str, dict[int, int]]

Find ADC channels flagged invalid (dataValid != 0) in any frame.

Scans the channel-level dataValid flag of every ADC channel in every frame. This is a header-only read: no sample data is decompressed, so the scan is cheap even for large files. Proc and sim channels carry no dataValid flag and are never included.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
invalid	dict[str, dict[int, int]]	Mapping of channel name to {frame_index: raw dataValid value} for every ADC channel and frame where dataValid != 0. Empty if all channels are valid in all frames.

Examples:

>>> invalid = gwframe.inspect.get_invalid_channels('data.gwf')
>>> for channel, frames in invalid.items():
...     print(f"{channel}: invalid in frames {sorted(frames)}")

Source code in gwframe/inspect.py

def get_invalid_channels(
    filename: str | PathLike[str],
) -> dict[str, dict[int, int]]:
    """
    Find ADC channels flagged invalid (dataValid != 0) in any frame.

    Scans the channel-level dataValid flag of every ADC channel in every
    frame. This is a header-only read: no sample data is decompressed, so
    the scan is cheap even for large files. Proc and sim channels carry no
    dataValid flag and are never included.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    invalid : dict[str, dict[int, int]]
        Mapping of channel name to ``{frame_index: raw dataValid value}``
        for every ADC channel and frame where dataValid != 0. Empty if all
        channels are valid in all frames.

    Examples
    --------
    >>> invalid = gwframe.inspect.get_invalid_channels('data.gwf')
    >>> for channel, frames in invalid.items():
    ...     print(f"{channel}: invalid in frames {sorted(frames)}")
    """
    stream = _core.IFrameFStream(fspath(filename))
    toc = stream.get_toc()
    num_frames = stream.get_number_of_frames()

    invalid: dict[str, dict[int, int]] = {}
    for ch_name in toc.get_adc():
        for frame_index in range(num_frames):
            data_valid = int(
                stream.read_fr_adc_data(frame_index, ch_name).get_data_valid()
            )
            if data_valid:
                invalid.setdefault(ch_name, {})[frame_index] = data_valid
    return invalid